简介:本文介绍如何通过 Nacos A2A 插件,让 Dify 既能发现并调用外部智能体,也能把自身工作流发布为可被其他系统调用的 A2A 智能体。文中包含 AgentCard 字段说明、JSON-RPC 调用示例、常见错误排查表和上线前的鉴权检查清单,帮助团队降低多智能体系统的接入成本。
随着 AI Agent 从单轮问答走向复杂业务流程,一个智能体很难独自完成全部任务。多智能体协作逐渐成为常见架构:一个 Agent 负责理解需求,一个 Agent 负责生成代码,一个 Agent 负责查询数据,另一个 Agent 负责审核结果。Google 于 2025 年 4 月发布 A2A 协议,为智能体之间的发现、能力描述和任务交互提供了统一的标准。
Dify 本身是可视化的 AI 应用开发平台,适合搭建工作流、知识库和对话应用。但在多智能体场景下,它原生的能力边界比较明显,团队通常会遇到以下问题。
Nacos 3.0 提供了 Agent Registry 能力,可以像管理服务注册那样管理 A2A Agent 的元数据。Dify 侧的 Nacos A2A 插件则负责把这套注册中心接入工作流。两者组合后,Dify 既能调用其他智能体,也能被其他智能体调用。具体支持的版本和功能边界,请以 Nacos 与插件的官方文档为准,部署前先核对版本。
整体架构可以分为三层。
在 Dify 侧通常会用到两类插件,它们的方向相反,配置重点也不同。
| 项目 | A2A Discovery | A2A Server/Provider |
|---|---|---|
| 数据方向 | Dify 作为客户端调用外部 Agent | Dify 应用作为服务端被外部调用 |
| 主要配置 | Nacos 地址、命名空间、目标 Agent 的筛选条件 | 应用名称、技能描述、对外访问地址、鉴权方式 |
| 鉴权重点 | 保存外部 Agent 的 Token 或密钥 | 配置入口 Token,并通过网关设置白名单 |
| 典型失败 | AgentCard 拉取失败、调用超时、返回结构不匹配 | 外部无法访问对外地址,或技能描述不准确导致路由错误 |
接入后,Dify 会成为多智能体网络中的一个节点,而不再是封闭的平台。
建议准备以下组件。
自托管 Dify 时,可以使用 Docker Compose 部署,便于后续与向量数据库、对象存储等组件集成。
将外部 Agent 的 AgentCard 地址、能力标签、版本和鉴权方式登记到 Nacos。下面是一份精简的 AgentCard 示例,字段结构参照 A2A 规范,protocolVersion 等取值需要与你使用的规范版本保持一致。
{"protocolVersion": "0.3.0","name": "doc-summary-agent","description": "文档摘要智能体,对长文本生成结构化摘要","url": "https://agent.example.com/a2a/v1","version": "1.0.0","capabilities": {"streaming": false,"pushNotifications": false},"defaultInputModes": ["text/plain"],"defaultOutputModes": ["text/plain"],"skills": [{"id": "summarize","name": "文档摘要","description": "对长文本进行结构化摘要,输出要点和关键风险","tags": ["summary", "document"]}]}
注册完成后,Nacos 会维护 Agent 的元数据。Dify 插件可以按名称、标签或能力描述检索目标 Agent。因此,description、skills 和 tags 写得越准确,动态路由的效果越好。
进入 Dify 的插件或工具配置页面,在插件市场中搜索并安装 Nacos A2A 插件。随后填写以下参数。
保存后,Dify 会尝试拉取已注册的 A2A Agent 列表。如果列表为空,先检查命名空间和分组是否与注册时一致。
如果工作流还需要调用大模型,可以在模型供应商中添加 OpenAI 兼容接口的模型服务。同一个 API Key 通常可以用于添加多个模型,具体以所用供应商的说明为准。
在 Dify 工作流中新增 A2A Discovery 节点,选择目标 Agent,并把上游节点的输出变量作为任务内容传入。插件封装后,开发者主要配置目标 Agent、输入变量和输出解析规则。
如果需要用 HTTP 请求节点直接调用,底层请求遵循 A2A 的 JSON-RPC 格式。当前规范中,发送消息的方法名为 message/send,消息体需要包含 messageId,文本片段的类型标记为 kind: "text"。
{"jsonrpc": "2.0","id": "req-001","method": "message/send","params": {"message": {"kind": "message","role": "user","messageId": "msg-001","parts": [{"kind": "text","text": "请总结这份需求文档,并输出关键风险点"}]}}}
下面是对应的 Python 调用示例。Token 从环境变量读取,避免写死在代码里。
import osimport uuidimport requestsurl = "https://agent.example.com/a2a/v1"token = os.environ["A2A_AGENT_TOKEN"] # 从环境变量读取,不要硬编码payload = {"jsonrpc": "2.0","id": str(uuid.uuid4()),"method": "message/send","params": {"message": {"kind": "message","role": "user","messageId": str(uuid.uuid4()),"parts": [{"kind": "text", "text": "请生成项目周报"}],}},}headers = {"Content-Type": "application/json","Authorization": f"Bearer {token}",}resp = requests.post(url, json=payload, headers=headers, timeout=30)resp.raise_for_status()body = resp.json()if "error" in body:raise RuntimeError(f"A2A 调用失败: {body['error']}")print(body.get("result"))
这段代码要点有三个。第一,HTTP 状态码和 JSON-RPC 的 error 字段需要分别检查,因为服务端可能返回 200 却在 error 中报错。第二,超时设置为 30 秒,并应在工作流节点中配置重试次数。第三,返回的 result 可能是任务对象或消息对象,解析前应先确认结构。
需要注意,A2A 规范仍在演进。方法名、Part 类型和 AgentCard 字段可能随版本变化,实际接入前请核对插件所依赖的协议版本。
除了调用外部 Agent,Dify 还可以通过 A2A Server/Provider 插件对外提供服务。发布时需要完成以下工作。
其他支持 A2A 的系统就可以在 Nacos 中发现该 Dify Agent,并发送任务。这样,Dify 中沉淀的工作流、知识库和模型能力,就能被企业内其他智能体复用。
Dify 负责意图识别和知识库问答。订单查询、物流状态和工单创建交给外部 A2A Agent 处理。通过 Nacos 注册中心,系统可以按业务类型把请求路由到对应的 Agent。
一个 Agent 负责需求拆解,一个 Agent 负责代码生成,另一个 Agent 负责测试用例生成。Dify 作为编排层,通过 A2A 协议串联这些专业 Agent,形成可复用的研发流程。
Dify 应用接收用户问题,先调用数据查询 Agent 获取指标,再调用报告生成 Agent 输出结论。如果涉及多个模型,可以按节点选择不同模型,并结合各模型的单价和响应速度做取舍。
Dify 可以结合向量数据库搭建本地知识库,用 RAG 提升回答的准确性。当问题超出知识库范围时,通过 A2A 插件调用外部专业 Agent 补充答案。
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 插件中看不到任何 Agent | 命名空间或分组配置错误 | 对照注册时的命名空间核对 |
| 返回 401 或 403 | Token 失效,或未随请求发送 | 检查 Authorization 请求头和密钥有效期 |
| AgentCard 拉取失败 | 地址不可达,或证书校验失败 | 用 curl 直接访问 AgentCard 地址 |
| 调用超时 | 下游 Agent 处理耗时较长 | 调大超时时间,并设置有限次数的重试 |
| 返回结构解析失败 | 方法名或协议版本不一致 | 核对 method 字段和返回结构,确认插件版本 |
排查时建议同时查看 Dify 的运行日志和 Nacos 的服务日志,确认请求是否到达了目标 Agent。
Nacos A2A 插件让 Dify 同时具备两种能力。一方面,Dify 可以通过 A2A Discovery 调用外部智能体。另一方面,Dify 应用可以通过 A2A Server/Provider 对外提供服务。结合 Nacos Agent Registry,团队能够统一管理 Agent 的注册、发现、路由和权限,降低多智能体应用的开发和维护成本。
建议从一个小场景开始。先注册一个外部 A2A Agent,再在 Dify 工作流中完成一次调用,确认返回结果符合预期后,再把 Dify 应用发布为 A2A Agent。每一步都验证通过,再扩大范围,这样更容易定位问题,也更容易控制风险。