第8章 MCP 与工具配置指南

MCP 与工具

工具赋予智能体对话之外的能力。它们在智能体 YAML 配置的 `tools` 字段下声明，每个工具通过你自定义的名称进行标识。

Omnigent 支持 MCP 服务器、内置工具、Python 函数、子智能体以及继承的工具。

MCP 服务器

MCP（Model Context Protocol）服务器通过标准协议暴露工具。

在共享会话中，上传的智能体所声明的服务器也可以在 Web UI 的“智能体信息”面板中进行管理——但仅限会话所有者操作。编辑者只能以只读方式查看列表。参见：仅所有者可修改智能体。

自定义服务器

对于内置集合之外的 MCP 服务器，请在智能体 YAML 中声明。传输方式根据配置自动推断：本地 stdio 服务器使用 `command`，远程 HTTP/SSE 服务器使用 `url`。

本地命令 (stdio)：

```yaml tools: my-server: type: mcp command: node args: [dist/server.js] env: API_KEY: ${MY_API_KEY} # 环境变量在运行时展开 ```

远程 URL (HTTP/SSE)：

```yaml tools: docs-api: type: mcp url: https://example.com/mcp headers: Authorization: "Bearer ${API_TOKEN}" # 环境变量在运行时展开 ```

可选的 `tools` 列表用于过滤暴露给智能体的 MCP 工具。它在两种传输方式下机制相同——列出允许的工具名称，只有这些工具才会呈现给模型：

```yaml tools: github: type: mcp command: npx args: [-y, server-github] tools: [search_issues, get_pull_request] # 仅暴露这两个工具 ```

省略 `tools` 则暴露服务器提供的所有工具。

边车 MCP 文件

除了直接在 `config.yaml` 的 `tools` 下内联声明 MCP 服务器，还可以将其保留在智能体 `tools/mcp/` 目录下的独立文件中。Omnigent 在加载时会发现所有 `tools/mcp/*.yaml` 文件。边车文件需显式指定服务器名称及其传输方式（`transport: stdio` 配合 `command/args`，或 `transport: http` 配合 `url`），并支持内联格式相同的可选 `tools` 白名单：

```yaml # tools/mcp/github.yaml name: github transport: stdio command: npx args: [-y, server-github] tools: [search_issues, get_pull_request] # 仅暴露这两个工具 ```

```yaml # tools/mcp/docs.yaml name: docs transport: http url: https://mcp.example.com/sse tools: [search_docs] ```

无论服务器是内联声明还是放在边车文件中，工具白名单的执行逻辑一致：仅列出的工具名称会通告给模型，省略 `tools` 则暴露服务器提供的所有工具；若 `tools` 的值不是列表，加载时将报错并指明文件名。

认证

如上文示例所示，自定义 MCP 服务器通过以下方式接受凭证：

* `env`：传递给 stdio 服务器进程的环境变量（例如 `API_KEY: ${MY_API_KEY}`） * `headers`：远程服务器的 HTTP 头，支持 `${...}` 环境变量展开（例如 `Authorization: "Bearer ${API_TOKEN}"`） * `auth`：配合 `type: databricks`，可从 `~/.databrickscfg` 中的配置文件解析 OAuth 令牌。databricks 是唯一支持的认证类型；在此类型中，`profile` 为必填项。其他服务器不使用 `auth:`，而是通过上述 `env` 或 `headers` 进行认证：

```yaml tools: internal-api: type: mcp url: https://my-workspace.databricks.com/mcp auth: type: databricks profile: my-profile ```

内置工具

Omnigent 附带一组内置工具，可在 `tools.builtins` 下按名称启用，无需编写代码。

web_search

这是一个统一的网络搜索工具，其后端由智能体规范决定：

* OpenAI 模型——直通 OpenAI 原生的 `web_search_preview`（服务端，使用 LLM API 密钥）。无需设置 `search_provider`。 * 其他模型（Anthropic、Llama、Databricks 托管等）——设置 `search_provider` 以显式指定搜索引擎。无默认值，也不依赖环境变量回退，因此运行的引擎始终明确；若未设置 `search_provider`，工具将返回错误并列出可选引擎。

支持的后端：

