前言¶
DeepSeek Harness (DSH) 采用插件化架构，智能体通常在本地或特定环境中运行。若要让外部系统或其他 A2A（Agent2Agent）协议的智能体发现并调用这些智能体，需要一套标准的接入机制。dsh-a2a-server 插件提供了这一能力，它作为入站服务器运行，通过标准的 Agent Card 和 JSON-RPC 绑定，使 DSH 智能体能够被任何兼容的客户端发现和提交任务。
插件定位¶
dsh-a2a-server 是一个社区插件（非 DeepSeek 官方产品），由 huangjuhua-aigc 维护，许可证为 MIT。它是一个 DeepSeek Harness 的插件，核心作用是将本地的智能体代理暴露给 A2A 协议。它通过在已知 URI（.well-known/agent-card）上提供 Agent Card，并实现 v1.0 JSON-RPC 绑定，允许任何知晓部署地址的合规对端发现该智能体并向其提交任务。
核心功能¶
该插件提供以下核心能力：
- 入站 A2A 服务器：仅作为服务器端运行，不会主动连接到另一个智能体。
- Agent Card 服务：在标准 URI 上提供 Agent Card，用于服务发现。
- JSON-RPC 绑定：实现 v1.0 JSON-RPC 协议，支持以下方法：
SendMessageSendStreamingMessageGetTaskListTasksCancelTaskSubscribeToTaskGetExtendedAgentCard
- 多对端支持：通过环境变量配置多个对端（
A2A_PEERS），支持带令牌或不带令牌的访问。
安装与启用¶
安装该插件需要使用 Web 配置文件。
1、在终端执行安装命令：
dsh plugin --profile web add dsh-a2a-server
2、安装后，插件处于 PENDING 状态，直到依赖的服务就绪。该插件需要以下上下文服务：
* ctx.agents
* ctx.credentials
* ctx.webServer（由 dsh-web-app 提供）
* ctx.sessionProjections（可选，用于在结算后获取任务）
典型用法¶
安装完成后，可以通过以下步骤启动服务并测试交互。
1、在插件目录下安装依赖并启动服务器。以下命令启动服务，监听端口 9922，并配置了一个名为 alice 的对端，令牌为 demo123：
pnpm install
A2A_PEERS="alice:demo123" A2A_PORT=9922 pnpm serve
2、获取 Agent Card，验证服务是否正常：
curl -s http://127.0.0.1:9922/.well-known/agent-card.json
3、提交任务。使用 SendMessage 方法发送一条文本消息：
curl -s http://127.0.0.1:9922/a2a \
-H "authorization: Bearer demo123" \
-H 'content-type: application/json' \
-H 'a2a-version: 1.0' \
-d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"messageId":"m1","role":"ROLE_USER","parts":[{"text":"hello"}]}}}'
4、使用官方提供的探测脚本验证接口合规性：
node example/probe.mjs http://127.0.0.1:9922 demo123
注意事项与限制¶
- 仅限入站模式：该插件不会主动连接到其他智能体，没有客户端或对端目录功能。
- 版本兼容性：该插件仅支持 A2A v1.0 协议。v0.3 协议的方法名、类型定义等均不兼容，且不支持 v0.3。如果请求中未指定
A2A-Version，默认视为 1.0。 - 运行环境依赖：对于无头配置文件（headless profile），必须挂载
@deepseek-ai/dsh-host-webserver以提供ctx.webServer。 - 凭证解析：模型的凭证通过
ctx.credentials解析，例如从环境变量DEEPSEEK_API_KEY中读取。
结语¶
dsh-a2a-server 为 DeepSeek Harness 提供了接入 Agent2Agent 生态的基础设施。对于需要在 DSH 中运行智能体并希望其被外部系统调用的开发者，该插件提供了标准化的接口和发现机制。相关代码与文档位于 GitHub。
