agentic_huge_data_base / wiki
页面 Onyx · 5.3 工具集成·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 5.3

5.3 · 工具集成（Tool Integration）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节5.3 状态全文译文 模块接口与服务契约、界面与交互、系统架构、智能体运行时
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Tool Integration 上一章5.2 下一章5.4
源码线索
  • backend/alembic/versions/f3c9e59c3b07_seed_coding_agent_tool.py
  • backend/onyx/db/code_interpreter.py
  • backend/onyx/server/manage/code_interpreter/__init__.py
  • backend/onyx/server/manage/code_interpreter/api.py
  • backend/onyx/server/manage/code_interpreter/models.py
  • backend/onyx/server/query_and_chat/session_loading.py
  • backend/onyx/tools/built_in_tools.py
  • backend/onyx/tools/constants.py
  • backend/onyx/tools/tool_constructor.py
  • backend/onyx/tools/tool_implementations/coding_agent/__init__.py
模块标签
  • 接口与服务契约
  • 界面与交互
  • 系统架构
  • 智能体运行时
  • 测试、发布与运维

章节正文

工具集成

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/5.3-tool-integration

工具集成

相关源文件

本章引用的主要源码文件：

  • backend/alembic/versions/f3c9e59c3b07_seed_coding_agent_tool.py
  • backend/onyx/db/code_interpreter.py
  • backend/onyx/server/manage/code_interpreter/__init__.py
  • backend/onyx/server/manage/code_interpreter/api.py
  • backend/onyx/server/manage/code_interpreter/models.py
  • backend/onyx/server/query_and_chat/session_loading.py
  • backend/onyx/tools/built_in_tools.py
  • backend/onyx/tools/constants.py
  • backend/onyx/tools/tool_constructor.py
  • backend/onyx/tools/tool_implementations/coding_agent/__init__.py
  • backend/onyx/tools/tool_implementations/coding_agent/coding_agent_tool.py
  • backend/onyx/tools/tool_implementations/custom/custom_tool.py
  • backend/onyx/tools/tool_implementations/images/image_generation_tool.py
  • backend/onyx/tools/tool_implementations/mcp/mcp_tool.py
  • backend/onyx/tools/tool_implementations/open_url/firecrawl.py
  • backend/onyx/tools/tool_implementations/open_url/open_url_tool.py
  • backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
  • backend/onyx/tools/tool_implementations/python/python_tool.py
  • backend/onyx/tools/tool_implementations/web_search/utils.py
  • backend/onyx/tools/tool_implementations/web_search/web_search_tool.py
  • backend/tests/external_dependency_unit/tools/test_mcp_passthrough_oauth.py
  • backend/tests/external_dependency_unit/tools/test_oauth_tool_integration.py
  • backend/tests/external_dependency_unit/tools/test_python_tool.py
  • backend/tests/external_dependency_unit/tools/test_python_tool_server_enabled.py
  • backend/tests/integration/common_utils/managers/chat.py
  • backend/tests/integration/common_utils/managers/tool.py
  • backend/tests/integration/common_utils/test_models.py
  • backend/tests/integration/tests/chat/test_chat_deletion.py
  • backend/tests/integration/tests/code_interpreter/conftest.py
  • backend/tests/integration/tests/code_interpreter/test_code_interpreter_api.py
  • backend/tests/integration/tests/migrations/test_tool_seeding.py
  • backend/tests/integration/tests/streaming_endpoints/test_chat_stream.py
  • backend/tests/unit/onyx/tools/custom/test_custom_tools.py
  • backend/tests/unit/onyx/tools/test_mcp_tool_schema.py
  • backend/tests/unit/onyx/tools/test_python_tool_availability.py
  • backend/tests/unit/onyx/tools/tool_implementations/python/__init__.py
  • backend/tests/unit/onyx/tools/tool_implementations/python/test_code_interpreter_client.py
  • web/src/app/app/components/tools/constants.ts
  • web/src/app/app/services/actionUtils.ts