| search_provider | API 密钥 | 说明 | | :--- | :--- | :--- | | duckduckgo | 无需密钥 | 不需要 api_key | | keenable | 可选 | 默认为免密钥；提供 api_key 可解除速率限制 | | google | 必需 | 还需要 engine_id | | perplexity | 必需 | | | nimble | 必需 | | | tavily | 必需 | |

免密钥后端开箱即用；需密钥后端需要凭证以获得更稳定、更高频的服务。

```yaml tools: builtins: - name: web_search search_provider: duckduckgo # 例如，一个免密钥后端 # api_key: ${PERPLEXITY_API_KEY} # 需密钥后端必填 ```

Keenable

Keenable 默认免密钥。若规范中无 `api_key`，它调用免密钥公共端点并开箱即用；提供 `api_key` 则切换至认证端点并解除速率限制。设置可选的 `max_results` 以控制返回结果数量（1–20，默认 5）：

```yaml tools: builtins: - name: web_search search_provider: keenable # api_key 是可选的 — 省略以使用免密钥免费层级： # api_key: ${KEENABLE_API_KEY} # max_results: 5 # 1-20 (默认 5) ```

Hindsight 长期记忆

三个内置工具赋予智能体跨越运行和会话的记忆，由 Hindsight（一个开源智能体记忆系统）提供支持。与会话历史在会话间丢失不同，智能体保留的任何内容在所有后续运行中均可用。

| 工具 | 功能 | | :--- | :--- | | hindsight_retain | 将持久的事实、偏好或决策存入记忆。接受内容字符串。 | | hindsight_recall | 在回答前搜索记忆中的相关事实。接受查询字符串。 | | hindsight_reflect | 从记忆中综合推理摘要，而非返回原始事实。接受查询字符串。 |

Hindsight 客户端 SDK 是可选依赖。安装 memory 附加包并提供 API 密钥：

```bash pip install 'omnigent[memory]' export HINDSIGHT_API_KEY=hsk_... # https://ui.hindsight.vectorize.io ```

在 `tools.builtins` 下按名称启用工具：

```yaml tools: builtins: - name: hindsight_recall api_key: ${HINDSIGHT_API_KEY} - name: hindsight_retain api_key: ${HINDSIGHT_API_KEY} - name: hindsight_reflect api_key: ${HINDSIGHT_API_KEY} ```

配置键

`api_key` 是必需的；其他键均为可选：

| 键 | 用途 | | :--- | :--- | | api_key | Hindsight API 密钥（通常为 ${HINDSIGHT_API_KEY}）。 | | api_url | API 基础 URL。默认为 https://api.hindsight.vectorize.io。 | | bank_id | 读写的记忆库。默认为智能体 ID，其次为对话 ID。 | | budget | 召回/反思的预算级别 — low, mid (默认), 或 high。 | | max_tokens | 召回结果的最大令牌数（默认 4096）。 | | tags | 应用于 hindsight_retain 的逗号分隔标签。 | | recall_tags | 用于过滤 hindsight_recall 的逗号分隔标签。 | | recall_tags_match | recall_tags 的匹配方式 — any (默认), all, any_strict, 或 all_strict。 |

记忆按解析后的 bank 隔离。若无 `bank_id`，bank 默认为智能体 ID，因此每个智能体开箱即拥有独立的记忆库。固定 `bank_id` 可在多次运行（或多个智能体）间共享一个人类可读的 bank：

```yaml tools: builtins: - name: hindsight_retain api_key: ${HINDSIGHT_API_KEY} bank_id: remy # 稳定且易于在 Hindsight 中检查 ```

由于这些工具仅在模型实际调用时才持久化和召回，请在提示词中指导智能体在回答前执行召回，并在学习到持久事实时执行保留——参见 remy 示例智能体的提示词实例。

Nimble 网络研究与提取

两个内置工具通过 Nimble 访问实时网络。

`nimble_research` 将研究任务交给 Nimble 网络搜索智能体，返回带有每项声明置信度信号的引用答案。当你有 Nimble 提取模板针对页面运行时，使用 `nimble_extract`；它返回解析后的结构化 JSON 结果。

`nimble_research` 需要可选的 nimble 附加包：

```bash pip install 'omnigent[nimble]' ```

在智能体 config.yaml 的 `tools.builtins` 下启用它们：

