Open Agent Search

Open Agent Search

为 AI Agent 和应用提供一个可自托管的搜索与内容层。

什么是 OAS？ · Agent 设置 · 功能 · 架构 · API 接口 · 参与贡献

与 Agent 一起设置

将此提示词复制到你的编码 Agent 中：

Set up Open Agent Search for this project using
https://github.com/Jayanth-MKV/open-agent-search. Read its README and
skills/open-agent-search-setup/SKILL.md. Reuse uv if installed, otherwise
install it using the official uv instructions for my OS. Configure the
local stdio MCP server with the pinned package and managed Python version
from the repository's MCP manifest. Merge the server into this agent's
configuration without replacing existing servers. Install the
open-agent-search-setup and open-agent-search skills for this agent in
project scope. Verify the MCP connection and available tools, then try
one web search. Tell me if a client restart is needed. No API key is required.

安装命令

安装 Node.js 22+ 和 uv 后：

npx --yes [email protected] --version
npx --yes [email protected] mcp
# Or start the HTTP API:
npx --yes [email protected] serve

npm 启动器使用固定版本的 Python 核心。它要求 PATH 中包含 uv；uv 会管理 Python 3.12 和依赖项。

安装 uv 后，在隔离环境中运行 MCP 服务：

uvx --python 3.12 --from open-agent-search==1.0.5 oas-mcp

如果缺少 Python 3.12，uv 可以下载它。首次运行时会下载依赖项；完成配置后，客户端会启动并停止此 stdio 进程。

如需持久化安装 PyPI 包并运行 HTTP 服务：

uv tool install --python 3.12 open-agent-search==1.0.5
open-agent-search

HTTP 服务会在所有网络接口的 8000 端口上监听。对于只需要本地工具的 Agent，请使用 stdio。

在当前项目中为 Codex 安装两个技能：

npx --yes skills add Jayanth-MKV/open-agent-search --skill open-agent-search-setup open-agent-search --agent codex --copy --yes

将 codex 替换为 claude-code、cursor、opencode 或其他受支持的 Agent。仅在需要跨项目安装时添加 --global。插件和手动设置。使用上文的 npm 或 PyPI 方式均可；两者都会启动相同的 Python 实现。

在 Claude Code 2.1.275+ 中，可一步安装两个技能和 MCP 配置：

/plugin install open-agent-search --marketplace Jayanth-MKV/open-agent-search --scope project

什么是 Open Agent Search？

Open Agent Search (OAS) 是面向 AI Agent 和应用的独立检索层。它为本地和已部署的集成提供统一一致的搜索与内容接口。

OAS 通过统一一致的工具接口，取代针对每种搜索垂直领域的独立适配器。你可以在本地运行它，为单个编码 Agent 提供服务；也可以部署 HTTP 服务，为共享的 Agent 和应用工作负载提供服务。

搜索来源、传输方式和客户端集成可以不断演进，而无需改变项目的核心目标：为 Agent 和应用提供可靠且可控的检索边界。

连接 MCP 或 HTTP

将搜索添加到 Claude Code

claude mcp add oas -- uvx --python 3.12 --from open-agent-search==1.0.5 oas-mcp

重启 Claude Code，然后让它搜索网页、新闻、图片、视频或图书。同一条 uvx 命令也适用于 Cursor、VS Code、Windsurf、OpenClaw 和其他 MCP 客户端。

{
  "mcpServers": {
    "open-agent-search": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "open-agent-search==1.0.5", "oas-mcp"]
    }
  }
}

uv tool install --python 3.12 open-agent-search==1.0.5
open-agent-search

执行首次搜索：

curl "http://localhost:8000/api/search/text?q=python+programming&max_results=5"

服务会在 http://localhost:8000 提供 REST 端点，在 /docs 提供交互式 API 文档，并在 /ai/mcp 提供可流式传输的 HTTP MCP。

功能

• 一个搜索层，多种传输方式。 在本地使用 stdio MCP，或通过 HTTP 提供 REST 和 MCP 服务。
• 无需提供商 API 密钥。 搜索由 ddgs 库提供支持。
• 可自托管。 可在本地运行、使用 Docker 运行，或将 HTTP 服务部署到 Vercel。
• 与框架无关。 协议接口适用于各大 MCP 客户端和 Agent 技术栈。
• 面向生产环境的默认配置。 内置类型化 FastAPI 路由、速率限制、运行状况检查、测试和部署指南。

架构

本地 MCP 命令和 HTTP 服务共用相同的搜索与内容功能。请选择符合使用该服务的 Agent 或应用运行位置的连接方式。

两种部署方式

搜索功能

参数和响应格式请参阅 API 参考和 MCP 工具参考。

隐私模型

OAS 无需 OAS 账户或搜索提供商 API 密钥，并且可以运行在你控制的基础设施上。搜索查询仍需通过 DDGS 发送给上游搜索提供商，因此本项目不应被视为匿名网络。处理敏感工作负载时，请检查部署日志、网络策略和上游提供商的条款。

安装和部署

从源代码安装

git clone https://github.com/jayanth-mkv/open-agent-search.git
cd open-agent-search
uv sync
uv run open-agent-search

Docker

docker compose up -d

部署详情：Docker · Vercel

文档

• 安装
• 快速入门
• MCP 集成
• API 端点
• 贡献指南

注册表和 Agent 发现

• 软件包：npm 和 PyPI。
• 本地 MCP 套件：Smithery。它在你的机器上运行，需要 Node.js 22+ 和 uv。
• MCP 注册表命名空间：io.github.jayanth-mkv/open-agent-search。在两个软件包均可用后，发布工作流会发布 server.json。查看注册表记录。
• Agent 技能：Open Agent Search 和 setup 已发布到 ClawHub。你也可以使用上面的命令从 GitHub 安装。 skills.sh 目录通过实际安装来发现技能；仅有仓库并不保证会被收录。
• Glama：glama.json 声明了 GitHub 维护者。提交到目录并验证所有权需要单独登录 Glama。

npm 安装路径需要 Node.js 22+ 和 uv。PyPI 安装路径使用 uv 管理 Python 3.12。此项目提供本地服务和部署代码；不提供共享的托管搜索端点。

本地 MCPB 套件通过 python scripts/build_mcpb.py 构建。它包含已固定版本的 npm 启动器，并要求 PATH 中有 Node.js 22+ 和 uv。首次启动时会下载 Python 核心组件及依赖项。套件中不包含凭据。

根据 ClawHub 的要求，它分发的技能副本采用 MIT-0 许可。本仓库及其软件包仍采用 MIT 许可。配置 CLAWHUB_TOKEN 和仓库变量 PUBLISH_CLAWHUB=true 后，GitHub Actions 会在向 main 推送时预览技能变更，并在发布版本时发布技能。该工作流会检查已通过身份验证的 ClawHub 所有者是否与源仓库所有者一致。

开发

uv sync --group dev
uv run pytest
uv run ruff check .

Open Agent Search 目前仍处于 Beta 阶段。欢迎提交 Bug 报告和针对性拉取请求；请参阅 CONTRIBUTING.md。

许可证

MIT

由 Xplormity Collective 维护。