# ArenaSK Open API 外部调用操作手册

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

---

## 1. 认证配置 (Authentication)

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

**系统配置位置**：
当前系统支持的 API Key 配置位于项目根目录的 `.env` 文件内：
```ini
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：
```bash
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）：
```bash
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 的响应该结果：
```json
{
  "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)
```bash
curl "http://YOUR_SERVER_IP:3010/api/open/jobs/job-1712461931-abcdef12" \
  -H "Authorization: Bearer sk-test-key-001"
```

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

**1. 正在执行时（Running / Queued）**
```json
{
  "jobId": "job-1712461931-abcdef12",
  "status": "running",
  "progress": "Executing agent task...",
  "createdAt": "2026-04-07T12:00:00Z"
}
```

**2. 任务已完成时（Completed）** 🌟 此刻可以提取最终结果：
```json
{
  "jobId": "job-1712461931-abcdef12",
  "status": "completed",
  "progress": "Invocation completed",
  "result": {
    "output": "你好！我已经完成了产品名称提取。这里是转换后的 CSV 格式内容...\n..."
  }
}
```

**3. 任务失败异常时（Failed）**
```json
{
  "jobId": "job-1712461931-abcdef12",
  "status": "failed",
  "error": "Agent execution failed: process timeout."
}
```

---

## 3. 高级用法指南

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

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

外部系统提取了上次的 `result.output` 后，在下次调用的 Body 中：
```json
{
    "task": "基于我附加给你的日志总结，开展新一轮的数据清理",
    "contextFiles": [
        {
            "name": "logs-from-yesterday.txt",
            "content": "....提取的昨日任务输出大段文本...."
        },
        {
            "name": "data.csv",
            "content": "id,name\n1,apple"
        }
    ]
}
```
系统底座会自动将这 2 个对象落地成文件，以文本阅读的视角送入 Agent 的大脑供其深度理解（支持上万字）。通过这种 “外部系统充当记忆保管员 + API 动态投喂上下文文件” 的组合拳，就可以把这些 Agent 变成可控、随时插拔的智能化函数库！