a2aproject / a2aproject/A2A

[Feat]: Official a2a CLI — consolidating community CLI efforts

Abierto
#1,929 64 comentarios 8 reacciones 0 asignados Ver en GitHub
gitvote gitvote/closed gitvote/passed
Lenguaje dominante
Shell
Estrellas
25.7k
Forks
2.6k
Merge medio
3 d 6 h
PR fusionados (30 d)
16

Descripción

## Is your feature request related to a problem? Please describe.

The A2A ecosystem has spawned several independent CLI tools for interacting with A2A agents, each with different command grammar, feature coverage, language, and distribution story:

| Implementation | Language | Notable features |
|---|---|---|
| [agntcy/slim a2acli-skill](https://github.com/agntcy/slim/tree/multicluster-demo/multicluster-demo/a2acli-skill) | Go | SLIM RPC transport, SPIRE identity auth |
| [spec-works/a2a-ask-cli](https://github.com/spec-works/plugins/blob/main/plugins/a2a-ask/skills/a2a-ask-cli/SKILL.md) | .NET | OAuth2, catalog support, AI skill packaging |
| [a2a-go internal/cli](https://github.com/a2aproject/a2a-go/tree/main/internal/cli) ([discussion #306](https://github.com/a2aproject/a2a-go/discussions/306)) | Go | Verb/noun grammar, server modes, in the official org |
| [chrishayuk/a2a-cli](https://github.com/chrishayuk/a2a-cli) | Python | Rich interactive TUI, multi-transport (HTTP/SSE/WS/STDIO) |
| [ericabouaf/a2a-cli](https://github.com/ericabouaf/a2a-cli) | TypeScript | Stdin piping, lightweight |
| [a2a-rs/a2acli](https://github.com/a2aproject/a2a-rs/tree/main/a2acli) | Rust | In the official org, single static binary |
| [a2a-swift-client](https://github.com/tolgaki/a2a-swift-client) | Swift | *Not CLI*. Impressive coverage for Authentication |

This fragmentation creates several problems:

- **Developer confusion** — there's no obvious "official" CLI to reach for when getting started with A2A
- **No standard distribution** — none can be distributed via Homebrew, winget, or similar without first designating one as canonical
- **No common AgentSkill.md** — AI coding agents (Claude Code, GitHub Copilot CLI, Cursor) need a `SKILL.md` to know how to invoke the CLI; without a canonical CLI there can be no canonical skill file, making it impossible to deliver a standard story for how coding agents interact with A2A agents
- **Duplicate effort** — community contributors are spread across multiple repos with no way to consolidate improvements

## Describe the solution you'd like

Create a new **`a2aproject/a2a-cli`** repository under the official org, housing a single canonical `a2a` CLI that the community can rally around.

**Language:** We're not prescribing a specific language, but we'd strongly encourage Go or Rust. Both produce a single self-contained binary with no runtime dependency — that's what makes Homebrew, winget, and direct GitHub Release downloads painless for end users. Languages that require Node.js, Python, or .NET to be installed first make distribution more involved.

**Initial scope — core A2A client operations:**
- `discover ` — fetch and display an agent's AgentCard (where `` may be a URL, local file, or catalog reference)
- `send "message"` — send a message; supports `--return-immediately` to get back a task reference without waiting. An open design question: streaming could be `send --stream` or a dedicated `stream` command — the latter avoids a mutually exclusive flags problem since `--stream` and `--return-immediately` cannot both apply.
- `task get ` — retrieve task details
- `task list` — list tasks with filtering
- `task cancel ` — cancel a running task
- `task subscribe ` — subscribe to task events
- Auth support: bearer token, API key, custom headers
- `-o json` output for scripting and pipeline use

**Distribution:**
- Homebrew formula (macOS/Linux)
- GitHub Releases with prebuilt binaries (macOS amd64/arm64, Linux amd64/arm64, Windows amd64)
- Direct install script
- Optionally: winget, apt, Docker image

### AgentSkill.md

Ship a well-maintained `SKILL.md` alongside the CLI, structured as an instruction document for AI coding agents. This is the primary mechanism by which tools like Claude Code, GitHub Copilot CLI, and Cursor can learn to invoke the CLI correctly. An official, maintained skill file creates a **canonical story for how coding agents interact with A2A agents** — something no individual community CLI can provide on its own.

### AI Catalog

Once the AI Catalog spec stabilises, the CLI is a natural home for catalog operations (browsing agents, registering entries, resolving agent URLs from a catalog). This is intentionally out of initial scope to avoid shipping against a moving target, but the command structure should be designed with it in mind.

### Serve mode

A `serve` mode — where the CLI can act as a simple A2A agent itself (echo, proxy, or wrapping an arbitrary command via stdin/stdout) — is a compelling feature for local testing and development. It's out of initial scope but a natural follow-on once the core client experience is established.

## Describe alternatives you've considered

- **Maintain separate CLIs per language SDK** — already the current state; leads to fragmentation and duplicate effort
- **Bless one of the existing community CLIs** — none are under the official org yet; creating a new repo provides a neutral landing point and avoids implying one contributor's work is "more official" than others'
- **Build a web-based playground instead** — a different use case; doesn't serve scripting, automation, or coding-agent integration scenarios
- **Promote `a2a-go/internal/cli` in-place** — this conflates the CLI with a specific language SDK, hurts discoverability, and doesn't give the CLI its own identity; Discussion [#306](https://github.com/a2aproject/a2a-go/discussions/306)'s command grammar and implementation could however be used as a reference starting contribution

## Additional context

- The [A2A roadmap](https://a2a-protocol.org/latest/roadmap/) calls out "Prioritize community-led development with standardized processes for contributing to tooling" — an official CLI repo fits squarely here
- The existing [a2a-inspector](https://github.com/a2aproject/a2a-inspector) and [a2a-tck](https://github.com/a2aproject/a2a-tck) repos establish the precedent for official tooling repos under the org
- [Discussion #306](https://github.com/a2aproject/a2a-go/discussions/306) in `a2a-go` contains a working Go implementation and well-considered command grammar that could serve as a reference contribution or starting point

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.