Python实现AI智能体工具调用系统开发指南

1. 课程概述：构建具备工具调用能力的AI智能体

在AI智能体开发领域，让大语言模型(LLM)具备调用外部工具的能力是突破纯文本交互限制的关键一步。本课程将带您深入实现一个生产级的工具调用系统，让您的AI助手能够：

• 读取和写入本地文件
• 执行系统命令
• 进行网络搜索
• 浏览目录结构

这个实现基于Python 3.10+和OpenAI函数调用API规范，采用了面向对象设计模式和异步编程模型，确保系统既具备良好的扩展性又能高效处理I/O密集型操作。

重要提示：本课程代码需要安装Python 3.10或更高版本，并预先配置好OpenAI API密钥。建议在虚拟环境中进行开发。

2. 工具调用系统架构设计

2.1 核心组件关系图

我们的工具调用系统由三个核心组件构成：

code复制[Tool基类] ← 继承 → [具体工具实现]
      ↑
      | 注册
      ↓
[ToolRegistry] ← 使用 → [Agent]

2.2 工具调用工作流程

1. 初始化阶段：

   • 创建ToolRegistry实例
   • 注册所有可用工具
   • 初始化Agent时传入ToolRegistry

2. 运行时交互：

   mermaid复制sequenceDiagram
       participant User
       participant Agent
       participant LLM
       participant Tool
       
       User->>Agent: 发送请求
       Agent->>LLM: 请求+工具定义
       LLM->>Agent: 返回工具调用请求
       Agent->>Tool: 执行工具
       Tool->>Agent: 返回结果
       Agent->>LLM: 发送工具结果
       LLM->>Agent: 生成最终回复
       Agent->>User: 返回回复
   

3. 基础类实现详解

3.1 Tool抽象基类

Tool是所有具体工具的基类，定义在ultrabot/tools/base.py中：

python复制from __future__ import annotations
import abc
from typing import Any

class Tool(abc.ABC):
    """所有工具的抽象基类"""
    
    name: str = ""  # 工具唯一标识符
    description: str = ""  # 工具功能描述
    parameters: dict[str, Any] = {}  # 参数JSON Schema
    
    @abc.abstractmethod
    async def execute(self, arguments: dict[str, Any]) -> str:
        """异步执行工具的核心方法"""
        
    def to_definition(self) -> dict[str, Any]:
        """生成OpenAI兼容的工具定义"""
        return {
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": self.parameters,
            }
        }

关键设计考虑：

1. 使用abc.ABC确保子类必须实现execute方法
2. 参数使用JSON Schema规范，与OpenAI API兼容
3. async设计支持异步I/O操作

3.2 ToolRegistry工具注册表

python复制class ToolRegistry:
    """工具管理中心"""
    
    def __init__(self) -> None:
        self._tools: dict[str, Tool] = {}
    
    def register(self, tool: Tool) -> None:
        """注册工具实例"""
        if not tool.name:
            raise ValueError("工具必须设置name属性")
        self._tools[tool.name] = tool
    
    def get(self, name: str) -> Tool | None:
        """按名称获取工具"""
        return self._tools.get(name)
    
    def get_definitions(self) -> list[dict[str, Any]]:
        """获取所有工具定义"""
        return [tool.to_definition() for tool in self._tools.values()]
    
    # 其他方法...

注册表的核心功能：

• 提供工具的单点管理
• 支持动态添加/移除工具
• 生成LLM所需的工具定义列表

4. 内置工具实现

我们实现了5个基础工具，涵盖常见操作场景。

4.1 文件操作工具

ReadFileTool - 文件读取工具

python复制class ReadFileTool(Tool):
    name = "read_file"
    description = "读取文件内容，可指定起始行和行数限制"
    parameters = {
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "文件路径"},
            "offset": {"type": "integer", "description": "起始行号(1-based)"},
            "limit": {"type": "integer", "description": "最大读取行数"}
        },
        "required": ["path"]
    }
    
    async def execute(self, arguments: dict[str, Any]) -> str:
        path = Path(arguments["path"]).expanduser().resolve()
        
        # 安全性检查
        if not path.exists():
            return f"错误：文件不存在: {path}"
        if not path.is_file():
            return f"错误：不是常规文件: {path}"
        
        # 读取内容处理
        text = path.read_text(errors="replace")
        
        # 行切片处理
        if "offset