参考

HTTP API 和 ToolHost

HTTP server 暴露项目观测、用户控制动作、SSE 事件流，以及面向容器的 ToolHost。

Server

suzumio serve --host 0.0.0.0 --port 39400

当前 API 面向本地或可信网络使用。第一版尚未实现用户 API 鉴权。面向容器的 tool route 使用每个 agent 的 token。

约定

主题行为
Base URL默认 http://127.0.0.1:39400。
Body 格式POST route 使用 JSON；无 body 的 lifecycle action 除外。
列表限制?limit=n，最多 500。
错误根据 route 返回 plain text 或 JSON。
TokensProject 和 agent listing 响应会 redact agent token。

Health

GET /health

{
  "healthy": true
}

Projects

方法路径说明
GET/api/projects列出 SUZUMIO_ROOT 下的项目，每项是 project summary。
GET/api/projects/:projectProject summary，包含 redacted agents、recent turns 和 recent messages。
curl http://127.0.0.1:39400/api/projects/demo

Project Objects

方法路径说明
GET/api/projects/:project/agentsAgent records，token 已隐藏。
GET/api/projects/:project/messages?limit=100近期消息。
GET/api/projects/:project/events?limit=200近期事件。
GET/api/projects/:project/turns?limit=100近期 turn。
GET/api/projects/:project/tool-calls?limit=100近期工具调用。
GET/api/projects/:project/artifacts?limit=100Artifact registry。
GET/api/projects/:project/config/resolvedResolved YAML config，plain text。
GET/api/projects/:project/reportSubmitted final report 文本；未提交时返回提示。

用户控制动作

方法路径Body说明
POST/api/projects/:project/start空设置为 running 并 tick scheduler。
POST/api/projects/:project/stop空设置为 stopped。
POST/api/projects/:project/approve空设置为 completed。
POST/api/projects/:project/request-changes{ "recipient": "pm", "body": "..." }回到 running，发送 P1 用户消息，并 tick scheduler。
POST/api/projects/:project/messages{ "recipient": "pm", "priority": "P1", "body": "..." }创建消息并 tick scheduler。
curl -X POST http://127.0.0.1:39400/api/projects/demo/messages \
  -H 'content-type: application/json' \
  -d '{"recipient":"pm","priority":"P1","body":"Start."}'

/messages body 可包含 sender、recipient、channel、priority、body。使用 recipient 或 channel 其一。Priority 默认 P1。

SSE Stream

事件流以 Server-Sent Events 发送 SQLite events。它会先发送近期已有事件，然后每两秒轮询新事件。

GET /api/projects/:project/stream

event: message.created
data: { ...event row... }

ToolHost

Docker runner 使用 POST /tool 执行项目工具。这不是公共用户 API。

POST /tool
{
  "project": "demo",
  "agentId": "pm",
  "turnId": "turn_...",
  "token": "agent-private-token",
  "tool": "messages.send",
  "input": {
    "recipient": "user",
    "priority": "P1",
    "body": "Done."
  }
}

ToolHost 校验 token 与 agent 匹配，并确认工具在 agent allowlist 中。执行前记录 tool_calls，成功或失败后更新。

Core Tool Inputs

messages.send

{
  "recipient": "worker",
  "channel": "#project",
  "priority": "P2",
  "body": "Markdown message"
}

使用 recipient 或 channel 其一，channel 必须在配置中声明。

artifacts.publish

{
  "path": "relative/path/in/workspace.txt",
  "name": "optional-name.txt",
  "description": "What this artifact contains"
}

Path 相对 agent workspace。Suzumio 会复制文件到 artifact registry 并记录 SHA-256 hash。

artifacts.list

{}

completion.submit

{
  "report": "# Final Report\n\n..."
}

该工具写入 final-report.md，把项目设为 submitted，等待用户审批。

WebUI

根路径 / 提供内嵌 WebUI。第一版保持简单：项目选择器、消息表单、agents、messages、turns、events 和 artifacts。

下一步：路线图。