跳转至

如何使用 Hydra 自定义智能体配置

本指南向你展示如何使用 Hydra（一个强大的配置组合框架）来自定义智能体配置。

配置示例

所有示例配置文件可在 docs/configs/ 处获得：

1. agent_simple.yaml - 完整配置

一个完整智能体配置，其中所有字段都明确定义。此示例显示：

  • 智能体类型和基本设置（type、max_turns）
  • 使用环境变量插值的模型配置，使用 ${oc.env:VAR_NAME}
  • 智能体配置文件（名称和说明）
  • 上下文管理器和环境设置
  • 工具包配置（搜索工具包示例）

将此作为参考来了解所有可用配置选项。

2. agent_with_hydra.yaml - Hydra 组合

使用 Hydra 组成功能的简化版本。关键概念：

defaults 列表：加载和组合预定义配置 

defaults:
  - /model/base@model                  # 从 configs/model/base.yaml 加载
  - /tools/search@toolkits.search      # 从 configs/tools/search.yaml 加载
  - _self_

覆盖加载的配置：加载后自定义参数 

model:
  model_settings:
    temperature: 0                     # 覆盖默认温度
toolkits:
  search:
    search_engine: jina                # 覆盖默认搜索引擎

这种方法减少了冗余，使配置更易于维护。

3. toolkit_builtin.yaml - 内置工具包

内置工具包的配置（在 utu/tools/ 中实现）。示例显示：

  • 工具包模式：builtin | mcp | customized
  • 工具激活：指定要启用的工具或使用 null 启用所有工具
  • 工具包特定配置（例如，搜索工具包的 search_engine、crawl_engine）
  • 需要它的工具的可选 LLM 配置

4. toolkit_mcp.yaml - MCP 工具包

模型上下文协议（MCP）工具包的配置。示例显示：

  • MCP 传输类型：stdio | sse | streamable_http
  • 连接参数（URL、标头、超时）
  • 用于密钥的环境变量插值，如 ${oc.env:GITHUB_TOKEN}

请参见 configs/tools/mcp/ 了解更多信息 MCP 示例。

快速开始

  1. 复制示例：从 agent_with_hydra.yaml 开始作为模板
  2. 修改智能体配置文件：更新 agent.name 和 agent.instructions
  3. 选择工具包：更新 defaults 列表以包含你想要的工具包
  4. 覆盖默认值：根据需要自定义特定参数
  5. 保存到 configs/agents/：创建你自己的配置文件（例如，configs/agents/my_agent.yaml）

加载你的配置

# 按名称加载配置（不带 .yaml 扩展名）
python scripts/cli_chat.py --config my_agent

# 或以编程方式
from utu.config import ConfigLoader
config = ConfigLoader.load_agent_config("my_agent")

参考