---
name: agent
description: 调用 Agent 执行任务 —— 能从知识库获取内容制作经验、擅长使用浏览器做深度调研。
---

# Agent 调用

统一入口调用远端（KnowHub 服务器）或本地 Agent。底层走 `cyber-agent` SDK 的 `invoke_agent()`。

## 前置

需要 `cyber-agent` 包可 import。若未安装，在该仓库根目录执行：

```bash
pip install -e .
```

## 用法

```bash
python <this_skill_dir>/invoke.py \
    --agent_type=<type> \
    --task="<任务描述>" \
    [--skills=skill1,skill2] \
    [--continue_from=<sub_trace_id>] \
    [--project_root=<本地项目目录>]
```

## 远端 Agent（`remote_` 前缀）

**`remote_librarian`** — 知识库查询与上传：
- `skills=ask_strategy`（默认）：查询整合，返回带引用的回答
- `skills=upload_strategy`：上传（`task` 为 JSON 字符串 `{knowledge:[...], tools:[...], resources:[...]}`）

**`remote_research`** — 深度调研：自动全网搜集 + 总结，成果自动入库。

## 本地 Agent

`agent_type` 无 `remote_` 前缀。**默认使用 skill 目录自带的共享 config**，无需每个项目单独建 `config.py`。

- **默认行为**：不传 `--project_root` → 用 skill 目录的 `config.py`，trace 落在调用方 CWD 的 `.cache/trace/`（自动创建）
- **项目覆盖**：如果项目需要自己的 `RUN_CONFIG` / `presets.json` / `tools/`，传 `--project_root=<项目目录>`，该目录需满足：
  - `config.py` 定义 `RUN_CONFIG`（必需）
  - `presets.json` 定义 preset（可选）
  - `tools/__init__.py` 注册自定义工具（可选）

## 续跑

首次调用返回的 `sub_trace_id` 作为下次的 `--continue_from`，同一 Agent 累积上下文。

## 返回值

stdout 输出 JSON，成功退出码 0、失败 1：

```json
{
  "mode": "remote" | "local",
  "agent_type": "...",
  "sub_trace_id": "...",
  "status": "completed" | "failed",
  "summary": "Agent 最终产出的 message 文本（结构化信息由 prompt 约定写在这里）",
  "stats": {"total_messages": N, "total_tokens": N, "total_cost": 0.xxx},
  "error": null
}
```

## 注意

- 远端 `skills` 由服务器白名单过滤，非法项静默丢弃
- 远端 Agent 无法访问调用方本地文件系统——大数据先通过 knowhub / toolhub 上传再传 ID
- `summary` 是纯文本；需要结构化字段（引用来源、ID 等）时由 Agent prompt 约定格式，调用方自己 parse