```yaml tools: builtins: - name: nimble_research api_key: ${NIMBLE_API_KEY} - name: nimble_extract api_key: ${NIMBLE_API_KEY} template: my_template_name # 你账户中的提取模板之一 ```

Nimble 也是 web_search 提供者，用于不需要完整研究运行的快速查询。完整的配置参考（轮询、智能体实例、提取模板及获取 API 密钥的位置），参见 Nimble 的 Omnigent 连接器文档。

Python 函数工具

将任何 Python 可调用对象暴露为工具。该函数通过其完全限定导入路径引用：

```yaml tools: summarize_file: type: function description: Summarize a local text file. callable: my_package.tools.summarize_file parameters: type: object properties: path: type: string required: [path] ```

`parameters` 下的 JSON Schema 是可选的。若省略，Omnigent 将根据函数的类型注解和签名自动生成 schema。

子智能体工具

将智能体声明为工具，以便主管智能体可以委派任务给它们。你可以内联定义子智能体，也可以将其保留在自己的目录中并按名称引用。

内联定义

直接在 `tools` 块中定义子智能体的完整规范：

```yaml tools: reviewer: type: agent description: Review proposed code changes. prompt: | You are a careful code reviewer. Focus on correctness, tests, security, and maintainability. executor: harness: claude-sdk model: claude-sonnet-4-6 os_env: inherit pass_history: true max_sessions: 2 ```

外部目录

对于复杂、跨父级共享或独立维护的子智能体，请为其在父级 `agents/` 文件夹下创建独立目录，并在 `tools.agents` 下按名称列出。Omnigent 在加载时会发现所有 `agents//config.yaml`：

```yaml # 父级 config.yaml tools: agents: - reviewer ```

```yaml # agents/reviewer/config.yaml — 标准的智能体配置 spec_version: 1 name: reviewer description: Review proposed code changes. prompt: | You are a careful code reviewer. Focus on correctness, tests, security, and maintainability. executor: type: omnigent config: harness: claude-sdk model: claude-sonnet-4-6 ```

`tools.agents` 下的条目仅是与 `agents/` 子目录匹配的字符串名称。每个引用的文件都是完整的智能体配置，可定义自己的工具、技能、harness 和策略。

子智能体（内联或外部）可以拥有自己的 harness、模型、工具和策略。在内联子智能体中，`pass_history` 标志控制是否转发父级的对话历史，`max_sessions` 限制并发调用次数。

工具继承

使用 `inherit` 将父级的某个工具传递给子智能体：

```yaml tools: researcher: type: agent prompt: Research and summarize. tools: word_count: inherit # 从父级获取 word_count ```

子智能体接收与父级相同的工具定义，无需重复。

使用 `spec: self` 使子智能体克隆整个父级规范。它将拥有与父级智能体相同的工具、提示词和配置。

Hindsight 集成

Omnigent 附带 Hindsight 集成，赋予智能体长期记忆。有三个工具可用：

* `hindsight_retain` — 跨运行持久化事实。 * `hindsight_recall` — 在回答前检索相关记忆。 * `hindsight_reflect` — 对 bank 中存储的所有内容进行推理。

这些工具包含在可选附加包中。安装它并设置 Hindsight API 密钥后再声明：

```bash pip install 'omnigent[hindsight]' export HINDSIGHT_API_KEY=hsk_... # https://ui.hindsight.vectorize.io ```

在 `builtins` 下按保留名称声明它们，传入 API 密钥和可选的 `bank_id`（省略 `bank_id` 则记忆库默认为智能体 ID）：

```yaml tools: builtins: - name: hindsight_recall api_key: ${HINDSIGHT_API_KEY} bank_id: my-agent - name: hindsight_retain api_key: ${HINDSIGHT_API_KEY} bank_id: my-agent - name: hindsight_reflect api_key: ${HINDSIGHT_API_KEY} bank_id: my-agent ```

混合工具类型

单个智能体可以混合使用所有工具类型。`tools` 块是一个从名称到定义扁平映射：

```yaml tools: github: type: mcp command: uv args: [run, python, -m, my_package.github_mcp]

summarize_file: type: function callable: my_package.tools.summarize_file

reviewer: type: agent config: agents/reviewer.yaml ```