智能体到智能体协议（Agent2Agent Protocol，A2A）用于发现和调用远程智能体。IaC Code 可以作为 A2A 1.0 Server 发布云资源管理能力，供其他智能体和工作流平台调用。本文介绍 Server 启动、Agent Card、首条消息、上下文延续和认证。
前提条件
已完成安装和配置 IaC Code。
已安装 A2A 可选依赖。
已确定 Server 允许访问的工作目录，以及调用云资源所需的 RAM 身份。
网络部署已准备服务认证、访问控制和 Secret 管理。
启动 A2A Server
安装可选依赖并启动本地 Server：
python -m pip install "iac-code[a2a]"
iac-code a2a --host 127.0.0.1 --port 41242
预期结果：Server 提供健康检查、Agent Card 和 A2A 请求端点。
获取 Agent Card
使用 HTTP 获取：
curl http://127.0.0.1:41242/.well-known/agent-card.json
或使用内置客户端：
iac-code a2a-client discover --url http://127.0.0.1:41242/
预期结果：响应包含智能体名称、A2A 接口、输入输出模式，以及 iac_generation、
iac_review、aliyun_ros_operations 等已发布能力。
发送首条消息
iac-code a2a-client call \
--url http://127.0.0.1:41242/ \
--prompt "查询 cn-hangzhou 的 ROS 资源栈并汇总异常状态，不要执行任何写操作" \
--cwd "$PWD" \
--stream
预期结果：客户端流式输出任务更新和最终结果。--cwd 会作为工作目录元数据发送，必须是
Server 允许访问的绝对路径。远程 Server 上的路径是服务端文件系统路径，不是客户端本地任意路径。
延续上下文和管理任务
首次调用结果会返回 A2A contextId。后续消息携带该值复用 IaC Code 上下文：
iac-code a2a-client call \
--url http://127.0.0.1:41242/ \
--context-id "<首次调用返回的 contextId>" \
--prompt "继续分析异常资源栈的事件并给出处理建议，不要执行写操作" \
--cwd "$PWD" \
--stream
使用 task-get、task-list、task-cancel 和 task-subscribe 查询、列出、取消或订阅任务。任务 ID 表示一次 A2A 执行，contextId 表示可以跨消息复用的对话上下文。
配置认证和工作目录
未配置认证的 Server 仅适合可信的本地环境。网络部署至少启用 Bearer Token、Basic Auth 或 API Key 之一。例如，通过部署环境的 Secret 设置 Bearer Token：
export IACCODE_A2A_HTTP_TOKEN="${A2A_SERVICE_TOKEN}"
iac-code a2a --host 127.0.0.1 --port 41242
调用方通过 --token 或客户端配置读取相同 Secret。不要把令牌直接写入命令历史或仓库。
通过 IACCODE_A2A_ALLOWED_CWDS 设置操作系统路径分隔的允许目录列表。还可以按需配置 Agent
Card 签名和客户端验证，避免把任务发送到伪造端点。
权限注意事项
A2A 请求通常没有本地用户实时处理权限弹窗。服务端应为允许的读写操作配置明确策略， 并默认拒绝未经授权的写工具。云上写 API 仍需精确授权和本地审计，A2A 服务认证不能替代阿里云 RAM 权限。
常见问题
Agent Card 或请求返回 401
Agent Card 发现也受已配置的认证方式保护。确认客户端在发现和调用阶段都发送正确的 Bearer Token、Basic Auth 或 API Key。
请求提示工作目录不允许
传入绝对目录，并确认它位于 IACCODE_A2A_ALLOWED_CWDS 中。不要将整个文件系统根目录加入允许列表。
云上写操作没有执行
检查服务端工具权限策略和 RAM 权限。不要通过关闭权限检查解决问题；应只允许任务实际需要的目标 API，并保留审批和审计记录。