跳到主要内容

配置 Agent 网关

AISIX 通过 /a2a/<agent> 上需要调用方身份认证的网关端点公开已注册的 Agent-to-Agent（A2A）Agent。本指南将官方 A2A Echo Agent 连接到现有 AISIX 网关，注册该 Agent，为快速入门中的调用方授予访问权限，并验证 A2A 1.0 JSON-RPC 请求。

你可以选择 AISIX Cloud 或开源配置流程。两种流程的注册步骤不同，但配置的网关行为相同，并使用同一请求验证结果。

前置条件​

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

启动 A2A 测试 Agent​

本示例在 Docker 中运行官方 A2A Go SDK 提供的 Echo 服务器。Agent 与现有网关会加入一个临时 Docker 网络，因此网关无需重启即可访问 Agent。Echo 服务器仅用于本地测试：它不进行身份认证，并会返回调用方发送的消息文本。它生成的 A2A 1.0 Agent Card 不包含 AISIX 当前在发现 Card 时所需的兼容 url 字段。因此，本配置仅验证 JSON-RPC 调用路径，不验证 Agent Card 路由。容器不会接收任何密钥。完成本指南后，请停止并删除该容器。

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

如使用 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.4.0 \
    serve --echo --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 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
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 调用​

本节命令适用于两种管理方式。命令使用现有的 AISIX_PROXY 值和保存在 AISIX_A2A_KEY 中的调用方凭证。

AISIX Cloud 可能需要几秒钟才能将配置下发到网关。以下命令会轮询 Agent，最长等待 90 秒：

for attempt in $(seq 1 45); do
  A2A_RESPONSE=$(curl -sS -X POST "$AISIX_PROXY/a2a/echo-agent" \
    -H "Authorization: Bearer $AISIX_A2A_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": "req-1",
      "method": "SendMessage",
      "params": {
        "message": {
          "messageId": "msg-1",
          "role": "ROLE_USER",
          "parts": [{"text": "Hello through AISIX"}]
        }
      }
    }') || true

  if echo "$A2A_RESPONSE" | jq -e \
    '.result.task.artifacts[].parts[] | select(.text == "Hello through AISIX")' \
    >/dev/null 2>&1; then
    break
  fi
  sleep 2
done

echo "$A2A_RESPONSE" | jq -e \
  '.result.task.artifacts[].parts[] | select(.text == "Hello through AISIX")'

最后一条命令会输出匹配的文本部分。AISIX 已对调用方进行身份认证、检查其 Agent 授权，并将 JSON-RPC 请求原样转发到 Echo Agent。

为实际 Agent 调整配置​

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

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

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

清理​

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

如使用 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、授予调用方访问权限，并通过 AISIX 发送 A2A 1.0 请求。可以继续阅读以下指南：