dsh-a2a
dsh-a2a：DeepSeek Harness 的 A2A v1.0——将该 harness 暴露为 A2A agent，并从 agent 工具调用远程 A2A agents。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-a2a@0.7.1A2a 以 dsh-a2a 发布，当前版本为 0.7.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A2A v1.0 for DeepSeek Harness — expose the harness as an A2A agent, and let harness agents delegate to remote A2A agents.
One plugin, two halves, built on the official @a2a-js/sdk (A2A Protocol v1.0):
contextId maps to a persistent harness session, so follow-up messages continue the same conversation.a2a_call / a2a_list model tools, so harness agents can delegate work to remote A2A agents from a config-driven registry with header auth./agents/<id> with its own preset, model route, workspace group, Agent Card identity, and skills; one contextId maps to one persistent harness session per agent (deterministic sha256(contextId) ids), preset-mounted, persistent across turns.AgentSkill[] (id / name / description) on its own card, so an A2A client can route by what an agent is for./.well-known/agent-card.json, JSON-RPC SendMessage / SendStreamingMessage / GetTask / CancelTask / ListTasks (SSE for streaming), REST message:send / tasks/* — all through the official SDK's request handler.${ENV_VAR} placeholders resolved at call time; credentials never sit in the config.server.apiKey set, every request except the Agent Card must present Authorization: Bearer <key>; the card can also advertise a publicUrl behind a reverse proxy.metadata map instead of using the deployment's route (see Per-request overrides).A2A, ~/.a2a-sessions by default).turnTimeoutMs, default 5 min) so the next message is never stuck.dsh plugin --profile web add dsh-a2a
export A2A_HOST=127.0.0.1
export A2A_PORT=8899
dsh web # restart, then GET http://127.0.0.1:8899/.well-known/agent-card.json
Call the agent (JSON-RPC, blocking):
curl -s http://127.0.0.1:8899/ -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"role":"user","messageId":"m1","parts":[{"kind":"text","text":"hi"}],"contextId":"demo"}}}'
A2A_ENABLED=0 runs the client tools only (no listener).
The mounted row lives in ~/.dsh/profiles/web/cordis.patch.yml:
- id: a2a
name: dsh-a2a
config:
server:
enabled: true # serve the A2A endpoint at all
host: 127.0.0.1 # A2A_HOST
port: 8899 # A2A_PORT
turnTimeoutMs: 300000 # per-turn deadline
allowOverrides: true # let callers pick preset/model per request
agents: # LOCAL agents served at /agents/<id>
- id: support
name: Support Agent
description: Answers internal support questions.
version: '0.1.0'
preset: standard
workspaceTitle: A2A
skills:
- id: query-orders
name: Query orders
description: Look up an order's status and timeline.
agents: [] # remote agents reachable from a2a_call
Each local agent lives at /agents/<id>/.well-known/agent-card.json and gets a
session namespace (a2a-<id>-<hash>), its own workspace group, and its own
Agent Card. The legacy single-agent form (server.preset / server.agentCard)
still works: when server.agents is empty, one agent is derived from it.
| Field | Default | Meaning |
|---|---|---|
server.enabled | true | Serve the A2A endpoint; client tools work regardless |
server.host / server.port | 127.0.0.1 / 8899 | Listen address (env A2A_HOST / A2A_PORT) |
server.preset | standard | Preset mounted into each A2A conversation agent |
server.turnTimeoutMs | 300000 | Per-turn deadline; a slow turn is cancelled |
server.allowOverrides | true | Whether callers may pick preset/model per request via metadata; when false their overrides are dropped (and logged) |
server.publicUrl | — | Public URL advertised on the Agent Card (required behind a reverse proxy); env A2A_PUBLIC_URL |
server.apiKey | — | When set, every request except the Agent Card must present Authorization: Bearer <key>; env A2A_API_KEY |
server.provider / server.model | — | Model route for A2A conversations, must be set as a pair; falls back to the harness default model; env A2A_PROVIDER / A2A_MODEL |
server.cwd | ~/.a2a-sessions | Working directory for A2A conversations (doubles as the sidebar workspace path); env DSH_A2A_CWD |
server.workspaceTitle | A2A | Sidebar group title for A2A conversations |
server.agents[].id | — | URL slug under /agents/ (must be URL-safe), e.g. support |
server.agents[].name / description / version | — | This agent's Agent Card identity |
server.agents[].preset | — | Preset mounted into this agent's conversations |
By default every conversation uses the deployment's route: the configured server.preset and provider/model pair. A caller can pick its own instead by naming them on the A2A metadata map:
curl -s http://127.0.0.1:8899/ -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{
"message":{"role":"user","messageId":"m1","parts":[{"kind":"text","text":"hi"}],"contextId":"demo"},
"metadata":{"agentPreset":"general","model":"model-a"}
}}'
| Key | Aliases | Meaning | Applies |
|---|---|---|---|
agentPreset | preset | Preset id to compose the agent from, overriding server.preset | on the request that creates the session |
model | — | Model id, overriding server.model | on every request, and it sticks for the rest of the session |
provider | — | Provider route, paired with the configured (or default) model | on every request |
The two ride different lifetimes because the harness gives them different ones:
preset on a later turn is ignored and logged: swapping tools mid-conversation would leave tool calls the new composition cannot make. Send the preset on the first message (or use a fresh contextId).Precedence and edge cases:
params.message.metadata wins over params.metadata; writing the same value to both — as the REST message:send shape invites — is unambiguous, and callers that only know one of them still work.model is paired with server.provider, falling back to the harness default model's provider: callers know the model they want, not the route serving it. Without any provider to pair with, the task fails rather than answering on a model the caller did not ask for.server.allowOverrides: false to lock the deployment's route: overrides are then dropped and logged, and the request is still answered.dsh assemblies are layered: the bundle's own patch (npm-distributed) → the profile's cordis.patch.yml → environment variables. When giving a deployment its own identity, put each piece on the right layer:
cordis.patch.yml generic — it reaches every npm consumer, so never bake deployment-specific identity (a bespoke preset, a dedicated Agent Card name/description) into it.a2a row by id in ~/.dsh/profiles/web/cordis.patch.yml (no - insert: prefix, and spell out the full server block):# ~/.dsh/profiles/web/cordis.patch.yml
- id: a2a
name: dsh-a2a
config:
server:
enabled: true
host: 127.0.0.1
port: 8899
preset: my-support-preset # deployment-specific preset
turnTimeoutMs: 300000
agentCard:
name: My Support Agent # deployment-specific identity
description: Answers internal support questions.
version: '0.1.0'
agents: []
publicUrl / apiKey / provider / model never sit in any YAML; keep the !!js process.env.XXX expressions and inject the values at launch (systemd users can use EnvironmentFile):# /etc/dsh-web.env (systemd EnvironmentFile example)
A2A_PUBLIC_URL=https://gateway.example.com/
A2A_API_KEY=<secret>
A2A_PROVIDER=venus
A2A_MODEL=model-b
Patch-layer changes are read at assembly time — restart dsh web to apply them. The GUI registry (agents) is the exception: saves hot-reload.
| Tool | What it does |
|---|---|
a2a_list | Lists the registered remote A2A agents (name + description). |
a2a_call | Sends a prompt to one registered agent and returns its completed text reply. |
/agents/<id>/... with its own Agent Card, JSON-RPC + REST surface, preset-mounted executor, and session namespace. The root /.well-known/agent-card.json returns the first agent (there is no default agent at /); server.agents[] is the multi-agent form, and the legacy single-agent config derives one agent. Lifecycle is tied to the Cordis fiber — the listener starts on plugin load and closes (sockets included) on plugin disposal.AgentExecutor contract: publish a task event, run one harness turn (followup → whenIdle with deadline → cancel on timeout), publish the reply as a message event, then a terminal statusUpdate. CancelTask reaches the right agent through the running-task table. The executor per agent is keyed by contextId (session namespace a2a-<agentId>-<hash>), so follow-up turns continue the same conversation.ClientFactory (JSON-RPC + REST transports) with an authenticating fetch that injects the per-agent headers.server.apiKey enforces a Bearer token on every request except the Agent Card (which must stay publicly readable); for larger deployments, still put the port behind an authenticating gateway or a reverse proxy. The Agent Card advertises no security schemes./agents/<id> gets its own); sessions resume across turns but a dsh restart creates fresh in-memory state. The root /.well-known/agent-card.json returns the first agent only — address a specific agent at /agents/<id>/....model override switches sessions this executor instance created. One adopted from outside it — opened in the web UI, or resumed from disk — has no route handle to switch, so the override is logged and ignored; the reply keeps the model it was created with. Sending the model again after the executor creates the session works as expected.a2a settings namespace (schema defaults → row-config base → user overrides); a save hot-reloads the running tools, and a reset re-inherits the deployment registry.npm run check # biome + typecheck + vitest (59 tests) + build
The suite covers config validation, the Agent Card + JSON-RPC round trip through the official A2A client against a real HTTP listener, per-context session continuity, task cancellation, header auth, per-request overrides, and the model-facing tools.
server.agents[].provider / model | — | This agent's model route (must be a pair); falls back to the harness default |
server.agents[].cwd / workspaceTitle | server.cwd / A2A | This agent's workspace directory / group title |
server.agents[].skills | [] | A2A AgentSkill[] (id / name / description) advertised on this agent's card |
server.agentCard.* | — | Legacy single-agent identity (used when server.agents is empty) |
agents[].name / url | — | Remote registry name for a2a_call + Agent Card URL |
agents[].headers | {} | Request headers; ${ENV_VAR} placeholders resolved at call time |
agents[].description | '' | Shown by a2a_list |