Aetheris API Reference

April 19, 2026 · View on GitHub

面向 Aetheris v2.x 用户的 HTTP API 快速参考。完整契约见 api-contract.md。

Base URL

http://localhost:8080/api

认证

# Header 认证（当前实现）
Authorization: Bearer <token>

Jobs API

提交 Job

POST /api/runs
Content-Type: application/json

{
  "workflow_id": "agent_message",
  "input": {
    "agent_id": "refund-agent",
    "message": "请退款订单 order-123"
  }
}

Response:

{
  "job_id": "job-abc123",
  "status": "pending",
  "created_at": "2026-04-19T12:00:00Z"
}

查询 Job 状态

GET /api/jobs/:id

{
  "job_id": "job-abc123",
  "status": "parked",
  "agent_id": "refund-agent",
  "current_node": "wait_approval",
  "created_at": "2026-04-19T12:00:00Z"
}

发送 Signal（唤醒 Parked Job）

POST /api/jobs/:id/signal
Content-Type: application/json

{
  "correlation_key": "approval-abc123",
  "payload": {
    "approved": true,
    "reason": "客户投诉合理"
  }
}

获取执行 Trace

GET /api/jobs/:id/trace

{
  "job_id": "job-abc123",
  "timeline": [
    {"time": "12:00:00", "event": "JobCreated"},
    {"time": "12:00:05", "event": "StepStarted", "node": "query_order"},
    {"time": "12:00:10", "event": "ToolCompleted", "node": "query_order"},
    {"time": "12:00:15", "event": "JobParked", "node": "wait_approval", "correlation_key": "approval-abc123"},
    {"time": "15:12:30", "event": "SignalReceived", "payload": {"approved": true}},
    {"time": "15:12:35", "event": "StepStarted", "node": "send_refund"},
    {"time": "15:12:40", "event": "JobCompleted"}
  ]
}

获取 Replay 数据

GET /api/jobs/:id/replay

停止 Job

POST /api/jobs/:id/stop

获取 Job 事件流

GET /api/jobs/:id/events

Agents API

创建 Agent

POST /api/agents
Content-Type: application/json

{
  "name": "refund-agent",
  "description": "退款审批 Agent",
  "type": "react",
  "llm": "default",
  "tools": ["query_order", "send_refund"]
}

列出 Agents

GET /api/agents

获取 Agent 状态

GET /api/agents/:id/state

列出 Agent 的 Jobs

GET /api/agents/:id/jobs?status=running

Documents API

上传文档

POST /api/documents/upload
Content-Type: multipart/form-data

file: <binary>
knowledge_id: "kb-123"

列出文档

GET /api/documents?knowledge_id=kb-123

MCP Tool API

通过 MCP Gateway 注册的工具通过 MCP 协议调用，不走 REST API。

# 通过 MCP 协议列出工具
mcp__tools__list

# 通过 MCP 协议调用工具
mcp__tools__call
{
  "name": "mcp-github",
  "arguments": {
    "action": "search_repos",
    "query": "aetheris golang",
    "limit": 5
  }
}

System API

健康检查

GET /health

版本信息

GET /api/version

错误格式

所有错误返回统一格式：

{
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Job job-xxx not found",
    "details": {}
  }
}

常见错误码:

Code	HTTP Status	说明
`JOB_NOT_FOUND`	404	Job 不存在
`AGENT_NOT_FOUND`	404	Agent 不存在
`INVALID_SIGNAL_KEY`	400	correlation_key 不匹配
`JOB_NOT_PARKED`	400	Job 未在 Parked 状态，无法 Signal
`TOOL_NOT_FOUND`	404	工具未注册
`TOOL_EXECUTION_ERROR`	500	工具执行失败
`UNAUTHORIZED`	401	未认证
`RATE_LIMITED`	429	请求过于频繁

速率限制

端点	限制
`POST /api/runs`	100 req/min
`POST /api/jobs/:id/signal`	60 req/min
`GET /api/jobs/:id/*`	300 req/min