宜博 / lemonboss

Commit 708d4103d158ac316106715151842d12f40eeb63

Authored by yibo
1 parent 1569dad4

docs(open-api): 手册补全局 Agent invoke 端点 

POST /api/open/agents/:agentId/invoke（h3-video-prompt 这类不挂公司的
全局 Agent）跟公司级 invoke 是同一套请求体/轮询流程，只是端点和「查
存在还是查雇佣」不同，补一段区分说明 + 示例。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Inline Side-by-side
Showing 1 changed file with 22 additions and 2 deletions
docs/done/open-api-manual.md
  View file @708d410
@@ -30,8 +30,16 @@ OPEN_API_KEYS=sk-test-key-001,sk-prod-key-... @@ -30,8 +30,16 @@ OPEN_API_KEYS=sk-test-key-001,sk-prod-key-...
30 30
31 ### 接口 ①：指派任务并获取 JobId (Invoke) 31 ### 接口 ①：指派任务并获取 JobId (Invoke)
32 32
33 -**🔹 端点**：`POST /api/open/companies/:companyId/agents/:agentId/invoke`  
34 -**🔹 作用**：唤起指定公司和指定名称的 Agent 执行任务。 33 +两个变体，选哪个只看这个 Agent 挂不挂在某家公司名下：
  34 +
  35 +- **公司级 Agent**：`POST /api/open/companies/:companyId/agents/:agentId/invoke`
  36 + 这家公司必须已经雇过这个 Agent（`company_agents` 里有登记），没雇过一律 404。
  37 +- **全局 Agent**：`POST /api/open/agents/:agentId/invoke`
  38 + 面向不挂任何公司的系统级 specialist（比如 `master`、`agent-creator`、`h3-video-prompt`
  39 + 这类），不查雇佣关系，只查这个 Agent 本体存不存在。`agentId` 里不能带 `companyId:role`
  40 + 这种冒号前缀——那是公司级 Agent 的地址形态，传了会直接 400，提示改走上面那条。
  41 +
  42 +两者的请求体、返回值、轮询方式完全一样，下面统一说明。
35 43
36 #### 请求参数 (Body) 44 #### 请求参数 (Body)
37 45
@@ -42,6 +50,8 @@ OPEN_API_KEYS=sk-test-key-001,sk-prod-key-... @@ -42,6 +50,8 @@ OPEN_API_KEYS=sk-test-key-001,sk-prod-key-...
42 | `webhookUrl` | String | 选填 | 回调地址。当任务完结时主动推送结果至该URL。| `"https://your-app/webhook"`| 50 | `webhookUrl` | String | 选填 | 回调地址。当任务完结时主动推送结果至该URL。| `"https://your-app/webhook"`|
43 51
44 #### 代码示例 (cURL) 52 #### 代码示例 (cURL)
  53 +
  54 +公司级 Agent：
45 ```bash 55 ```bash
46 curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-youtube-skills/invoke \ 56 curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-youtube-skills/invoke \
47 -H "Authorization: Bearer sk-test-key-001" \ 57 -H "Authorization: Bearer sk-test-key-001" \
@@ -57,6 +67,16 @@ curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-yo @@ -57,6 +67,16 @@ curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-yo
57 }' 67 }'
58 ``` 68 ```
59 69
  70 +全局 Agent（不带 companyId）：
  71 +```bash
  72 +curl -X POST https://lemonboss.wudaima.com/api/open/agents/h3-video-prompt/invoke \
  73 + -H "Authorization: Bearer sk-test-key-001" \
  74 + -H "Content-Type: application/json" \
  75 + -d '{
  76 + "task": "帮我写一条 5 秒产品特写的 H3 视频提示词，主体是一杯冒着热气的咖啡"
  77 + }'
  78 +```
  79 +
60 #### 返回值 80 #### 返回值
61 接口会光速返回 HTTP 202 的响应该结果： 81 接口会光速返回 HTTP 202 的响应该结果：
62 ```json 82 ```json