POST /run

发起一次 Agent Run，返回 SSE 事件流。这是 wesgine 最核心的端点。

POST /cells/{cellID}/run

请求参数

字段类型必填说明
actorstring✅请求主体标识（员工 ID / 用户 ID）
modelstring✅模型名称（如 gpt-4o、claude-sonnet-4-20250514）
messagesMessage[]✅消息列表
session_idstring否会话 ID（不传则创建新会话）
agent_idstring否Agent ID（使用指定 Agent 的配置）
provider_namestring否指定 Provider（不传则按策略自动路由）
thinking_levelstring否思考深度：none / low / medium / high
cycle_detect_overrideobject否覆盖循环检测阈值（见下方）

Message 格式

{
  "role": "user",
  "content": [
    {"type": "text", "text": "分析这份合同"},
    {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "..."}}
  ]
}
字段类型说明
rolestringuser / assistant / system
contentContentBlock[]内容块数组

ContentBlock 类型

type说明字段
text文本text
image图片source.type（base64 / url）、source.media_type、source.data
file_ref文件引用path

curl 示例

curl -N -X POST http://localhost:9091/cells/dept-legal/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "alice",
    "model": "gpt-4o",
    "session_id": "s-001",
    "agent_id": "contract-reviewer",
    "messages": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "审查这份合同的风险条款"}]
      }
    ]
  }'

-N 禁用 curl 缓冲，确保实时看到 SSE 事件。

响应

Content-Type: text/event-stream

data: {"type":"run_start","run_id":"run-a1b2c3","session_id":"s-001","model":"gpt-4o","timestamp":"2026-09-21T06:00:00Z"}

data: {"type":"turn_start","turn_num":1}

data: {"type":"stream_delta","content":"这份合同"}

data: {"type":"stream_delta","content":"存在以下风险："}

data: {"type":"stream_delta","content":"\n\n1. 违约金条款不明确..."}

data: {"type":"tool_start","tool_name":"read","call_id":"call-001","arguments":{"path":"contract.pdf"}}

data: {"type":"tool_end","call_id":"call-001","result":"[文件内容...]","is_error":false}

data: {"type":"turn_end","turn_num":1}

data: {"type":"done","reason":"end_turn","run_id":"run-a1b2c3"}

完整 SSE 事件类型参见 SSE 流式协议。

CycleDetect 覆盖

可以 per-Run 覆盖循环检测阈值（委派子 Run 可用更严格阈值）：

{
  "cycle_detect_override": {
    "action_term_threshold": 40,
    "identical_call_term_threshold": 5
  }
}

错误码

HTTP错误说明
400ErrActorRequiredactor 为空
400ErrModelRequiredmodel 为空
400ErrVisionNotSupported请求含图片但模型不支持 Vision
429—超出 MaxConcurrentRuns 配额
503—Cell 处于 Cold 状态（含 Retry-After: 5）

重要行为