配置 Agent 网关

AISIX 通过 /a2a/<agent> 上需要调用方身份认证的网关端点公开已注册的 Agent-to-Agent（A2A）Agent。本指南将官方 A2A Echo Agent 连接到现有 AISIX 网关，并为快速入门中的调用方授予访问权限。随后，官方 A2A Go SDK 客户端通过网关发送 A2A 1.0 消息。

你可以选择控制面或 AISIX OSS 配置流程。两种流程的注册步骤不同，但配置的网关行为相同。完成任一流程后，均使用相同的 Agent Card 就绪检查和 SDK 客户端调用验证结果。

前置条件

开始前，请准备以下环境：

• 如使用 AISIX Enterprise，请完成 AISIX Enterprise 入门，并保持其中的 Shell 和 aisix-dp 网关运行。如使用 AISIX Cloud，请从所属组织获取环境、已连接网关、写入作用域管理员 Token、调用方 API Key 和网关 URL。
• 如使用开源 AISIX 网关，请完成开源 AISIX 网关快速入门，并停留在其中的 Shell 和工作目录，同时保持 aisix-quickstart 网关运行。
• Docker、cURL 和 jq。

启动 A2A 测试 Agent

本示例在 Docker 中运行官方 A2A Go SDK 提供的 Echo 服务器。Agent 与现有网关会加入一个临时 Docker 网络，因此网关无需重启即可访问 Agent。Echo 服务器仅用于本地测试：它不进行身份认证，并会返回调用方发送的消息文本。该服务器会发布同时兼容 A2A 0.3 和 1.0 的 Agent Card，因此还可通过 AISIX 验证面向客户端的发现流程。Echo 服务器启动时不带上游凭证；后续客户端检查会将快速入门中的一次性调用方密钥传入该测试容器。完成本指南后，请停止并删除该容器。

根据所选配置流程设置网关容器名称。

如使用 AISIX Enterprise 或 AISIX Cloud：

export AISIX_GATEWAY_CONTAINER="aisix-dp"

如使用开源 AISIX 网关：

export AISIX_GATEWAY_CONTAINER="aisix-quickstart"

创建临时网络，并将正在运行的网关连接到该网络：

docker network create aisix-a2a
docker network connect aisix-a2a "$AISIX_GATEWAY_CONTAINER"

在同一网络中启动 Echo Agent。固定版本的 Go SDK 会在容器中下载并编译，因此首次启动可能需要约一分钟：

docker run -d --name aisix-a2a-echo \
  --network aisix-a2a \
  golang:1.25-alpine \
  sh -c 'go run github.com/a2aproject/a2a-go/v2/cmd/a2a@v2.5.0 \
    serve --echo --card-compat --host 0.0.0.0 --port 8080 \
    --transport jsonrpc --protocol latest --name "AISIX A2A Echo"'

等待 Agent 就绪：

for attempt in $(seq 1 120); do
  docker logs aisix-a2a-echo 2>&1 | grep -q "Listening on" && break
  sleep 1
done

docker logs aisix-a2a-echo 2>&1 | grep "Listening on"

最后一条命令会输出监听地址。在网关容器内，可以通过 http://aisix-a2a-echo:8080 访问该 Agent。

注册 Agent 并授予访问权限

通过部署对应的管理方式注册 Agent。两种方式都会将 Agent 命名为 echo-agent、固定为 A2A 1.0，并将其授权给现有的快速入门调用方。

AISIX Enterprise 或 AISIX Cloud

注册测试 Agent，并将其公开给快速入门环境：

A2A_AGENT_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/a2a_agents" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "name": "echo-agent",
  "url": "http://aisix-a2a-echo:8080",
  "protocol_version": "1.0",
  "auth_type": "none",
  "allowed_environments": ["${ENV_ID}"]
}
EOF
)

export A2A_AGENT_ID=$(echo "$A2A_AGENT_RESPONSE" | jq -er '.a2a_agent.id')
echo "$A2A_AGENT_RESPONSE" | jq

❶ protocol_version 标识调用方与上游 Agent 使用的传输格式。AISIX 会原样转发请求，不会在不同版本之间转换。

❷ allowed_environments 控制哪些环境可以接收此组织级资源。

将 echo-agent 授权给快速入门中创建的调用方 API Key：

curl -fsS -X PATCH \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allowed_agents":["echo-agent"]}' | jq

export AISIX_A2A_KEY="$AISIX_API_KEY"

该部分更新会保留 API Key 现有的模型访问权限。控制面会自动将这两个资源下发到已连接的网关。

开源 AISIX 网关

在现有 resources.yaml 中，为快速入门调用方添加 allowed_agents，并添加 a2a_agents 集合。保留现有模型服务提供方密钥和模型条目不变：

resources.yaml（调用方与 Agent）

