a2a-cli

使用 a2a CLI 驱动 A2A Agent

a2a 是一个用于 A2A protocol 的无状态客户端： 向它提供一个 Agent 和一条消息，它会根据 Agent 的名片协商传输方式（JSON-RPC、REST 或 gRPC），发送消息，并报告 Agent 返回的内容。

核心概念

• 一次交互从你发送给 Agent 的 Message 开始。
• Agent 会回复一条 Message（直接回答）或一个 Task（可跟踪、可能需要长时间运行的工作）。
• Task 有由服务端分配的 taskId 和 contextId，并会在不同状态间流转。它可以完成、失败、取消，或在需要你提供输入或进行身份验证才能继续时变为 interrupted。
• 通过发送带有 --task-id 的 Message 来恢复被中断的任务。
• 使用 --context-id 将相关工作分组：作为回复创建的 Task 会加入该上下文。多个任务可以共享一个上下文，同时传入的 --task-id 和 --context-id 必须一致。
• 服务端会保留任务（以及与其关联的消息）；未关联任务的普通 Message 不会被存储，因此之后要继续工作时，你需要保存 taskId/contextId。

设置

此技能会调用 a2a 二进制文件，但不会安装它。使用 a2a version 确认它位于 PATH 中；如果失败，请根据你的平台选择合适的方法安装：

• Homebrew（macOS / Linux）：

  brew tap a2aproject/a2a-cli https://github.com/a2aproject/a2a-cli
  brew install a2a
  

• WinGet（Windows）： winget install a2aproject.a2acli

• 预编译二进制文件： 从发布页面下载适用于你平台的压缩包，解压后将 a2a 二进制文件放入 PATH。

• 从源代码构建（需要 Go 工具链；再次运行即可更新）：

  go install github.com/a2aproject/a2a-cli@latest
  # go install names the binary a2a-cli; rename it to a2a to match the docs
  mv "$(command -v a2a-cli)" "$(dirname "$(command -v a2a-cli)")/a2a"
  

请以 a2a help 和 a2a <command> --help 为准，了解当前可用命令和标志。如果某个命令被拒绝，提示未知命令，或者某个标志已不存在，你的 SKILL.md 副本可能已过时——运行 a2a skill，并根据其输出更新本地的 SKILL.md。

任务生命周期

使用 -a <host|url|path> 指定 Agent（解析其名片并选择传输方式），或使用 -e <url> --transport <rest|jsonrpc|grpc> 直接连接。

1. 检查 Agent — 确认可以访问，并查看它支持的功能：

   a2a card get https://agent.example.com
   

2. 发送消息。 send 会阻塞，直到任务进入终止或中断状态。添加 -o json 可获取机器可读的输出，并记下响应中的 taskId 和 contextId——继续任务时需要用到它们：

   a2a send -a https://agent.example.com "Summarize this repo"
   a2a send -a https://agent.example.com -o json "Summarize this repo"
   

3. 实时跟踪长时间运行的任务，而非阻塞等待；也可以稍后重新连接：

   a2a send -a https://agent.example.com --stream "Run a long analysis"
   a2a task subscribe -a https://agent.example.com <task-id>
   

4. 检查状态、轮询直至完成，或获取结果：

   a2a task get -a https://agent.example.com <task-id>
   # Poll until completion or input/auth-required:
   a2a task get -a https://agent.example.com <task-id> --wait
   a2a task get -a https://agent.example.com <task-id> --wait --poll-interval 2s --timeout 60s
   

5. 回复被中断的任务（任务进入 INPUT_REQUIRED / AUTH_REQUIRED 状态），以继续同一任务：

   a2a send -a https://agent.example.com --task-id <task-id> "Yes, proceed"
   

6. 继续对话，在同一上下文中创建新任务：

   a2a send -a https://agent.example.com --context-id <context-id> "Follow-up question"
   

7. 列出或取消任务：

   a2a task list -a https://agent.example.com
   a2a task cancel -a https://agent.example.com <task-id>
   

关键标志

运行 a2a <command> --help 查看完整的最新标志列表。以下是最重要的标志：

标志	用途
-a, --agent-card <host|url|path>	解析 Agent 卡片（选择传输方式）。
-e, --endpoint <url> + --transport <rest|jsonrpc|grpc>	直接连接到某个接口，跳过卡片解析。
-o, --output json	输出机器可读内容；添加 --stream 可获取实时事件流。
--async	立即返回标识符，不阻塞；稍后使用 task get 轮询。
--wait	重复轮询 task get，直到任务进入终止状态或中断状态。
--poll-interval <duration>	等待期间两次轮询之间的间隔（默认值为 2s）。
--timeout <duration>	请求超时和总等待时长上限（默认值为 30s）。
--task-id <id> / --context-id <id>	继续某个任务 / 将新任务归入某个上下文。
--save-fileparts <dir>	将响应中的原始文件部分（工件和消息）保存到 <dir> 下的文件中；输出仍会按名称/类型/大小对其进行摘要说明。
--auth "<creds>" / --svc-param <k=v>	附加凭据或传输参数（也可设置 A2ACLI_* 环境变量）。切勿提交机密信息。

配置

每项设置都可以通过标志、A2ACLI_* 环境变量、.env 文件（本地 .env 或 ~/.config/a2a-cli/.env），或持久化的用户级 ~/.config/a2a-cli/config.yaml 设置；优先级依次为：标志 > 环境变量 > 本地文件 > 用户 config.yaml > 全局 .env。使用 a2a config show 查看生效值及其解析来源（机密信息会被隐藏）。

命令插件——PATH 中用于添加顶层命令的 a2a-<name> 二进制文件——默认选择加入且处于禁用状态。使用 a2a plugin set-enabled true 启用插件发现。