项目简介

Xaibo是一个模块化的人工智能Agent框架，旨在通过清晰的协议接口构建灵活的AI系统。它提供Agent的定义、模块组装、依赖注入、事件追踪等核心功能。通过内置的API适配器，Xaibo不仅可以暴露Agent的能力供OpenAI兼容客户端使用，还能将其Agent作为标准的Model Context Protocol (MCP) 服务器暴露给兼容的MCP客户端。

主要功能点

模块化架构: 基于协议的模块化设计，Agent由可互换的组件（如不同的LLM、工具、记忆模块）构成，易于定制和扩展。
依赖注入: 模块显式声明所需协议，框架负责解析和注入依赖，提高组件的可测试性和管理性。
透明事件追踪: 内置事件系统捕获Agent内部组件的每一次交互，提供详细的运行时可见性和调试数据。
MCP服务器能力: 通过内置的'McpApiAdapter'，可以将Xaibo中构建的Agent作为标准的MCP工具暴露，使Xaibo成为一个可供MCP客户端连接和调用的MCP服务器。
多种适配器: 除了MCP，还提供与OpenAI Chat Completions API和OpenAI Responses API兼容的HTTP适配器。

安装步骤

确保您已安装Python 3.10或更高版本，以及'pip'或'uv'包管理器。
安装'uv' (如果使用pip可跳过):
```
pip install uv
```
使用'uvx'初始化一个新的Xaibo项目（这将创建一个推荐的项目结构和示例Agent）：
```
uvx xaibo init my_project
```
进入新创建的项目目录：
```
cd my_project
```

安装核心Xaibo库及必要的依赖组。要启用MCP服务器功能，至少需要'webserver'组。如果您的Agent还需要特定的LLM或工具，也需要安装相应的组（例如，使用OpenAI LLM）：

# 安装核心、webserver和openai依赖
uv pip install xaibo[webserver,openai]
# 或者使用pip
# pip install xaibo[webserver,openai]

服务器配置

当Xaibo服务器运行并启用了'McpApiAdapter'后，它将作为一个MCP服务器运行。MCP客户端需要配置连接到此服务器的信息，通常包括以下关键参数（以JSON格式配置）：

'name': 为此MCP服务器连接定义的唯一标识符（字符串）。客户端使用此名称引用服务器提供的工具。
'transport': 客户端与服务器通信的传输协议（字符串）。例如，如果Xaibo服务器通过HTTP暴露MCP，可能是 '"sse"' (Server-Sent Events) 或 '"websocket"'。如果客户端与服务器在同一机器上通过标准输入/输出通信，可能是 '"stdio"'。
'url': 服务器的完整网络地址（字符串）。对于'sse'或'websocket'传输，通常是'"http://your_server_address:port/mcp"' 或 '"ws://your_server_address:port/mcp"'。
'command': （仅适用于'stdio'传输）启动服务器进程的命令及其参数列表（字符串列表）。
'args': （仅适用于'stdio'传输）传递给服务器启动命令的额外参数列表（字符串列表）。
'env': （仅适用于'stdio'传输）为服务器进程设置的环境变量（字符串键值对对象）。
'headers': （可选）用于身份验证或其他配置的HTTP头（字符串键值对对象）。例如，如果Xaibo服务器配置了API密钥，您可能需要在此包含'{"Authorization": "Bearer your_api_key"}'。

基本使用方法

启动Xaibo开发服务器并启用MCP适配器。在项目目录下运行（这将同时启动调试UI、OpenAI兼容API和MCP API，默认端口9001）：

uv run xaibo dev --adapter xaibo.server.adapters.McpApiAdapter
# 或者使用pip安装后直接运行服务器模块
# python -m xaibo.server.web --agent-dir ./agents --adapter xaibo.server.adapters.McpApiAdapter --host 127.0.0.1 --port 9001

一旦服务器运行，任何兼容MCP协议的客户端都可以连接到'http://127.0.0.1:9001/mcp' (SSE/HTTP POST) 或 'ws://127.0.0.1:9001/mcp' (WebSocket)，通过发送JSON-RPC请求与Xaibo Agent进行交互。客户端可以：
- 发送'initialize'请求进行握手。
- 发送'tools/list'请求发现所有已注册的Xaibo Agent（它们被暴露为MCP工具）。
- 发送'tools/call'请求调用特定的Xaibo Agent工具，并传递相应的参数（通常包含一个'message'字段）。

关键词

信息