api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini
    allowed_agents:
      - echo-agent

a2a_agents:
  - name: echo-agent
    url: http://aisix-a2a-echo:8080
    protocol_version: "1.0"
    auth_type: none

❶ allowed_agents 授予快速入门调用方访问已注册 echo-agent 的权限。

❷ name 会成为 /a2a 下调用方可见的路径段。

在运行中的网关容器内验证完整文件，然后在不重启容器的情况下重新加载：

docker exec aisix-quickstart \
  aisix validate --resources /etc/aisix/resources.yaml

docker kill --signal HUP aisix-quickstart

export AISIX_A2A_KEY="$CALLER_API_KEY"

如果更新后的文件无效，网关会继续使用上一个有效配置。请检查 docker logs aisix-quickstart，查看被拒绝的加载操作。

使用 A2A 客户端验证

本节命令适用于两种管理方式。首先，等待网关能够获取已注册 Agent 的 Card。这样无需手工构造 JSON-RPC 消息，即可为控制面配置投射保留所需的等待时间：

for attempt in $(seq 1 45); do
  curl -fsS \
    "$AISIX_PROXY/a2a/echo-agent/.well-known/agent-card.json" \
    -H "Authorization: Bearer $AISIX_A2A_KEY" \
    >/dev/null 2>&1 && break
  sleep 2
done

curl -fsS \
  "$AISIX_PROXY/a2a/echo-agent/.well-known/agent-card.json" \
  -H "Authorization: Bearer $AISIX_A2A_KEY" \
  >/dev/null

设置客户端容器可访问的 Agent URL。两个 AISIX 快速入门指南均使用网关容器内的 3000 端口：

export AISIX_A2A_URL="http://${AISIX_GATEWAY_CONTAINER}:3000/a2a/echo-agent"

在 echo-agent 容器内运行官方 A2A Go SDK 的命令行客户端。--transport jsonrpc 会直接连接已注册的 AISIX 端点，而非先解析 Agent Card：

docker exec aisix-a2a-echo \
  go run github.com/a2aproject/a2a-go/v2/cmd/a2a@v2.5.0 \
  send "$AISIX_A2A_URL" "Hello through AISIX" \
  --transport jsonrpc \
  --auth "Bearer $AISIX_A2A_KEY" \
  --output json | jq -e \
  '.artifacts[].parts[] | select(.text == "Hello through AISIX")'

该命令会输出匹配的产物部分。AISIX 已对调用方进行身份认证、检查其 Agent 授权，并将 SDK 客户端的 A2A 1.0 请求转发到 Echo Agent。

为实际 Agent 调整配置

将测试 URL 替换为网关可访问的 A2A JSON-RPC 端点。将 protocol_version 设置为 Agent 支持的传输格式，并使用该格式发送请求。AISIX 支持 "1.0" 和 "0.3"，但不会在两者之间转换。

通过 auth_type 和 secret 配置所需的上游凭证。请参阅上游身份认证。

对于开源 AISIX 网关，请验证完整的资源文件。如果运行中的网关已经具有所有被引用的环境变量，请发送 SIGHUP。如果新增或修改了环境变量，请使用新值重新创建容器。请参阅重新加载资源文件。

清理

如果要继续学习其他 Agent 网关指南，可以保留 Agent 和调用方授权。否则，请按照所用管理方式删除本指南添加的资源。

如使用 AISIX Enterprise 或 AISIX Cloud，请清除调用方的 Agent 授权并删除 Agent：

curl -fsS -X PATCH \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allowed_agents":[]}' | jq

curl -fsS -X DELETE "$AISIX_CP/a2a_agents/$A2A_AGENT_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN"

如使用开源 AISIX 网关，请从 resources.yaml 中删除新增的 allowed_agents 和 a2a_agents，验证文件并再次发送 SIGHUP。

删除测试 Agent 和临时网络：

docker rm -f aisix-a2a-echo
docker network disconnect aisix-a2a "$AISIX_GATEWAY_CONTAINER"
docker network rm aisix-a2a

后续步骤

你已注册 A2A Agent、授予调用方访问权限，并使用官方 SDK 客户端通过 AISIX 发送 A2A 1.0 消息。可以继续阅读以下指南：

• A2A 流式传输与 Agent Card 发现：接收流式任务，并通过公共网关源地址验证面向客户端的 Agent Card。

• 配置上游身份认证：为上游 Agent 使用 Bearer Token 或 API Key。

• 控制 Agent 访问权限：授权精确的 Agent 名称、名称模式或所有已注册 Agent。

• 应用限流和预算：使用调用方限流及 AISIX Enterprise 或 AISIX Cloud 中的预算治理 A2A 调用。

• 可观测性：查看 A2A 调用生成的用量事件和指标。