From dc48ebe1ea6c0f5ed7ccd39a5c9f0b0f36fd3408 Mon Sep 17 00:00:00 2001 From: yibo Date: Tue, 25 Aug 2026 19:21:29 +0800 Subject: [PATCH] docs(open-api): 存一份对外交付页面的 HTML 源文件 --- docs/done/open-api-manual.html | 520 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 520 insertions(+), 0 deletions(-) create mode 100644 docs/done/open-api-manual.html diff --git a/docs/done/open-api-manual.html b/docs/done/open-api-manual.html new file mode 100644 index 0000000..c557c10 --- /dev/null +++ b/docs/done/open-api-manual.html @@ -0,0 +1,520 @@ +Agent Invocation API + + + + + + +
+ + +
+
+

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。
+
+
+ +
+ LemonBoss Open API · Agent Invocation · 内部真相来源见仓库 docs/done/open-api-manual.md +
+
+
+ + -- libgit2 0.21.4