使用说明

🤖 OmniBot

MCP-native AI Agent Framework — plug any MCP server, ship an agent in minutes.

Quick Start • Architecture • Features • Configuration • Comparison • Contributing

什么是OmniBot？

OmniBot是一个 轻量级AI代理框架 围绕模型上下文协议（MCP）。您可以在JSON配置中声明MCP服务器，而不是硬编码工具集成——OmniBot会自动发现它们的工具，并让您的代理在零代码更改的情况下使用它们。

将MCP视为 用于AI工具的USB-COmniBot是一款支持任何USB-C设备的笔记本电脑。

建筑

                          ┌──────────────────────────────────────────────┐
                          │                  OmniBot                     │
                          │                                              │
┌──────────┐   REST/WS    │  ┌────────────┐    ┌──────────────────────┐  │
│  Web UI  │─────────────▶│  │  FastAPI    │───▶│   Agent Engine       │  │
│  (Chat   │◀─────────────│  │  Gateway    │◀───│                      │  │
│  Widget) │              │  └────────────┘    │  ┌────────────────┐  │  │
└──────────┘              │                    │  │  ReAct Loop    │  │  │
                          │                    │  │  ┌──────────┐  │  │  │
┌──────────┐              │                    │  │  │ Reason   │  │  │  │
│  cURL /  │──────────────│                    │  │  │    ↓     │  │  │  │
│  API     │              │                    │  │  │ Act      │  │  │  │
│  Client  │              │                    │  │  │    ↓     │  │  │  │
└──────────┘              │                    │  │  │ Observe  │  │  │  │
                          │                    │  │  └──────────┘  │  │  │
                          │                    │  └────────────────┘  │  │
                          │                    └──────────┬───────────┘  │
                          │                               │              │
                          │              ┌────────────────┼──────────┐  │
                          │              │   Unified Tool Registry    │  │
                          │              └──┬─────────┬──────────┬───┘  │
                          │                 │         │          │      │
                          └─────────────────┼─────────┼──────────┼──────┘
                                            │         │          │
                          ┌─────────────────┼─────────┼──────────┼──────┐
                          │   MCP Servers   │         │          │      │
                          │                 ▼         ▼          ▼      │
                          │  ┌───────────┐ ┌────────┐ ┌──────────────┐ │
                          │  │filesystem │ │ fetch  │ │   github     │ │
                          │  └───────────┘ └────────┘ └──────────────┘ │
                          │  ┌───────────┐ ┌────────┐ ┌──────────────┐ │
                          │  │ postgres  │ │sqlite  │ │  playwright  │ │
                          │  └───────────┘ └────────┘ └──────────────┘ │
                          └─────────────────────────────────────────────┘

                          ┌─────────────────────────────────────────────┐
                          │   LLM Providers                             │
                          │   ┌──────────┐  ┌───────────┐  ┌────────┐  │
                          │   │  OpenAI  │  │ Anthropic │  │ More.. │  │
                          │   │ GPT-4o   │  │  Claude   │  │        │  │
                          │   └──────────┘  └───────────┘  └────────┘  │
                          └─────────────────────────────────────────────┘

核心功能

🔌 MCP客户端（一级）

OmniBot以MCP为母语。在中声明任何与MCP兼容的服务器 omnibot.json 它可以立即作为代理工具使用——无需代码，无需适配器，无需胶水。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    }
  }
}

🧠 重新激活代理循环

A内置 理由→ Act → 观察 循环驱动代理。LLM决定调用哪些工具，解释结果，并不断迭代，直到得到完整的答案——最多 MAX_AGENT_ITERATIONS 回合。

🗂️ 统一工具注册表

MCP工具和原生Python工具并排存在一个注册表中。代理不在乎工具来自哪里，它只是选择了正确的工具。

from app.core.engine import engine

async def get_weather(city: str) -> str:
    return f"Weather in {city}: 22°C, sunny"

