ArenaSK Open API 外部调用操作手册

本手册详细说明了如何通过外部系统（如第三方业务系统、自动化流、外部脚本）跨平台调用 LemonBoss 平台内部已经部署的任意 Agent。

---

1. 认证配置 (Authentication)

调用系统的任何开放接口前，必须在 HTTP 标头 (Headers) 中携带你申请/配置的 API Key 密钥。

系统配置位置： 当前系统支持的 API Key 配置位于项目根目录的 .env 文件内：

OPEN_API_KEYS=sk-test-key-001,sk-prod-key-...

请求方式： 无论你用什么语言发送请求，请确保 HTTP Headers 包含以下任意一种格式：

• Authorization: Bearer <API_KEY> (推荐)
• X-API-Key: <API_KEY>

---

2. 核心调用流程

因为我们的 Agent 需要进行「思考与执行 (Plan & Execute)」，单次任务通常耗时数分钟。为了防止网络超时断连，我们的接口设计完全异步化 (Asynchronous)：

完整调用链路： 👉 外部发送请求 invoke ➔ 系统接管并返回单号 jobId ➔ 外部每隔几秒根据 jobId去查进度 poll ➔ 遇到 completed 则提取输出。

接口 ①：指派任务并获取 JobId (Invoke)

两个变体，选哪个只看这个 Agent 挂不挂在某家公司名下：

• 公司级 Agent：POST /api/open/companies/:companyId/agents/:agentId/invoke 这家公司必须已经雇过这个 Agent（company_agents 里有登记），没雇过一律 404。
• 全局 Agent：POST /api/open/agents/:agentId/invoke 面向不挂任何公司的系统级 specialist（比如 master、agent-creator、h3-video-prompt 这类），不查雇佣关系，只查这个 Agent 本体存不存在。agentId 里不能带 companyId:role 这种冒号前缀——那是公司级 Agent 的地址形态，传了会直接 400，提示改走上面那条。

两者的请求体、返回值、轮询方式完全一样，下面统一说明。

请求参数 (Body)

参数名	类型	必填	说明	示例
task	String	✅	需要 Agent 帮您执行的自然语言任务。	"帮我爬取并总结最新的 AI agent 趋势"
contextFiles	Array	选填	外部传递前置文件，Agent可以据此进行记忆连接或文档问答。	见下文详述
webhookUrl	String	选填	回调地址。当任务完结时主动推送结果至该URL。	"https://your-app/webhook"

代码示例 (cURL)

公司级 Agent：

curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-youtube-skills/invoke \
  -H "Authorization: Bearer sk-test-key-001" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "基于上次总结的结果，帮我提取其中所有的产品名称并生成CSV格式",
    "contextFiles": [
      {
        "name": "previous_result.md",
        "content": "这是一段之前的调查结果......"
      }
    ]
  }'

全局 Agent（不带 companyId）：

curl -X POST https://lemonboss.wudaima.com/api/open/agents/h3-video-prompt/invoke \
  -H "Authorization: Bearer sk-test-key-001" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "帮我写一条 5 秒产品特写的 H3 视频提示词，主体是一杯冒着热气的咖啡"
  }'

返回值

接口会光速返回 HTTP 202 的响应该结果：

{
  "jobId": "job-1712461931-abcdef12",
  "status": "queued",
  "message": "Agent invocation job queued. Poll GET /api/open/jobs/job-1712461931-abcdef12 for status."
}

此时你必须要把 jobId 记录下来！

---

接口 ②：轮询任务执行结果 (Status Polling)

我们推荐外部系统（例如你的脚本中）使用 while 循环或定时任务，每隔 3~5 秒钟调用一次该接口查询。

🔹 端点：GET /api/open/jobs/:jobId

代码示例 (cURL)

curl "http://YOUR_SERVER_IP:3010/api/open/jobs/job-1712461931-abcdef12" \
  -H "Authorization: Bearer sk-test-key-001"

返回值

你可以通过判断返回体中的 status 字段来得知进度：

1. 正在执行时（Running / Queued）

{
  "jobId": "job-1712461931-abcdef12",
  "status": "running",
  "progress": "Executing agent task...",
  "createdAt": "2026-04-07T12:00:00Z"
}

2. 任务已完成时（Completed） 🌟 此刻可以提取最终结果：

{
  "jobId": "job-1712461931-abcdef12",
  "status": "completed",
  "progress": "Invocation completed",
  "result": {
    "output": "你好！我已经完成了产品名称提取。这里是转换后的 CSV 格式内容...\n..."
  }
}

3. 任务失败异常时（Failed）

{
  "jobId": "job-1712461931-abcdef12",
  "status": "failed",
  "error": "Agent execution failed: process timeout."
}

---

3. 高级用法指南

如何保持“上下文记忆”或者“持续对话”？

Agent 是没有自动长久记忆跨系统调用流的。你在下一次调用相同的这个 Agent（比如第二天再调一次）时，如果想让它知道前面发生了什么，或者传递新的数据报告给它，一定要使用 contextFiles 数组结构！。

外部系统提取了上次的 result.output 后，在下次调用的 Body 中：

{
    "task": "基于我附加给你的日志总结，开展新一轮的数据清理",
    "contextFiles": [
        {
            "name": "logs-from-yesterday.txt",
            "content": "....提取的昨日任务输出大段文本...."
        },
        {
            "name": "data.csv",
            "content": "id,name\n1,apple"
        }
    ]
}

系统底座会自动将这 2 个对象落地成文件，以文本阅读的视角送入 Agent 的大脑供其深度理解（支持上万字）。通过这种 “外部系统充当记忆保管员 + API 动态投喂上下文文件” 的组合拳，就可以把这些 Agent 变成可控、随时插拔的智能化函数库！