# Rust Agent Crate
一个用Rust编写的AI Agent框架，提供与大语言模型集成、工具调用、MCP服务连接等功能，帮助开发者构建强大的智能应用。
## 项目简介
Rust-Agent 是一个模块化的智能代理开发框架，设计用于简化基于大语言模型的应用开发。该框架提供了统一的执行接口、灵活的工具集成机制以及与MCP服务的无缝连接能力，使开发者能够快速构建具有推理和工具使用能力的智能应用。
## 核心功能
- **统一执行接口**：基于 `Runnable<I, O>` 接口的统一执行模型，支持同步、异步和流式处理
- **大语言模型集成**：支持OpenAI等主流大语言模型的调用
- **智能代理系统**：提供 `McpAgent` 等代理实现，支持上下文管理和工具调用
- **工具调用机制**：灵活的工具注册和调用系统
- **MCP服务集成**：与MCP服务的连接适配器
- **异步编程支持**：基于Tokio的全异步设计
## 架构概览
项目采用模块化设计，主要包含以下核心模块：
```
src/
├── lib.rs # 主入口和公共导出
├── core/ # 核心抽象和接口
├── models/ # 语言模型集成
├── agents/ # 代理实现
├── tools/ # 工具定义和实现
├── mcp/ # MCP服务集成
├── memory/ # 记忆功能（预留模块）
└── callbacks/ # 回调机制（预留模块）
```
### 核心模块关系
- **core**: 定义了 `Runnable<I, O>` 等核心接口，是整个框架的基础
- **models**: 实现了 `ChatModel` 接口，负责与大语言模型交互
- **agents**: 实现了 `Agent` 接口和 `Runnable` 接口，是应用的核心逻辑处理器
- **tools**: 提供了工具定义和工具调用相关功能
- **mcp**: 提供了与MCP服务交互的客户端和适配器
## 快速开始
### 安装
在你的 `Cargo.toml` 文件中添加依赖：
```toml
dependencies = {
rust_agent = { path = "path/to/rust-agent-crate" }
}
```
### 基本用法
下面是一个使用 `McpAgent` 构建简单对话机器人的示例：
```rust
use rust_agent::{McpAgent, McpClient, ChatMessage, ChatMessageContent, AgentOutput};
use std::sync::Arc;
use std::collections::HashMap;
// 创建MCP客户端（实际使用时需要实现McpClient接口）
let mcp_client = Arc::new(YourMcpClientImplementation::new());
// 创建McpAgent实例
let mut agent = McpAgent::new(
mcp_client,
"gpt-3.5-turbo".to_string(),
"你是一个有用的助手".to_string()
);
// 添加工具（可选）
// agent.add_tool(Box::new(YourToolImplementation::new()));
// 构建用户输入
let mut input = HashMap::new();
input.insert("input".to_string(), "你好，今天天气怎么样？".to_string());
// 调用代理处理输入
let result = agent.invoke(input).await;
// 处理结果
match result {
Ok(AgentOutput::Finish(finish)) => {
if let Some(answer) = finish.return_values.get("answer") {
println!("AI回复: {}", answer);
}
},
Ok(AgentOutput::Action(action)) => {
println!("需要调用工具: {}", action.tool);
// 处理工具调用...
},
Err(e) => {
println!("发生错误: {}", e);
}
}
```
## 主要模块说明
### Core 模块
Core模块定义了框架的核心抽象和接口，其中最重要的是 `Runnable<I, O>` 接口。这个接口统一了所有组件的执行方式，支持同步调用、批量处理和流式输出。
```rust
// Runnable接口简化定义
trait Runnable<I, O> {
// 执行单个输入并返回结果
fn invoke(&self, input: I) -> Pin<Box<dyn Future<Output = Result<O, Error>> + Send>>;
// 执行多个输入并返回结果列表
fn batch(&self, inputs: Vec<I>) -> Pin<Box<dyn Future<Output = Result<Vec<O>, Error>> + Send>>;
// 流式处理输入并返回结果流
fn stream(&self, input: I) -> Pin<Box<dyn Stream<Item = Result<O, Error>> + Send>>;
}
```
### Models 模块
Models模块提供了与大语言模型的集成，主要实现了 `ChatModel` 接口。当前支持OpenAI兼容的接口，如示例中的 `OpenAIChatModel`。
```rust
// 创建OpenAI模型实例
let model = OpenAIChatModel::new("your-api-key".to_string(), Some("https://api.openai.com/v1"))
.with_model("gpt-4".to_string())
.with_temperature(0.7);
// 构建消息
let messages = vec![
ChatMessage::System(ChatMessageContent {
content: "你是一个助手".to_string(),
name: None,
additional_kwargs: HashMap::new()
}),
ChatMessage::Human(ChatMessageContent {
content: "你好".to_string(),
name: None,
additional_kwargs: HashMap::new()
})
];
// 调用模型
let result = model.invoke(messages).await;
```
### Agents 模块
Agents模块实现了智能代理的核心逻辑，其中 `McpAgent` 是主要的实现类。它集成了语言模型调用、工具管理和响应生成等功能。
`McpAgent` 的主要功能包括：
- 处理用户输入
- 调用语言模型生成响应
- 解析模型输出，判断是否需要调用工具
- 执行工具调用（如果需要）
- 返回最终结果
### Tools 模块
Tools模块定义了工具的接口和实现机制。工具是代理可以调用的外部函数或服务，用于扩展代理的能力。框架提供了工具注册、查找和调用的统一机制。
### MCP 模块
MCP模块提供了与MCP服务交互的客户端和适配器。MCP允许代理连接到远程服务并调用那里的工具。该模块定义了 `McpClient` 接口和 `McpToolAdapter` 适配器类。
## 示例
项目提供了多个示例，展示了如何使用框架构建不同类型的智能应用。示例位于 `examples/` 目录下。
例如，`mcp_agent_chatbot.rs` 示例展示了如何使用 `McpAgent` 构建一个简单的聊天机器人：
```bash
# 运行示例
cargo run --example mcp_agent_chatbot
```
## 配置和环境变量
使用框架时，可能需要配置以下环境变量：
- `OPENAI_API_KEY`: OpenAI API密钥
- `OPENAI_API_URL`: OpenAI API基础URL（可选，默认为OpenAI官方API）
## 注意事项
- 框架使用异步编程模型，需要配合Tokio运行时
- 工具调用需要实现 `Tool` 接口或使用 `McpToolAdapter` 适配器
- 当前版本可能存在一些未实现的功能或简化实现，使用时需要注意
## 开发和贡献
如果你想为项目做贡献，请遵循以下步骤：
1. Fork 仓库
2. 创建你的特性分支
3. 提交你的更改
4. 推送到分支
5. 创建一个 Pull Request
## License
[MIT License](LICENSE)