企业官网建设流程全解析

1. 多智能体协作里，A2A 端点为什么总连不通

如果你正在做 AI 智能体项目，大概率遇到过这种局面：一个 Agent 用 LangGraph 写，另一个用 CrewAI 写，还有一个跑在 Google ADK 上。它们各自都能完成单点任务，但要让它们互相派活、回传结果，就开始出问题。A2A 协议（Agent-to-Agent）就是冲着这个场景来的，它用标准化的 HTTP + JSON-RPC 2.0 让不同框架的智能体互相发现、下发任务、回传产物。适合谁？适合已经在做多智能体编排、需要跨框架调用的开发者，也适合想把 Agent 通信链路统一收口的团队。

但真正动手时，卡点往往不在协议本身，而在“端点”和“鉴权”这两件事上。Agent Card 里写的 url 是http://localhost:8000/，客户端却从容器里访问，直接 connection refused；或者卡片里声明了apiKey，客户端却把 Key 塞进了 URL query，服务端返回 401；再或者流式接口返回的 SSE 里choices字段读不出来，日志里一堆reading 'choices'的报错。这些问题单看都不复杂，凑在一起就让人怀疑协议是不是没跑通。

我试过把多个 Agent 的通信端点统一改到一个稳定的 API 入口上，用同一套 Key 做鉴权，链路一下子清晰很多。这篇就按“发现问题 → 准备统一入口 → 写可复制配置 → 验证双 Agent 任务流转 → 排常见错”的顺序，把 A2A 通信链路从 Agent Card 发现到结果回传完整走一遍。核心检索词就是 AI 智能体 A2A 协议、Agent 间通信端点配置、A2A 鉴权失败排查。下面所有配置都可以直接抄，改掉 Key 和模型 ID 就能跑。

2. 把 A2A 通信端点统一到 TaoToken 的前置准备

A2A 的通信模型里，客户端 Agent 需要先拿到服务端 Agent 的 Agent Card，再从卡片里读出url、capabilities、authentication和skills，然后按 JSON-RPC 2.0 发tasks/send或tasks/sendSubscribe。问题在于，很多示例把url写成localhost或内网地址，一旦跨容器、跨机器就失效。更麻烦的是鉴权：每个 Agent 各自实现一套 Key 校验，客户端要维护多份凭证，调试成本高。

把通信端点统一到一个稳定的 API 入口，好处有三个。第一，Agent Card 里的url不再依赖本机地址，跨环境可用；第二，鉴权收敛成一套 Key，客户端只需要在 Header 里带一次；第三，模型调用和 Agent 通信走同一个出口，日志和排障路径一致。TaoToken 在这里扮演的就是这个统一入口：它提供兼容 OpenAI 风格的 API 地址，同时可以作为 A2A 服务端的模型后端和鉴权层。

你需要先准备两样东西：一个可用的 API Key，以及确认要用的模型 ID。Key 在控制台的 API Keys 页面创建，模型 ID 按你实际接入的模型填写。注意，A2A 服务端本身仍然要暴露自己的 HTTP 端点给客户端，TaoToken 负责的是服务端内部调用模型时的出口，以及客户端调用服务端时的鉴权约定。两者不要混为一谈。

前置检查清单如下。第一，确认服务端 Agent 能正常启动并打印监听地址。第二，确认 Agent Card 的url字段写的是客户端可达的地址，不是127.0.0.1。第三，确认authentication.schemes里声明的方案和客户端实际发送的 Header 一致。第四，确认模型调用的 Base URL 和 Key 已经配好。这四步做完，再进入配置环节，能省掉一大半返工。

3. 可复制的 A2A 客户端与服务端配置片段

这一节给三份可直接复制的配置：A2A 服务端的 Agent Card、客户端的调用配置、以及模型出口的 settings 片段。路径和字段名保持和常见实现一致，你按自己项目改 Key 和模型 ID 即可。

先看服务端的 Agent Card。它决定了客户端能发现什么、怎么鉴权、往哪发请求。注意url要写成客户端可达地址，authentication.schemes用apiKey，并在 Header 里约定Authorization。