engine.registry.register_builtin(
    name="get_weather",
    description="Get current weather for a city",
    input_schema={
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
    handler=get_weather,
)

🤖 多LLM支持

使用单个env变量在LLM提供程序之间切换。目前支持：

提供者	模型	函数调用
OpenAI	GPT-4o、GPT-4o-mini、o1等。	✅
人本主义	克劳德3.5十四行诗、克劳德3作品集等。	✅

📚 RAG（内置代理工具）

RAG不是一个单独的管道——它是代理在需要搜索您的知识库时可以调用的工具。上传文档，代理决定何时查询。

# Upload a document
curl -X POST http://localhost:8000/api/v1/knowledge \
  -F "file=@company-faq.pdf"

# Agent auto-searches when relevant
curl -X POST http://localhost:8000/api/v1/chat \
  -d '{"text": "What is our refund policy?"}'

快速开始

通过3个步骤让OmniBot运行：

步骤1：克隆并安装

git clone https://github.com/coldxiangyu163/omnibot.git
cd omnibot
cp .env.example .env          # Add your API keys
pip install -r requirements.txt

步骤2：配置MCP工具

创建 omnibot.json 在项目根目录中（或从模板复制）：

cp omnibot.example.json omnibot.json

编辑它以声明您想要的MCP服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    }
  }
}

第三步：跑步

# Development
make dev                       # → http://localhost:8000

# Or with Docker
docker compose up -d           # → http://localhost:8000

就是这样。您的代理已经上线，所有已声明的MCP工具都已自动发现并准备就绪。

试试看

# Simple chat
curl -X POST http://localhost:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"text": "List all files in the data directory"}'

# Full agent mode with step-by-step details
curl -X POST http://localhost:8000/api/v1/agent/run \
  -H "Content-Type: application/json" \
  -d '{"message": "Fetch https://news.ycombinator.com and summarize the top 3 stories"}'

# List all available tools (MCP + built-in)
curl http://localhost:8000/api/v1/tools

运作原理

OmniBot使用 ReAct（Reason+Act）代理循环:

User: "What's in my docs folder?"
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Agent Step 1                                        │
│   Think:  "I should list the directory"             │
│   Act:    filesystem.list_directory(path="./docs")  │
│   Result: ["report.pdf", "notes.md", "data.csv"]   │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│ Agent Step 2                                        │
│   Think:  "I have the file list, I can respond"     │
│   Response: "Your docs folder contains 3 files:     │
│              report.pdf, notes.md, and data.csv"    │
└─────────────────────────────────────────────────────┘

代理不断循环（最多 MAX_AGENT_ITERATIONS)直到它有足够的信息给出最终答案。

配置

环境变量

变量	描述	默认值
`LLM_PROVIDER`	LLM后端： `openai` 或 `anthropic`	`openai`
`LLM_MODEL`	型号名称（例如。 `gpt-4o`, `claude-3-5-sonnet-20241022`)	`gpt-4o`
`OPENAI_API_KEY`	OpenAI API密钥	-
`ANTHROPIC_API_KEY`	无烟煤API密钥	-
`MAX_AGENT_ITERATIONS`	每个请求的最大工具调用轮次	`10`
`MCP_CONFIG_PATH`	MCP服务器配置文件的路径	`omnibot.json`

MCP服务器配置(`omnibot.json`)

每个条目下 mcpServers 定义工具提供者：

{
  "mcpServers": {
    "<server-name>": {
      "command": "<executable>",
      "args": ["<arg1>", "<arg2>"],
      "env": {
        "<ENV_VAR>": "<value>"
      }
    }
  }
}

OmniBot通过stdio连接到每台服务器，发现其工具，并在启动时将其注册到统一的工具注册表中。

比较

