面板 API
面板 API
这页回答 /a2a/api 有哪些读端点和控制动作,每个请求与响应的形状是什么。读者是写脚本、做集成或排查面板行为的人。前提是 DSH web 已经启动,调用方在本机回环地址上。它是 A2A 接口 的本机控制面:那边讲远端客户端能调的线协议,这边讲只给本机脚本和面板用的接口。facade、preset、artifact、contextId 这些词见导读的术语表;TaskRecord(面板读到的任务记录)与 A2A 端点返回的 Task 的对照在本页最后一节。
下文统一用 http://127.0.0.1:3080。没有配置 baseUrl(卡片对外地址)或宿主也没报端口时会回退到 3000,以实际监听为准。
信任边界与状态码
/a2a/api 只接受来自 127.0.0.1、::1、::ffff:127.0.0.1 的连接。其它来源直接拿到:
forbidden请求体上限固定 1 MB,与 A2A 端点的 maxBodyBytes(A2A 配置项,见运维与排障的配置表)无关。
| 状态 | 条件 |
|---|---|
200 | 读取成功,或动作返回 ok: true |
400 | POST 的 body 解析不了 JSON |
403 | 发起请求的地址不在回环范围 |
404 | card 或 task 的 id 不存在 |
405 | 方法不是 GET / POST |
409 | 动作返回 ok: false,或 /a2a/api/session 的上下文有歧义 |
413 | 请求体超过 1 MB |
动作失败时返回 409,body 是动作结果:
{
"ok": false,
"message": "task a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10 not found or already terminal"
}400 与 413 也返回 JSON。403 与 405 是纯文本。POST 的 body 必须是 { "action": "...", ... }。动作名未知时返回 409,message 里带未知的动作名。
快照与读端点
| 方法与路径 | 返回 |
|---|---|
GET /a2a/api | 快照:version、inbounds、outbounds、tasks、taskTotal、taskNextOffset、peers、sessions、metrics |
GET /a2a/api/presets | [{ id, name?, description?, isDefault? }] |
GET /a2a/api/update | 版本号与更新查询。带 ?refresh=1 时不读缓存 |
GET /a2a/api/card?id=<inbound> | 一个入站实例的 AgentCard |
GET /a2a/api/task?id=<task> | 一条 TaskRecord |
GET /a2a/api/session?contextId=<id>&serverId=<instance> | 该上下文的消息列表 |
GET /a2a/api/metrics | 指标快照 |
快照支持 taskLimit(默认 50)、taskOffset、taskState、taskContextId、taskServerId。没有列出的 GET /a2a/api/* 会回退到快照,不返回 404。只有 card 和 task 的未知 id 是 404。
GET /a2a/api/card?id= 返回实例当前的 AgentCard。字段见A2A 接口的卡片一节。
GET /a2a/api/task?id= 返回 TaskRecord,不是线协议 Task:
{
"taskId": "a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10",
"contextId": "0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31",
"skill": "chat",
"state": "TASK_STATE_COMPLETED",
"createdAt": "2026-11-18T02:10:09.001Z",
"updatedAt": "2026-11-18T02:10:11.482Z",
"sessionId": null,
"remotePeerId": null,
"parts": [{ "text": "统计这三个文件的行数" }],
"artifacts": [
{ "artifactId": "result", "parts": [{ "text": "三个文件共 812 行。" }] }
],
"executor": "session",
"summary": null,
"serverId": "reports-1a2b3c4d",
"messageIds": ["m-1"],
"inputs": [
{
"messageId": "m-1",
"contextId": "0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31",
"taskId": "a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10",
"role": "ROLE_USER",
"parts": [{ "text": "统计这三个文件的行数" }]
}
]
}error 只在任务失败、取消或中断时出现。statusText 只在有非错误状态文本时出现。trace 只在激活过扩展时出现。这三个字段都是可选的。
GET /a2a/api/session?contextId=<id> 返回该上下文的派生 DSH 消息数组:
[
{ "role": "user", "content": [{ "type": "text", "text": "统计这三个文件的行数" }] },
{ "role": "assistant", "content": [{ "type": "text", "text": "三个文件共 812 行。" }] }
]示例只列 role 与 content。完整的 DSH 消息还带 id、source 等字段,也可能包含 reasoning block。
这个端点只用于回环调试,不属于 A2A 线协议。上下文没有活句柄时返回 []。同一个 contextId 同时被多个实例持有时返回 409,要带 serverId 再查。
快照示例:
{
"version": "0.5.5",
"inbounds": [
{
"id": "reports-1a2b3c4d",
"name": "reports",
"description": "Reporting agent",
"version": "0.1.0",
"endpointPath": "/a2a/reports-1a2b3c4d",
"preset": "standard",
"cardPath": "/a2a/reports-1a2b3c4d/agent-card.json",
"cardUrl": "http://127.0.0.1:3080/a2a/reports-1a2b3c4d",
"enabled": true,
"trace": false,
"skills": [{ "id": "chat", "name": "chat", "description": "Conversational assistance over a DSH agent session." }]
}
],
"outbounds": [
{
"id": "out-2c6d9dbdcf6a",
"name": "remote",
"agentCardUrl": "https://remote.example/a2a/x/agent-card.json",
"enabled": true,
"timeoutMs": 60000,
"state": "connected",
"skillCount": 1,
"toolCount": 1,
"skills": [{ "id": "chat", "name": "chat", "enabled": true }],
"agentVersion": "1.0.0",
"lastCardAt": "2026-11-18T02:00:00.000Z"
}
],
"tasks": [
{
"taskId": "a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10",
"contextId": "0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31",
"skill": "chat",
"state": "TASK_STATE_COMPLETED",
"createdAt": "2026-11-18T02:10:09.001Z",
"updatedAt": "2026-11-18T02:10:11.482Z",
"sessionId": null,
"remotePeerId": null,
"parts": [{ "text": "统计这三个文件的行数" }],
"artifacts": [{ "artifactId": "result", "parts": [{ "text": "三个文件共 812 行。" }] }],
"executor": "session",
"summary": null,
"serverId": "reports-1a2b3c4d",
"messageIds": ["m-1"],
"inputs": [
{
"messageId": "m-1",
"contextId": "0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31",
"taskId": "a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10",
"role": "ROLE_USER",
"parts": [{ "text": "统计这三个文件的行数" }]
}
]
}
],
"taskTotal": 1,
"taskNextOffset": null,
"peers": [
{
"id": "peer-6d2f4a1c",
"label": "127.0.0.1:54321",
"source": "127.0.0.1:54321",
"firstSeen": "2026-11-18T02:10:09.000Z",
"lastSeen": "2026-11-18T02:10:11.482Z",
"taskCount": 1,
"activeTaskIds": [],
"streaming": false
}
],
"sessions": [
{
"contextId": "0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31",
"sessionId": "a2a-reports-1a2b3c4d-0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31",
"serverId": "reports-1a2b3c4d",
"serverName": "reports",
"preset": "standard",
"status": "idle",
"taskCount": 1,
"activeCount": 0,
"firstSeen": "2026-11-18T02:10:09.001Z",
"lastSeen": "2026-11-18T02:10:11.482Z",
"streaming": false,
"live": true
}
],
"metrics": {
"startedAt": "2026-11-18T02:00:00.000Z",
"uptimeMs": 600000,
"requests": 12,
"authFailures": 0,
"tasks": { "created": 1, "completed": 1, "failed": 0, "canceled": 0, "interrupted": 0, "avgDurationMs": 2481, "maxDurationMs": 2481 },
"outbound": { "calls": 2, "errors": 0, "avgDurationMs": 320 },
"byServer": {},
"audit": []
}
}version 是已安装的插件版本。inbounds[].trace 是最终生效的值,已经算进部署开关。outbounds[].agentVersion 只有连接建立后才出现。taskNextOffset 为 null 表示没有下一页。
入站动作
所有动作都是 POST /a2a/api,成功返回 200,失败返回 409。
| action | 请求 | 成功响应 |
|---|---|---|
inbound.create | {"action":"inbound.create","name":"reports","description":"Reporting agent","version":"0.1.0","enabled":true} | {"ok":true,"message":"inbound server \"reports\" created","id":"reports-1a2b3c4d"} |
inbound.update | {"action":"inbound.update","id":"reports-1a2b3c4d","name":"reports-v2"} | {"ok":true,"message":"inbound server reports-1a2b3c4d updated"} |
inbound.remove | {"action":"inbound.remove","id":"reports-1a2b3c4d"} | {"ok":true,"message":"inbound server reports-1a2b3c4d removed"} |
inbound.enable | {"action":"inbound.enable","id":"reports-1a2b3c4d"} | {"ok":true,"message":"inbound server reports-1a2b3c4d enabled"} |
inbound.disable | {"action":"inbound.disable","id":"reports-1a2b3c4d"} | {"ok":true,"message":"inbound server reports-1a2b3c4d disabled"} |
inbound.setAuth | {"action":"inbound.setAuth","id":"reports-1a2b3c4d","token":"s3cr3t"} | {"ok":true,"message":"inbound server reports-1a2b3c4d auth set (A2A_INBOUND_REPORTS_1A2B3C4D)"} |
inbound.sendTest | {"action":"inbound.sendTest","id":"reports-1a2b3c4d","text":"hello","skill":"chat"} | {"ok":true,"message":"test message submitted","task":{"id":"a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10","status":{"state":"TASK_STATE_COMPLETED","timestamp":"2026-11-18T02:10:11.482Z"}}} |
inbound.close | {"action":"inbound.close","id":"peer-6d2f4a1c"} | {"ok":true,"message":"inbound peer peer-6d2f4a1c closed"} |
inbound.create 的 id 是名称 slug 加 8 位十六进制。inbound.setAuth 把 token 写进 credentials 服务的托管名,记录里只留这个名字。空 token 表示清除。inbound.close 的 id 是对端 id,不是实例 id。它会先取消该对端的活跃任务,再删对端记录。
inbound.sendTest 返回的 task 是线协议 Task,不是 TaskRecord。它走相同的技能门禁与任务流程,只是不做 HTTP 鉴权:
{
"ok": true,
"message": "test message submitted",
"task": {
"id": "a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10",
"contextId": "0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31",
"status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2026-11-18T02:10:11.482Z" },
"artifacts": [{ "artifactId": "result", "parts": [{ "text": "三个文件共 812 行。" }] }],
"metadata": { "skill": "chat", "serverId": "reports-1a2b3c4d" }
}
}出站动作
| action | 请求 | 成功响应 |
|---|---|---|
outbound.create | {"action":"outbound.create","name":"remote","agentCardUrl":"https://remote.example/a2a/x/agent-card.json","timeoutMs":60000} | {"ok":true,"message":"agent \"remote\" connected","id":"out-2c6d9dbdcf6a"} |
outbound.update | {"action":"outbound.update","id":"out-2c6d9dbdcf6a","timeoutMs":5000,"disabledSkills":["coding"]} | {"ok":true,"message":"outbound server out-2c6d9dbdcf6a updated"} |
outbound.remove | {"action":"outbound.remove","id":"out-2c6d9dbdcf6a"} | {"ok":true,"message":"outbound server out-2c6d9dbdcf6a removed"} |
outbound.enable | {"action":"outbound.enable","id":"out-2c6d9dbdcf6a"} | {"ok":true,"message":"agent agent-5f3c1a2b-7d4e-4a91-8c2f-3b6d1e0a9c47 enabled"} |
outbound.disable | {"action":"outbound.disable","id":"out-2c6d9dbdcf6a"} | {"ok":true,"message":"agent agent-5f3c1a2b-7d4e-4a91-8c2f-3b6d1e0a9c47 disabled"} |
outbound.refresh | {"action":"outbound.refresh","id":"out-2c6d9dbdcf6a"} | {"ok":true,"message":"agent \"remote\" reconnected"} |
outbound.setAuth | {"action":"outbound.setAuth","id":"out-2c6d9dbdcf6a","token":"s3cr3t"} | {"ok":true,"message":"outbound server out-2c6d9dbdcf6a auth set (A2A_OUTBOUND_OUT_2C6D9DBDCF6A)"} |
outbound.discover | {"action":"outbound.discover","agentCardUrl":"https://remote.example/a2a/x/agent-card.json","token":"s3cr3t"} | {"ok":true,"message":"discovered \"remote\"","preview":{"name":"remote","version":"1.0.0","endpoint":"https://remote.example/a2a/x","skills":[{"id":"chat","name":"chat"}]}} |
outbound.update 只改名称、preset、超时、禁用技能和技能覆盖,不改 agentCardUrl。换远端卡片要删掉连接再建。
outbound.enable 的响应文案随分支变化:没有活连接、需要重连的实例返回 agent <agentId> enabled;启动时就禁用、连视图都没有的实例只写记录,返回 outbound server <id> marked enabled。已经连上的实例返回 agent <agentId> already enabled。这些文案不要当契约,按 ok 判断成败。
outbound.disable 停用时会注销工具并 dispose 活连接,视图落 disconnected,skillCount 与 toolCount 清零。
outbound.discover 的 preview:
{
"name": "remote",
"version": "1.0.0",
"description": "Remote agent",
"endpoint": "https://remote.example/a2a/x",
"skills": [{ "id": "chat", "name": "chat" }]
}它只读远端卡片,不建连接,也不改状态。token 只用于这次读取,不会保存。
任务与会话动作
| action | 请求 | 成功响应 |
|---|---|---|
task.cancel | {"action":"task.cancel","id":"a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10"} | {"ok":true,"message":"task a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10 canceled"} |
session.cancel | {"action":"session.cancel","id":"0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31","serverId":"reports-1a2b3c4d"} | {"ok":true,"message":"session 0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31: canceled 1 active task(s)"} |
session.close | {"action":"session.close","id":"0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31"} | {"ok":true,"message":"session 0f3b6c2a-8d41-4e77-9a10-5c6b7e8f2a31: closed 1 live session(s)"} |
task.cancel 中止该任务的执行器,把状态落 CANCELED。任务不存在或已经终态时 ok: false,HTTP 409。
session.cancel 只停掉该上下文里还没结束的任务,句柄不释放。session.close 先停任务,再放掉该上下文的活句柄。同一上下文下次来任务时会新开一个。两者都可以带 serverId 限定实例。不带时跨实例匹配同一个 contextId。
session.cancel 没有活跃任务时仍返回 ok: true,message 是 session <id>: no active tasks。session.close 没有可取消或可释放的内容时也返回 ok: true。
TaskRecord 与 Task 的字段对照
面板读端点与快照里的任务是 TaskRecord。A2A 端点返回的是线协议 Task。字段名不同,不要混用。
| 语义 | TaskRecord | Task |
|---|---|---|
| 任务 id | taskId | id |
| 上下文 | contextId | contextId |
| 状态 | state | status.state |
| 状态时间 | updatedAt | status.timestamp |
| 状态文本或错误 | error.message 或 statusText | status.message.parts[0].text |
| 输入 | parts、inputs[] | history[] 里的 ROLE_USER 消息 |
| 输出 | artifacts[] | artifacts[] |
| 技能 | skill | metadata.skill |
| 来源实例 | serverId | metadata.serverId |
| trace | trace | metadata[<trace URI>] |
| 会话 | sessionId | 不出现 |
| 对端 | remotePeerId | 不出现 |
| 执行器 | executor | 不出现 |
| 摘要 | summary | 不出现 |
| 幂等键 | messageIds[] | 不出现 |
| 创建时间 | createdAt | 不出现 |
TaskRecord 的 artifacts 元素只有 artifactId、name?、parts。线协议 Artifact 还允许 metadata,但入站不写。
指标与审计
GET /a2a/api/metrics 返回进程内计数与固定长度的审计环:
{
"startedAt": "2026-11-18T02:00:00.000Z",
"uptimeMs": 600000,
"requests": 12,
"authFailures": 1,
"tasks": {
"created": 3,
"completed": 2,
"failed": 1,
"canceled": 0,
"interrupted": 0,
"avgDurationMs": 1840,
"maxDurationMs": 2500
},
"outbound": { "calls": 4, "errors": 0, "avgDurationMs": 320 },
"byServer": {
"reports-1a2b3c4d": {
"requests": 12,
"authFailures": 1,
"tasksCreated": 3,
"tasksCompleted": 2,
"tasksFailed": 1,
"tasksCanceled": 0,
"tasksInterrupted": 0,
"taskDurationMs": 5520,
"outboundCalls": 0,
"outboundErrors": 0,
"outboundDurationMs": 0
}
},
"audit": [
{
"at": "2026-11-18T02:10:11.482Z",
"kind": "task.settled",
"serverId": "reports-1a2b3c4d",
"taskId": "a2a-1f7c9a2e-4b6d-4f1a-9c3e-2d5b8a7c6e10",
"detail": "TASK_STATE_COMPLETED in 2481ms"
}
]
}审计条目字段:at、kind、serverId?、taskId?、method?、source?、detail?。环的容量是 200 条,满了丢最旧的。指标与审计都只在当前进程内,重启清零。
面板行为
面板是 DSH 设置页的一个区块(插槽 settings.section),id 为 a2a,标题是「A2A 连接」,排序 90。它只调用 /a2a/api,不直接访问 A2A 端点。
- 挂载后立即拉一次快照,之后每 3 秒拉一次。组件卸载时清掉定时器。
- 任务列表默认 50 条,点「加载更多」每次加 50。后端上限 200。任务按
updatedAt倒序。 - 版本条挂载时查一次。宿主缓存 6 小时,只有点按钮才用
refresh=1重新请求。 - 测试控制台调
inbound.sendTest,走相同的门禁与生命周期,只是不做 HTTP 鉴权。只能从回环调用。 - 入站卡片可以打开当前 AgentCard、查看派生技能、启停、编辑、删除、清空鉴权。出站卡片可以导入、连接、刷新、编辑、禁用单个技能。
- 会话表按
(serverId, contextId)聚合并提供「取消活跃」与「关闭」。连接表按请求来源显示对端。