{ "name": "Calendar Agent", "description": "管理用户日历的智能代理，支持空闲查询与日程创建", "url": "http://your-agent-host:8000/", "version": "1.0.0", "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "capabilities": { "streaming": true, "pushNotifications": false }, "authentication": { "schemes": ["apiKey"], "credentials": { "header": "Authorization", "format": "Bearer {apiKey}" } }, "skills": [ { "id": "check_availability", "name": "检查空闲状态", "description": "检查用户在特定时间段是否有空", "tags": ["calendar", "productivity"], "examples": ["明天上午10点到11点我有空吗？"], "inputModes": ["text"], "outputModes": ["text"] } ] }

再看客户端的调用配置。这里用 JSON 描述一次tasks/send请求，Header 里带统一 Key，body 里带 skill 和消息。注意method和params的结构，这是 JSON-RPC 2.0 的标准形态。

{ "endpoint": "http://your-agent-host:8000/", "headers": { "Content-Type": "application/json", "Authorization": "Bearer sk-your-taotoken-key" }, "request": { "jsonrpc": "2.0", "id": "task-001", "method": "tasks/send", "params": { "skillId": "check_availability", "messages": [ { "role": "user", "parts": [ { "type": "text", "text": "明天上午10点到11点我有空吗？" } ] } ] } } }

最后是模型出口的 settings 片段。服务端 Agent 内部调用模型时，Base URL 指向 TaoToken 的 API 地址，Key 用同一套。这样服务端对外鉴权和内部模型调用可以复用同一份凭证管理逻辑。

[model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-your-taotoken-key" model_id = "your-model-id" timeout_seconds = 60 [a2a] agent_card_path = "/.well-known/agent.json" task_endpoint = "/tasks" auth_header = "Authorization" auth_scheme = "Bearer"

三份配置的对应关系要理清：Agent Card 里的url是客户端发请求的目标；客户端配置里的endpoint必须和它一致；Authorization的格式要和authentication.credentials.format对齐；模型出口的base_url和api_key是服务端内部用的，不暴露给客户端。把这三份放在一起对照，端点错配和鉴权错配基本能提前发现。

4. 双 Agent 任务流转验证：从发现到结果回传

配置写完，必须做一次完整的双 Agent 任务流转验证。这里用两个 Agent：一个作为客户端（Router Agent），一个作为服务端（Calendar Agent）。目标是让 Router 发现 Calendar 的 Agent Card，下发一个空闲查询任务，拿到结果并打印。

第一步，启动服务端并确认 Agent Card 可访问。启动后先请求/.well-known/agent.json，确认返回的 JSON 里url、skills、authentication都在。

curl -s http://your-agent-host:8000/.well-known/agent.json | python -m json.tool

预期结果是打印出完整卡片，skills数组里能看到check_availability。如果这里返回 404，说明服务端没有把卡片挂到 well-known 路径，检查路由注册。

第二步，客户端读取卡片并解析出端点和鉴权方案。下面这段 Python 演示发现和调用两个动作，注意 Header 的构造和 JSON-RPC 的 body。

import json import requests AGENT_HOST = "http://your-agent-host:8000" API_KEY = "sk-your-taotoken-key" # 1. 发现 Agent Card card_resp = requests.get(f"{AGENT_HOST}/.well-known/agent.json", timeout=10) card_resp.raise_for_status() card = card_resp.json() print("discovered skills:", [s["id"] for s in card["skills"]]) # 2. 按卡片声明的鉴权方案构造 Header auth_scheme = card["authentication"]["schemes"][0] headers = { "Content-Type": "application/json", "Authorization": f"Bearer {API_KEY}", } # 3. 下发任务 payload = { "jsonrpc": "2.0", "id": "task-001", "method": "tasks/send", "params": { "skillId": "check_availability", "messages": [ {"role": "user", "parts": [{"type": "text", "text": "明天上午10点到11点我有空吗？"}]} ], }, } resp = requests.post(card["url"] + "tasks", headers=headers, json=payload, timeout=60) print("status:", resp.status_code) print("body:", json.dumps(resp.json(), ensure_ascii=False, indent=2))

第三步，观察结果回传。成功时返回体里会有result字段，包含taskId、status和artifacts。artifacts里就是 Calendar Agent 的回复文本。如果status是working，说明任务被接受但还没完成，需要按taskId轮询或改用tasks/sendSubscribe走 SSE。

第四步，验证流式路径。把method换成tasks/sendSubscribe，客户端按 SSE 逐行读取。下面这段演示读取增量事件，注意每行以data:开头。

with requests.post(card["url"] + "tasks", headers=headers, json={ "jsonrpc": "2.0", "id": "task-002", "method": "tasks/sendSubscribe", "params": { "skillId": "check_availability", "messages": [{"role": "user", "parts": [{"type": "text", "text": "明天下午2点有空吗？"}]}], }, }, stream=True, timeout=120) as r: for line in r.iter_lines(decode_unicode=True): if line and line.startswith("data:"): event = json.loads(line[5:].strip()) print("event:", event.get("status"), event.get("delta", ""))

跑通这两条路径，说明 Agent Card 发现、任务下发、结果回传三段链路都通了。实测下来，最容易出问题的不是协议解析，而是端点地址和 Header 格式。把这两处对齐，双 Agent 流转基本一次过。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错逐条对照。每条给出触发原因和修复动作，你按日志里的关键字定位即可。

401 Unauthorized。触发原因通常是 Header 缺失、格式不对、或 Key 无效。先确认客户端 Header 是Authorization: Bearer sk-xxx，不是把 Key 放 query。再确认服务端校验逻辑读取的 Header 名和 Agent Card 里credentials.header一致。最后确认 Key 没有多余空格或换行。如果服务端内部调用模型也返回 401，检查base_url和api_key是否配对，模型 ID 是否在可用列表里。

local proxy failed。这个报错一般出现在客户端配置了本地代理或环境变量里有代理设置，导致请求发不出去。检查HTTP_PROXY、HTTPS_PROXY、ALL_PROXY是否指向了不可用地址。A2A 通信走的是标准 HTTP，不需要额外代理层。把相关环境变量清掉，或显式设置NO_PROXY包含你的 Agent 主机。

reading 'choices' 报错。典型日志是Cannot read properties of undefined (reading 'choices')。这说明客户端按 OpenAI 风格解析响应，但实际拿到的是 A2A 的 JSON-RPC 结构，或者流式事件里没有choices字段。修复方式是区分两条链路：模型调用走 OpenAI 兼容格式，读choices；A2A 任务回传走 JSON-RPC，读result.artifacts。不要把两者的解析逻辑混用。如果确实在流式里读choices，确认你请求的是模型接口而不是 A2A 任务接口。

OAuth 相关失败。如果 Agent Card 声明的是 OAuth 而不是 apiKey，客户端需要先走 token 获取流程，再把 access token 放进 Header。常见错误是 token 过期未刷新，或 scope 不匹配。排查时先确认authentication.schemes和实际使用的方案一致，再检查 token 有效期。如果暂时不想引入 OAuth，把卡片改成 apiKey 方案，用统一 Key 鉴权，链路会简单很多。

另外两个容易忽略的点。第一，Agent Card 的url末尾斜杠和客户端拼接路径的斜杠要统一，否则会出现//tasks或tasks缺失。第二，流式接口的超时时间要设够，SSE 长连接容易被默认 30 秒超时切断，建议设到 120 秒以上。把这几条对照一遍，大部分 A2A 通信报错都能定位到具体配置项。

6. 接入路径与后续动作

链路跑通后，下一步是把配置固化到项目里。模型出口的 Base URL 用https://taotoken.net/api，Key 在控制台创建后写入环境变量，不要硬编码。Agent Card 的url按部署环境区分，本地用可达地址，线上用域名。鉴权统一走Authorization: Bearer，服务端和客户端共用一套 Key 管理逻辑。

如果你要长期跑多智能体编排和 Agent 任务流转，建议把 Coding Plan 纳入考虑，它更适合持续性的编码和 Agent 场景。需要验证模型对话效果时，可以直接在模型对话页面试。接入文档里有完整的参数说明和示例，排障时对照着看会快很多。API Keys 页面负责创建和管理凭证，接入文档负责解释字段含义，两者配合使用。

最后留一个实用习惯：每次改完 Agent Card 或客户端配置，先跑一遍/.well-known/agent.json的 curl，确认卡片可读，再跑一次tasks/send的最小请求。这两步能挡住大部分端点错配和鉴权错配。把验证动作前置，比事后翻日志高效得多。