# KnowHub 远程子 Agent 调用接口

> 基地址：环境变量 `KNOWHUB_API`（默认 `http://localhost:9999`）

## 统一入口

**POST /api/agent**

所有远程子 Agent 共用这一个入口，通过 `agent_type` 区分。

### 请求体

```json
{
  "agent_type": "remote_librarian",   // 必填，见下方两个可选值
  "task": "任务描述",                   // 必填
  "messages": null,                    // 可选，预置消息 [{role, content}]
  "continue_from": null,               // 可选，传入 sub_trace_id 续跑
  "skills": null                       // 可选，指定 skill 白名单
}
```

### 响应体

```json
{
  "sub_trace_id": "trace-xxx",
  "status": "completed",       // completed | failed
  "summary": "执行结果摘要",
  "stats": {},
  "error": null
}
```

### 超时

默认 600 秒（环境变量 `REMOTE_AGENT_TIMEOUT` 可调）。

---

## 1. Librarian（知识管理）

`agent_type: "remote_librarian"`

用途：向知识库提问、上传/整理知识。

**示例 — 查询知识：**

```json
POST /api/agent
{
  "agent_type": "remote_librarian",
  "task": "查询 ControlNet 在姿态控制方面的使用经验和最佳实践"
}
```

**示例 — 上传知识：**

```json
POST /api/agent
{
  "agent_type": "remote_librarian",
  "task": "{\"task\": \"ControlNet 姿态控制\", \"content\": \"经验内容...\", \"types\": [\"strategy\"]}",
  "skills": ["upload_strategy"]
}
```

---

## 2. Research（深度调研）

`agent_type: "remote_research"`

用途：使用浏览器做深度调研，搜索外部信息并沉淀为知识。

**示例：**

```json
POST /api/agent
{
  "agent_type": "remote_research",
  "task": "调研 2026 年主流 AI 图像生成工具的 ControlNet 支持情况，对比各平台的精度和易用性"
}
```

**示例 — 续跑（上次中断的调研继续执行）：**

```json
POST /api/agent
{
  "agent_type": "remote_research",
  "task": "继续上次的调研",
  "continue_from": "trace-xxx-yyy"
}
```