目的与范围

本文档记录了 Onyx 中的工具集成系统，涵盖如何根据角色配置构建工具、如何将工具传递给大语言模型（LLM）进行函数调用，以及在聊天交互过程中如何执行工具。工具使大语言模型（LLM）能够执行搜索文档、浏览网页、运行 Python 代码、读取文件以及管理用户记忆等操作。

有关配置角色可用工具的详细信息，请参阅助手配置。有关工具结果如何整合到提示词中的详细信息，请参阅提示词工程。

可用的内置工具

Onyx 提供了几个核心内置工具，可以在角色上启用。这些工具定义在 BUILT_IN_TOOL_MAP onyx/tools/built_in_tools.py:36-46 中。

工具名称类名用途
run_searchSearchTool在已索引的连接器中进行内部文档搜索，并执行访问控制列表（ACL）强制 onyx/tools/tool_implementations/search/search_tool.py:47
web_searchWebSearchTool查询外部搜索引擎（Google、Bing 等）以获取互联网结果 onyx/tools/tool_implementations/web_search/web_search_tool.py:84
open_urlsOpenURLTool通过 URL 获取并提取网页或已索引文档的内容 onyx/tools/tool_implementations/open_url/open_url_tool.py:29
pythonPythonTool使用代码解释器服务在沙箱环境中执行 Python 代码 onyx/tools/tool_implementations/python/python_tool.py:51
file_readerFileReaderTool当项目/角色附加的文件过大无法放入上下文时，读取这些文件 onyx/tools/tool_implementations/file_reader/file_reader_tool.py:39
memoryMemoryTool跨对话存储和检索关于用户的持久信息 onyx/tools/tool_implementations/memory/memory_tool.py:44
generate_imageImageGenerationTool使用配置的提供者根据文本提示生成图像 onyx/tools/tool_implementations/images/image_generation_tool.py:48

来源： onyx/tools/built_in_tools.py:36-53，onyx/tools/tool_constructor.py:33-48

工具构建管线

概述

工具是根据角色配置、用户权限和聊天上下文，为每条聊天消息动态构建的。构建过程发生在 construct_tools 中，该函数在进入大语言模型（LLM）循环之前被调用。

自然语言空间到代码实体空间：工具构建

Onyx · 概述 · 图 1
Onyx · 概述 · 图 1
构建入口点

主要的构建过程发生在 construct_tools onyx/tools/tool_constructor.py:114-125 中。该函数通过检查角色附加的工具和用户可用的凭证，来处理 Tool 子类的实例化。例如，它会检查 user.oauth_accounts 来为需要用户级认证的工具提供令牌 onyx/tools/tool_constructor.py:173-176。

该函数返回一个字典，将工具数据库 ID 映射到 Tool 实例列表 onyx/tools/tool_constructor.py:161。

来源： onyx/tools/tool_constructor.py:114-176

工具配置对象

特定的配置对象控制工具构建行为和过滤范围：

SearchToolConfig

控制内部文档搜索配置 onyx/tools/tool_constructor.py:55-67：

字段类型用途
user_selected_filtersBaseFilters | None用户应用的来源类型和时间范围过滤器
project_id_filterint | None将搜索限制在 Vespa 中的项目文件
persona_id_filterint | None将搜索限制在 Vespa 中的角色文件
bypass_aclbool是否绕过访问控制（管理员功能）
slack_contextSlackContext | None用于联合搜索的 Slack 特定上下文
FileReaderToolConfig

用于指定 FileReaderTool 应有权访问哪些文件 onyx/tools/tool_constructor.py:69-74：

字段类型用途
user_file_idslist[UUID]来自 user_file 表的 ID（角色附加）
chat_file_idslist[UUID]来自 file_record 表的 ID（聊天附加）

来源： onyx/tools/tool_constructor.py:55-82

工具执行详情

PythonTool（代码解释器）

