从单 Agent 到多 Agent：为什么协作难落地

Agent 再强大，面对跨领域的复杂任务，终究会遇到能力边界。一个「点咖啡」的 Agent 不应该知道怎么「安排配送」，一个「写代码」的 Agent 不应该知道怎么「审批流程」。更合理的方式，是让不同 Agent 各司其职，再通过协作机制互相发现、互相调用。

问题在于，自建一套多 Agent 系统并不只是“多写几个 Agent”。你还需要自己解决一整套平台工程问题：

• 注册中心：哪些 Agent 在线？属于哪个环境？当前地址是什么？
• 服务发现：调用方如何找到合适的 Agent？如何读取它的能力描述？
• 跨 Agent 鉴权：谁可以发现谁、调用谁？凭证如何轮转？
• 调度编排：复杂任务如何拆解、分发、重试、聚合结果？
• 环境隔离：开发、测试、生产的 Agent 如何避免互相串用？
• 链路追踪：一次用户请求跨多个 Agent 后，如何定位慢调用和失败点？

每一项单独看都是一个工程项目，加起来可能比写 Agent 本身的代码还多。AgentRun 要解决的不是“发明多 Agent”，而是让多 Agent 从实验室协作变成可上线、可管理、可审计的生产系统。

二、为什么选择 A2A：用开放协议定义“怎么发现、怎么通信”

多 Agent 协作最怕被平台私有协议锁死：每接一个 Agent，就要重新适配一套能力描述、鉴权方式和调用协议。Agent 一多，系统很快变成烟囱。

A2A（Agent-to-Agent）是 Google 主导的开放协议，不绑定任何平台。这意味着你自建的 Agent、第三方的 Agent、不同云厂商的 Agent，只要遵循 A2A，就能基于同一套标准互相发现和通信。

它的价值，在于为 Agent 之间的互联提供了一套开放、统一的基础约定：

• 自描述：通过 AgentCard 描述 Agent 是谁、能做什么、怎么访问；
• 可发现：调用方可以基于标准入口获取 AgentCard，而不是依赖人工配置；
• 可互通：不同团队、不同平台、不同运行环境的 Agent，只要遵循协议，就能被统一接入；
• 可演进：协议层定义连接方式，平台层可以继续补齐注册、权限、治理、观测等生产能力。

所以，AgentRun 选择 A2A，不是把 A2A 包装成自己的私有能力，而是基于开放协议承接生态互通，再在协议之上补齐企业落地所需的管理面。

三、A2A 发现机制原理

AgentCard：智能体的自我介绍

A2A 协议通过AgentCard让每个智能体对外自描述能力与接入方式。AgentCard 是一份标准 JSON 文档，描述了：

• 是谁：Agent 的名称、描述、版本、提供方；
• 能做什么：技能列表（Skills），每个技能有 ID、名称、描述和示例问法；
• 怎么访问：服务地址（URL）、支持的传输协议（如 JSON-RPC / gRPC）；
• 有什么限制：认证方式、是否支持流式响应等。

按照 A2A 标准，AgentCard 默认托管在 /.well-known/agent-card.json路径下。客户端只需知道 Agent 的 Base URL，就能拿到这份自描述文档，进而决定如何与它通信。

服务发现：谁在这个网络里？

有了 AgentCard，还缺一个关键问题的答案：我怎么知道有哪些 Agent 可以调用？

A2A 协议本身不强制定义中心化注册表，实际项目中通常需要一个「发现层」来管理 Agent 的注册和查询。发现层接受查询请求，返回可用 Agent 的 AgentCard URL，调用方再逐一拉取 AgentCard 完成能力感知。

这也是 AgentRun 发挥价值的地方：协议定义“怎么描述、怎么连接”，平台负责“怎么注册、怎么发现、怎么隔离、怎么治理”。

四、AgentRun 的多 Agent 管理：注册、发现与隔离

AgentRun 在 A2A 协议基础上，提供了一套生产级的多 Agent 管理体系，核心围绕三个概念：

工作空间（Workspace）：逻辑隔离的 Agent 集合>

工作空间是 AgentRun 中组织 Agent 的基本单位，类似于一个「项目空间」或「命名空间」。不同业务域、不同团队的 Agent 可以分属不同工作空间，互相隔离，权限独立管理。

一个 Agent Runtime 归属于一个工作空间后，工作空间就成为它对外可被发现的范围边界。

发现端点（Discovery Endpoint）：按环境隔离的发现入口

一个工作空间内可以配置多个发现端点，典型用法是按部署环境区分：

工作空间: my-ai-platform ├── 发现端点 default → 面向内部调试，包含所有 Agent └── 发现端点 production → 面向生产流量，只含稳定版 Agent

每个发现端点维护一张映射表，记录「哪个 Agent」对应「哪个访问地址」。同一个 Agent 在不同端点中可以配置不同地址，例如开发地址和生产自定义域名。

平台托管 vs 外部 Agent：统一的发现体验

AgentRun 支持两类 Agent 共存于同一工作空间：

两类 Agent 在发现端点中的表现完全一致——调用方拿到的都是标准 ，无需关心 Agent 实际部署在哪里。

凭证安全保护：谁可以发现这些 Agent？

服务发现本身就是敏感信息：暴露工作空间内有哪些 Agent、它们在哪里，可能为攻击者提供侦察入口。AgentRun 在发现端点上内置了凭证验证体系，支持 API Key、HTTP Basic Auth 等方式。

凭证配置与工作空间解耦。更换凭证时，只需在平台重新绑定，无需修改任何 Agent 的代码。

五、实战体验：用“希希咖啡厅”跑通发现链路

本文以「希希咖啡厅」多 Agent 系统作为演示对象。目标不是展开 SDK 细节，而是让你看到一套多 Agent 如何被纳入 AgentRun 的工作空间，并通过统一发现端点暴露为 A2A 可调用资源。

1. 部署模板，准备两个专职 Agent

在 AgentRun 控制台的Agent 模版页面一键部署「希希咖啡厅」，平台会自动创建两个专职 Agent：

• coffee_agent：负责点单、查看菜单、查询订单；
• delivery_agent：负责安排配送和查询配送状态。

2. 创建工作空间，确定管理边界

新建一个 Workspace，作为这组 Agent 的组织、隔离和发现边界。后续所有服务发现都以工作空间为范围。

3. 注册 Agent，统一托管与外部接入

将平台托管 Agent 或外部 A2A 兼容 Agent 纳入工作空间。注册完成后，调用方看到的都是统一的 a2aAgentCardUrl，不需要关心 Agent 实际部署在 AgentRun、客户自建服务还是第三方平台。

4. 配置发现端点，暴露可控的发现入口

在工作空间的「服务发现」中添加端点，配置 Agent 映射和访问凭证。你可以按