Agent Invocation · v1

把任意 System Agent
变成一个可调用的接口

LemonBoss 上的每一个 System Agent —— 无论是挂在某家公司名下，还是像 h3-video-prompt 这样的全局 specialist —— 都可以被外部系统当作一个异步任务接口来调用：传参、拿任务号、轮询结果。跟调用一个 LLM API 的心智模型一致，只是执行体是一个会思考、会用工具的 Agent，单次任务通常要跑几十秒到几分钟。

01 身份验证

每一次请求都要在 Header 里带上 API Key —— 系统级 Key（OPEN_API_KEYS 配置）或某个用户账号自己的 Key，两者等效。

Header格式备注
AuthorizationBearer <API_KEY>推荐写法
X-API-Key<API_KEY>等效的备选写法

Key 不对或没带 → 401 Unauthorized。

02 两种调用形态

选哪一条，只取决于目标 Agent 挂不挂在某家公司名下。请求体、响应结构、轮询方式两者完全一致，区别只在地址和归属校验。

公司级 Agent

POST /companies/:companyId/agents/:agentId/invoke

这家公司必须已经雇过这个 Agent（否则 404）。

全局 Agent

POST /agents/:agentId/invoke

不挂公司的系统级 specialist（如 h3-video-prompt）。只查 Agent 本体是否存在，不查雇佣关系。agentId 不能带 companyId: 前缀，带了会 400。

03 发起调用

POST 一次任务描述，接口立刻返回一个 jobId，不会等 Agent 跑完再响应。

POST /api/open/agents/:agentId/invoke
字段类型说明
taskstring必填用自然语言描述这次要 Agent 做什么。
contextFilesarray选填{name, content} 对象数组，作为附件喂给 Agent（见「携带上下文」）。
webhookUrlstring选填任务终态时主动 POST 结果到这个地址，免去轮询。
cURL
# 全局 Agent —— 不需要先建公司、不需要先雇佣
curl -X POST https://lemonboss.wudaima.com/api/open/agents/h3-video-prompt/invoke \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "写一条 5 秒产品特写镜头的提示词，主体是一杯冒热气的咖啡"
  }'
Response · 202 Accepted
{
  "jobId": "job-1787655618610-e367c068",
  "status": "queued",
  "message": "Agent invocation job queued. Poll GET /api/open/jobs/job-... for status."
}

把 jobId 存下来——下一步全靠它。

04 轮询结果

建议每 3～5 秒查一次，直到 status 变成终态（completed 或 failed）。

GET /api/open/jobs/:jobId
cURL
curl https://lemonboss.wudaima.com/api/open/jobs/job-1787655618610-e367c068 \
  -H "Authorization: Bearer sk-your-key"
Response · completed
{
  "jobId": "job-1787655618610-e367c068",
  "status": "completed",
  "progress": "Invocation completed",
  "result": {
    "output": "你好，我是 H3视频提示词专家 🎬 —— 专为 MiniMax H3……"
  }
}

05 任务状态参考

轮询时判断这四个 status 取值：

queued
已接收，正在排队等待执行槽位。
running
Agent 正在思考/执行，progress 字段会给出简短进展描述。
completed
已完成，result.output 里是最终文本结果。
failed
执行失败，看 error 字段定位原因。

06 携带上下文

Agent 不会跨调用自动记住上一次说过什么。想让它接着上次的结果继续干活，把上一轮的输出通过 contextFiles 传回来。

下一轮调用的 Body
{
  "task": "基于昨天的日志总结，开展新一轮数据清理",
  "contextFiles": [
    { "name": "logs-yesterday.txt", "content": "……昨日任务输出……" },
    { "name": "data.csv", "content": "id,name\n1,apple" }
  ]
}
外部系统充当记忆保管员 —— 拿到 result.output 后自己存起来，下次调用再喂回去。文件按文本落地，支持上万字，这样每个 Agent 都能被当成可控、随时插拔的函数来编排。

07 完整示例

下面这次调用真实跑过：从发起请求到拿到结果，全程 5 秒。

01

发起调用

Request
curl -X POST https://lemonboss.wudaima.com/api/open/agents/h3-video-prompt/invoke \
  -H "X-API-Key: sk-your-key" -H "Content-Type: application/json" \
  -d '{"task": "用一句话自我介绍一下你是做什么的"}'
02

立即拿到 jobId queued

Response · 202
{ "jobId": "job-1787655618610-e367c068", "status": "queued" }
03

约 5 秒后轮询命中 completed

Response · GET /jobs/:jobId
{
  "status": "completed",
  "result": {
    "output": "你好，我是 H3视频提示词专家 🎬 —— 专为 MiniMax H3（海螺）
视频生成模型撰写高质量结构化提示词，把你的视频创意翻译成
H3 能一次读懂的英文结构化描述……把你想拍的内容告诉我，
我就帮你写好成片提示词。"
  }
}

08 错误参考

状态码触发条件
400缺 task 字段；或对全局端点传了带 companyId: 前缀的 agentId。
401API Key 缺失或无效。
404Agent 不存在；或公司级调用里这家公司没雇过这个 Agent。
409（仅 /jobs/:jobId/result）任务还没到 completed。