PythonTool 使用 CodeInterpreterClient 与外部沙箱服务进行通信 onyx/tools/tool_implementations/python/python_tool.py:51-57。

  • 可用性：通过 CODE_INTERPRETER_BASE_URL 和服务器健康检查来验证 onyx/tools/tool_implementations/python/python_tool.py:93-101。
  • 文件处理：它可以通过将文件上传到解释器并缓存 ci_file_id 来准备执行文件，从而避免在会话内重复上传 onyx/tools/tool_implementations/python/python_tool.py:168-182。
  • 流式传输：它会向前端发送 PythonToolStart 和 PythonToolDelta 数据包，以实时显示代码和输出 onyx/tools/tool_implementations/python/python_tool.py:157-163。
WebSearchTool

WebSearchTool 抽象了各种互联网搜索提供者（Google、Bing、Serper 等）onyx/tools/tool_implementations/web_search/web_search_tool.py:83-114。

  • 消毒：在发送给提供者之前，会对大语言模型（LLM）生成的查询进行消毒，以移除控制字符并规范化空白字符 onyx/tools/tool_implementations/web_search/web_search_tool.py:47-56。
  • 并行性：大语言模型（LLM）生成的多个搜索查询会使用线程池并行执行 onyx/tools/tool_implementations/web_search/web_search_tool.py:39。
OpenURLTool

OpenURLTool 允许大语言模型（LLM）“浏览”特定链接 onyx/tools/tool_implementations/open_url/open_url_tool.py:29。

  • 混合检索：它首先尝试在现有的 Onyx 索引中查找 URL onyx/tools/tool_implementations/open_url/open_url_tool.py:181-183。如果未找到，则使用 WebContentProvider（如 Firecrawl 或基本抓取器）获取实时页面 onyx/tools/tool_implementations/open_url/open_url_tool.py:132-133。
  • 规范化：URL 会被规范化（移除片段/查询参数），以提高缓存和索引命中率 onyx/tools/tool_implementations/open_url/open_url_tool.py:150-167。
ImageGenerationTool

当用户明确请求图像时使用 onyx/tools/tool_implementations/images/image_generation_tool.py:48-51。

  • 心跳：由于图像生成可能较慢，该工具每 5 秒发送一次 ImageGenerationToolHeartbeat 数据包，以防止客户端超时 onyx/tools/tool_implementations/images/image_generation_tool.py:41-42。
  • 持久化：生成的图像会保存到 Onyx 的 FileStore 中，并作为包含前端可访问 URL 的 GeneratedImage 对象返回 onyx/tools/tool_implementations/images/image_generation_tool.py:231-253。

来源： onyx/tools/tool_implementations/python/python_tool.py:51-182，onyx/tools/tool_implementations/web_search/web_search_tool.py:47-114，onyx/tools/tool_implementations/open_url/open_url_tool.py:132-183，onyx/tools/tool_implementations/images/image_generation_tool.py:41-253

MCP（模型上下文协议）集成

Onyx 支持模型上下文协议，允许其连接到外部 MCP 服务器以动态扩展其工具集 onyx/tools/tool_implementations/mcp/mcp_tool.py:52。

自然语言空间到代码实体空间：MCP 流程

Onyx · MCP（模型上下文协议）集成 · 图 2
Onyx · MCP（模型上下文协议）集成 · 图 2
  • 认证：支持 NONE、API_KEY 和 PT_OAUTH（直通 OAuth），其中用户的登录令牌会传递给 MCP 服务器 onyx/tools/tool_implementations/mcp/mcp_tool.py:167-172。
  • 优先级：来自 MCPConnectionConfig（数据库）的请求头优先于来自 API 请求的附加请求头 onyx/tools/tool_implementations/mcp/mcp_tool.py:132-164。
  • 安全性：拒绝列表包含关键请求头（如 Host），以防止请求头注入攻击 onyx/tools/tool_implementations/mcp/mcp_tool.py:23-28。

来源： onyx/tools/tool_implementations/mcp/mcp_tool.py:23-182，onyx/tools/tool_constructor.py:16-18