功能	LangChain	CrewAI	AutoGen	Dify/FastGPT	OmniBot
MCP本地	❌ 需要适配器	❌	❌	❌	✅ 头等舱
添加新工具	编写Python代码	编写Python语言代码	编写Python语言代码	平台用户界面	JSON配置
代理循环	手动链设置	基于角色	基于对话	基本流程	内置ReAct
多LLM	✅	✅	✅	✅	✅
RAG	独立链	插件	插件	内置	内置工具
依赖权重	重型（~50+deps）	中型	中型	全平台	轻量级
学习曲线	陡峭	中等	中等	低（无代码）	低
部署	库（DIY）	库（自制）	库	Docker一键
最适合	复杂管道	多代理团队	多代理聊天	无代码用户	MCP第一代理

OmniBot的最佳选择：你想要一个生产就绪的代理，它可以使用任何MCP工具，只需最少的设置，而无需引入庞大的框架。

项目结构

omnibot/
├── app/
│   ├── main.py                # FastAPI entry point + lifespan
│   ├── config.py              # Settings & env loading
│   ├── core/
│   │   ├── engine.py          # AgentEngine — the orchestrator
│   │   ├── agent/
│   │   │   └── loop.py        # ReAct agent loop implementation
│   │   ├── mcp/
│   │   │   ├── client.py      # MCP stdio client
│   │   │   └── registry.py    # Unified tool registry (MCP + built-in)
│   │   ├── llm/               # LLM providers (OpenAI, Anthropic)
│   │   └── rag/               # RAG pipeline (vector search tool)
│   ├── api/v1/                # REST API routes
│   ├── channels/              # WebSocket, future: Slack / Telegram
│   └── schemas/               # Pydantic request/response models
├── examples/                  # Quickstart & usage examples
├── static/widget/             # Embeddable web chat widget
├── omnibot.example.json       # MCP config template
├── docker-compose.yml         # One-click Docker deployment
├── Makefile                   # Dev commands
├── requirements.txt           # Python dependencies
└── tests/                     # Test suite

兼容的MCP服务器

任何兼容MCP的服务器都可以开箱即用。热门选择：

服务器	它做什么	安装
`@modelcontextprotocol/server-filesystem`	读/写本地文件	`npx -y @modelcontextprotocol/server-filesystem`
`mcp-server-fetch`	获取并解析网页	`uvx mcp-server-fetch`
`@modelcontextprotocol/server-github`	GitHub API（转发、问题、PR）	`npx -y @modelcontextprotocol/server-github`
`@modelcontextprotocol/server-postgres`	查询PostgreSQL数据库	`npx -y @modelcontextprotocol/server-postgres`
`@playwright/mcp`	浏览器自动化	`npx -y @playwright/mcp`
`mcp-server-sqlite`	SQLite数据库操作	`uvx mcp-server-sqlite`

浏览完整目录 MCP服务器.

路线图

[x] MCP客户端（stdio传输）
[x] 使用工具调用重新激活代理循环
[x] OpenAI+人工智能函数调用
[x] 统一工具注册表（MCP+内置）
[x] RAG作为内置代理工具
[x] REST API+WebSocket
[x] 可嵌入的网络聊天小部件
[]MCP SSE/流式HTTP传输
[]流式响应（SSE）
[]对话记忆（多回合上下文）
[]渠道整合（Slack/Telegram/Lark）
[]代理人之间的委托
[]MCP服务器模式（将OmniBot本身暴露为MCP服务器）

贡献

欢迎投稿！以下是如何开始：

开发设置

git clone https://github.com/coldxiangyu163/omnibot.git
cd omnibot
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
make dev

如何做出贡献

分叉存储库
创建特征分支： git checkout -b feat/my-feature
提交您的更改： git commit -m "feat: add my feature"
推到你的叉子： git push origin feat/my-feature
打开拉取请求反对 main

指南

遵循现有的代码风格和项目结构
尽可能添加新功能的测试
使用约定式提交用于提交消息
让PR保持专注——每个PR都有一个功能或修复
如果您的更改影响公共API，请更新文档

报告问题

发现错误或有功能请求？打开一个问题与：

对问题或建议的清晰描述
复制步骤（针对bug）
预期行为与实际行为

许可证

麻省理工学院 --使用它，修改它，运送它，用它赚钱。

_{Built with ❤️ by coldxiangyu}