diff --git a/skills/a2a-cli/README.md b/skills/a2a-cli/README.md new file mode 100644 index 0000000..047534b --- /dev/null +++ b/skills/a2a-cli/README.md @@ -0,0 +1,102 @@ +# a2a-cli agent skill + +An [Agent Skill](https://agentskills.io/) that teaches an AI coding agent to +drive the [`a2a` CLI](https://github.com/a2aproject/a2a-cli), the command-line +client for [A2A (Agent2Agent)](https://a2a-protocol.org/) agents. + +It is one file, `SKILL.md`. Once it is installed, your agent can: + +- fetch an agent's card, +- send it a task, +- stream or poll for the result, and +- log each task it starts, so you can follow up later. + +## Prerequisite + +The skill drives the `a2a` binary; it does not install it. Install `a2a` first: + +```bash +go install github.com/a2aproject/a2a-cli@latest +``` + +Confirm it is on your `PATH`: + +```bash +a2a version +``` + +## Installation + +Fetch the one skill file into the place your agent loads skills from. Many agents +read `~/.agents/skills/`. Use `~/.gemini/config/skills/` for Google Antigravity. + +```bash +mkdir -p ~/.agents/skills/a2a-cli +wget -O ~/.agents/skills/a2a-cli/SKILL.md \ + https://raw.githubusercontent.com/a2aproject/a2a-cli/main/skills/a2a-cli/SKILL.md +``` + +## Verify + +Check the file landed: + +```bash +ls ~/.agents/skills/a2a-cli # SKILL.md +``` + +Then start a new agent session. Confirm the agent lists `a2a-cli` among its +available skills. + +## Try it — confirm the skill works + +Hand these two prompts to your agent, in order. Together they exercise the whole +path: loading the skill, starting an agent, sending a message, and logging the +task. + +**1. Start a local echo agent.** + +> Using the a2a-cli skill, start a local echo A2A agent in the background on port 9090. + +Your agent should run `a2a server --echo --port 9090 &`. Confirm it is up: + +```bash +a2a card get http://localhost:9090 +# Name: Echo Agent ... Interfaces: HTTP+JSON http://127.0.0.1:9090 +``` + +**2. Send it a message and log the task.** + +> Send "hello from a2a" to the agent at http://localhost:9090, show me the reply, and log the task. + +The echo agent returns your text, and the task lands in the log: + +```bash +cat .a2a-cli-logs/tasks.jsonl +# one record: agent, taskId, contextId, state=TASK_STATE_COMPLETED, summary +``` + +Stop the background agent when done: + +```bash +pkill -f "a2a server --echo" +``` + +## Usage + +You do not run the skill yourself. Your agent loads it and follows it when a task +calls for A2A. Just ask, for example: + +> Fetch the agent card at `http://localhost:8080` and send it "summarize this repo". + +## Uninstall + +Remove the directory you created: + +```bash +rm -rf ~/.agents/skills/a2a-cli +``` + +## License + +Apache License 2.0, matching the +[a2a-cli project](https://github.com/a2aproject/a2a-cli/blob/main/LICENSE). diff --git a/skills/a2a-cli/SKILL.md b/skills/a2a-cli/SKILL.md new file mode 100644 index 0000000..431a41a --- /dev/null +++ b/skills/a2a-cli/SKILL.md @@ -0,0 +1,125 @@ +--- +name: a2a-cli +description: >- + Delegate work to A2A (Agent2Agent) agents from the command line with the `a2a` + CLI (github.com/a2aproject/a2a-cli). Use when you need to hand a task to a + specialized or remote agent, fetch an agent's card, send a message to an agent + at a URL, stream or poll a running task, or check, list, resume, or cancel an + A2A task. Not for building or serving an A2A agent, or for calling non-A2A + HTTP APIs. +compatibility: >- + Requires the `a2a` binary on PATH; a Go toolchain installs it from source, + since there are no prebuilt releases yet. The skill installs nothing itself. +license: Apache-2.0 +metadata: + source: https://github.com/a2aproject/a2a-cli + version: "2026.09.04" +--- + +# Driving A2A agents with the `a2a` CLI + +`a2a` is a stateless client for the [A2A protocol](https://a2a-protocol.org/): +give it an agent and a message, it negotiates the transport from the agent's +card (JSON-RPC, REST, or gRPC), sends the message, and reports what the agent +returned. + +## Core concepts + +- An interaction starts with a **Message** you send to an agent. +- The agent replies with either a **Message** (a direct answer) or a **Task** + (tracked, potentially long-running work). +- A **Task** has a server-assigned `taskId` and a `contextId`, and moves through + states. It can complete, fail, be cancelled, or become **interrupted** when it + needs your input or authentication to continue. +- Resume an interrupted task by sending a Message with its `--task-id`. +- Group related work with `--context-id`: a Task created in reply joins that + context. Many tasks can share one context, and a `--task-id` and `--context-id` + passed together must agree. +- The server keeps tasks (and the messages tied to them); a plain Message not + tied to a task is not stored — so **you** hold the `taskId`/`contextId` to + return to work later. + +## Setup + +Check for the binary; install from source if missing (needs a Go toolchain from +https://go.dev/doc/install); re-run to update: + +```bash +go install github.com/a2aproject/a2a-cli@latest +``` + +The tool is under active development. Treat `a2a help` and `a2a +--help` as the source of truth for the current commands and flags. + +## Task lifecycle + +Point at an agent with `-a ` (resolves its card and picks a +transport) or `-e --transport ` (connect directly). + +1. **Inspect the agent** — confirm it is reachable and see what it supports: + + ```bash + a2a card get https://agent.example.com + ``` + +2. **Send a message.** `send` blocks until the task reaches a terminal or + interrupted state. Add `-o json` for machine-readable output, and note the + `taskId` and `contextId` in the response — you need them to continue: + + ```bash + a2a send -a https://agent.example.com "Summarize this repo" + a2a send -a https://agent.example.com -o json "Summarize this repo" + ``` + +3. **Follow a long task live** instead of blocking, or re-attach to one later: + + ```bash + a2a send -a https://agent.example.com --stream "Run a long analysis" + a2a task subscribe -a https://agent.example.com + ``` + +4. **Check status and fetch results** at any time: + + ```bash + a2a task get -a https://agent.example.com + ``` + +5. **Answer an interrupted task** (it reached `INPUT_REQUIRED` / `AUTH_REQUIRED`) + by replying on the same task: + + ```bash + a2a send -a https://agent.example.com --task-id "Yes, proceed" + ``` + +6. **Continue the conversation** as a new task in the same context: + + ```bash + a2a send -a https://agent.example.com --context-id "Follow-up question" + ``` + +7. **List or cancel tasks:** + + ```bash + a2a task list -a https://agent.example.com + a2a task cancel -a https://agent.example.com + ``` + +## Key flags + +Run `a2a --help` for the full, current set. The load-bearing ones: + +| Flag | Use | +|---|---| +| `-a, --agent-card ` | Resolve the agent's card (picks the transport). | +| `-e, --endpoint ` + `--transport ` | Connect to one interface directly, skipping card resolution. | +| `-o, --output json` | Machine-readable output; add `--stream` for a live event stream. | +| `--async` | Return immediately with the identifiers instead of blocking; poll later with `task get`. | +| `--task-id ` / `--context-id ` | Continue a task / group a new task under a context. | +| `--auth ""` / `--svc-param ` | Attach credentials or transport parameters (or set `A2ACLI_*` env vars). Never commit a secret. | + +## Configuration + +Every setting can come from a flag, an `A2ACLI_*` environment variable, or a +`.env` file (a local `.env`, or `~/.config/a2a-cli/.env`); precedence is +flag > env var > file. Inspect the effective values and where each resolved from +with `a2a config show` (secrets redacted).