使用说明

项目简介

Agentical是一个基于Model Context Protocol (MCP) 的Python框架，旨在简化LLM与外部工具和数据源的集成。它提供了一套完整的工具，用于连接和管理多个MCP服务器，让LLM能够安全、可扩展地访问各种上下文信息和功能。

主要功能点

MCP协议集成：遵循MCP协议标准，确保与各类MCP服务器的兼容性。
模块化LLM后端：支持OpenAI、Gemini和Anthropic等主流LLM模型，易于扩展。
工具集成框架：提供清晰的接口和工具，方便开发者集成和使用各种外部工具。
多MCP服务器支持：可以同时连接和管理多个MCP服务器，实现跨工具的复杂操作。
灵活配置：通过JSON配置文件管理MCP服务器连接，支持环境变量配置。
异步设计：采用Async/Await异步架构，性能高效。

安装步骤

创建并激活虚拟环境 (推荐)

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate  # Windows

安装 Agentical 包

pip install beanone-agentical

服务器配置

Agentical 通过 'config.json' 文件配置需要连接的MCP服务器。以下是一个配置示例，展示了如何配置终端服务器、文件系统服务器和天气服务器。

{
  "terminal-server": {
    "command": "python",
    "args": ["server/terminal_server.py"],
    "env": {
      "WORKSPACE_DIR": "/path/to/workspace"  // 可选：指定终端服务器的工作目录
    }
  },
  "filesystem-server": {
    "command": "python",
    "args": ["server/fs_server.py"],
    "env": {
      "WORKSPACE_DIR": "/path/to/workspace"  // 可选：指定文件系统服务器的工作目录
    }
  },
  "weather-server": {
    "command": "python",
    "args": ["server/weather_server.py"],
    "env": {
      "OPENWEATHERMAP_API_KEY": "your-api-key-here"  // 必填：OpenWeatherMap API 密钥
    }
  }
}

配置说明:

server name: 服务器的名称，例如 'terminal-server'，用于在Agentical中标识和引用该服务器。
command: 启动MCP服务器的命令，通常是Python解释器路径 ('python')。
args: 传递给启动命令的参数列表，通常是服务器脚本的路径 ('server/terminal_server.py')。
env: 可选的环境变量配置，以键值对形式表示，用于服务器运行时需要的环境变量。例如 'WORKSPACE_DIR' 用于指定工作目录，'OPENWEATHERMAP_API_KEY' 用于天气API密钥。

注意:

您需要根据实际使用的MCP服务器修改 'command' 和 'args'，确保能够正确启动服务器。
部分服务器可能需要额外的环境变量配置，请参考服务器的文档或示例进行配置。
'config.json' 文件应与您的Agentical客户端代码在同一目录下，或者您可以通过命令行参数 '-c' 或 '--config' 指定配置文件路径。

基本使用方法

准备LLM后端 API Key

根据您选择的LLM后端（OpenAI, Gemini, Anthropic），您需要在 '.env' 文件中配置相应的API Key。例如，使用 OpenAI 后端，需要在 '.env' 文件中添加：
```
OPENAI_API_KEY=your_openai_api_key
```
运行示例 Demo

Agentical 提供了针对不同LLM后端的示例 Demo 脚本 ('demo_openai.py', 'demo_gemini.py', 'demo_anthropic.py')。您可以根据您的需求选择并运行相应的脚本。

例如，运行 OpenAI Demo：
```
python demo_openai.py
```
您也可以通过 '-c' 参数指定自定义的配置文件路径：
```
python demo_openai.py -c custom_config.json
```
交互式选择和使用 MCP 服务器

运行 Demo 脚本后，您将看到可用的 MCP 服务器列表。您可以选择连接到特定的服务器，或者选择 "All above servers" 连接到所有配置的服务器。

连接成功后，您可以在 "Query:" 提示符后输入自然语言查询，Agentical 将会调用LLM和相应的MCP工具来处理您的请求，并返回结果。

例如，您可以尝试以下查询：
- 'Read the contents of config.json and tell me if it has a weather API key configured. If yes, what's the current weather in that location?' (同时使用文件系统和天气工具)
- 'List all Python files in the current directory and show me the contents of any file that imports 'asyncio'' (同时使用终端和文件系统工具)
输入 'quit' 可以退出交互式会话。