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 文件中添加依赖：

dependencies = {
    rust_agent = { path = "path/to/rust-agent-crate" }
}

基本用法

下面是一个使用 McpAgent 构建简单对话机器人的示例：

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> 接口。这个接口统一了所有组件的执行方式，支持同步调用、批量处理和流式输出。

// 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。

// 创建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 构建一个简单的聊天机器人：

# 运行示例
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