Skip to content

Agent 工具开发 ​

构建强大、安全、可复用的 Agent 工具


📋 工具开发概述 ​

Agent 工具是连接 AI 模型与外部世界的桥梁。一个优秀的工具应该具备以下特性:

  • ✅ 易用性:清晰的接口和文档
  • ✅ 安全性:完善的输入验证和权限控制
  • ✅ 可靠性:健壮的错误处理和重试机制
  • ✅ 可扩展性:支持配置和定制
  • ✅ 可观测性:详细的日志和监控

🏗️ 工具架构 ​

工具组件 ​

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   工具接口      │ ←→  │   工具核心      │ ←→  │   工具实现      │
│  (Interface)    │     │  (Core)         │     │  (Implementation)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                      │                      │
         │ 输入验证              │ 业务逻辑            │ 外部调用
         │ 参数解析              │ 错误处理            │ API调用
         │ 格式转换              │ 缓存管理            │ 数据库操作
         └──────────────────────┘                      │
                                                       │
                                    ┌──────────────────┘
                                    ▼
                          ┌─────────────────┐
                          │   工具元数据    │
                          │  (Metadata)     │
                          └─────────────────┘

工具分类 ​

类别说明示例
信息获取获取外部信息Web搜索、天气、新闻
数据处理处理数据计算、转换、分析
文件操作读写文件读取、写入、列表
系统操作系统级操作Shell命令、进程管理
API调用调用外部APIREST、GraphQL、SOAP
数据库数据库操作查询、插入、更新
通信发送消息邮件、短信、通知

🔧 工具开发流程 ​

步骤1:定义工具接口 ​

python
from abc import ABC, abstractmethod
from typing import Dict, Any

class BaseTool(ABC):
    """工具基类"""
    
    name: str = ""
    description: str = ""
    version: str = "1.0.0"
    category: str = "general"
    risk_level: str = "low"
    
    @abstractmethod
    def execute(self, **kwargs) -> Dict[str, Any]:
        """执行工具"""
        pass
    
    def validate_input(self, **kwargs) -> bool:
        """验证输入"""
        return True
    
    def get_schema(self) -> Dict[str, Any]:
        """获取工具schema"""
        return {
            "name": self.name,
            "description": self.description,
            "version": self.version,
            "category": self.category,
            "risk_level": self.risk_level
        }

步骤2:实现工具核心 ​

python
class WebSearchTool(BaseTool):
    """Web搜索工具"""
    
    name = "web_search"
    description = "搜索互联网获取最新信息"
    category = "information"
    risk_level = "low"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
    
    def execute(self, query: str, max_results: int = 5) -> Dict[str, Any]:
        """执行搜索"""
        # 验证输入
        if not self.validate_input(query=query, max_results=max_results):
            return {"success": False, "message": "输入验证失败"}
        
        # 调用搜索API
        results = self._search(query, max_results)
        
        return {
            "success": True,
            "data": {"results": results},
            "message": "搜索成功"
        }
    
    def validate_input(self, query: str, max_results: int) -> bool:
        """验证输入"""
        if not query or len(query) > 200:
            return False
        if max_results < 1 or max_results > 20:
            return False
        return True
    
    def _search(self, query: str, max_results: int) -> list:
        """内部搜索实现"""
        # 调用真实的搜索API
        return [
            {
                "title": f"搜索结果 {i+1}",
                "url": f"https://example.com/result/{i}",
                "snippet": f"关于'{query}'的搜索结果..."
            }
            for i in range(max_results)
        ]

步骤3:注册工具 ​

python
from typing import List, Dict

class ToolRegistry:
    """工具注册中心"""
    
    def __init__(self):
        self.tools: Dict[str, BaseTool] = {}
    
    def register_tool(self, tool: BaseTool):
        """注册工具"""
        self.tools[tool.name] = tool
        print(f"注册工具: {tool.name}")
    
    def register_tools(self, tools: List[BaseTool]):
        """批量注册工具"""
        for tool in tools:
            self.register_tool(tool)
    
    def get_tool(self, name: str) -> BaseTool:
        """获取工具"""
        return self.tools.get(name)
    
    def list_tools(self) -> List[Dict]:
        """列出所有工具"""
        return [tool.get_schema() for tool in self.tools.values()]
    
    def get_tools_by_category(self, category: str) -> List[Dict]:
        """按类别获取工具"""
        return [
            tool.get_schema()
            for tool in self.tools.values()
            if tool.category == category
        ]

# 使用注册中心
registry = ToolRegistry()
registry.register_tool(WebSearchTool(api_key="your-api-key"))

# 获取工具
search_tool = registry.get_tool("web_search")
result = search_tool.execute(query="2026年AI趋势")

🛡️ 安全设计 ​

输入验证 ​

python
from pydantic import BaseModel, ValidationError, Field

class SearchInput(BaseModel):
    """搜索输入验证"""
    query: str = Field(..., min_length=1, max_length=200)
    max_results: int = Field(5, ge=1, le=20)

class SafeSearchTool(BaseTool):
    """安全的搜索工具"""
    
    def execute(self, **kwargs) -> Dict[str, Any]:
        try:
            # 使用Pydantic验证
            input_data = SearchInput(**kwargs)
        except ValidationError as e:
            return {"success": False, "message": f"输入验证失败: {e}"}
        
        # 执行搜索
        results = self._search(input_data.query, input_data.max_results)
        return {"success": True, "data": {"results": results}}

权限控制 ​

python
class PermissionTool(BaseTool):
    """带权限控制的工具"""
    
    def __init__(self, allowed_roles: list = None):
        self.allowed_roles = allowed_roles or ["admin", "user"]
    
    def execute(self, **kwargs) -> Dict[str, Any]:
        # 检查权限
        user_role = kwargs.get("user_role")
        if user_role not in self.allowed_roles:
            return {"success": False, "message": "无权限访问"}
        
        # 执行操作
        return self._execute(**kwargs)

🔄 高级特性 ​

缓存支持 ​

python
from functools import lru_cache

class CachedTool(BaseTool):
    """带缓存的工具"""
    
    def __init__(self, cache_size: int = 100):
        self._cache_size = cache_size
        self._cache = {}
    
    def execute(self, **kwargs) -> Dict[str, Any]:
        # 生成缓存键
        cache_key = self._generate_cache_key(**kwargs)
        
        # 检查缓存
        if cache_key in self._cache:
            return self._cache[cache_key]
        
        # 执行工具
        result = self._execute(**kwargs)
        
        # 存入缓存
        if len(self._cache) >= self._cache_size:
            # 移除最早的缓存
            oldest_key = next(iter(self._cache))
            del self._cache[oldest_key]
        self._cache[cache_key] = result
        
        return result
    
    def _generate_cache_key(self, **kwargs) -> str:
        """生成缓存键"""
        return hash(tuple(sorted(kwargs.items())))
    
    def clear_cache(self):
        """清空缓存"""
        self._cache.clear()

异步支持 ​

python
import asyncio

class AsyncTool(BaseTool):
    """异步工具"""
    
    async def execute_async(self, **kwargs) -> Dict[str, Any]:
        """异步执行"""
        loop = asyncio.get_event_loop()
        result = await loop.run_in_executor(
            None,
            self.execute,
            **kwargs
        )
        return result
    
    async def execute_parallel(self, tasks: list) -> list:
        """并行执行"""
        results = await asyncio.gather(*[
            self.execute_async(**task)
            for task in tasks
        ])
        return results

重试机制 ​

python
import time

class RetryTool(BaseTool):
    """带重试的工具"""
    
    def __init__(self, max_retries: int = 3, retry_delay: float = 1.0):
        self.max_retries = max_retries
        self.retry_delay = retry_delay
    
    def execute_with_retry(self, **kwargs) -> Dict[str, Any]:
        """带重试的执行"""
        for attempt in range(self.max_retries):
            try:
                result = self.execute(**kwargs)
                if result["success"]:
                    return result
            except Exception as e:
                if attempt < self.max_retries - 1:
                    time.sleep(self.retry_delay * (2 ** attempt))
                    continue
                return {"success": False, "message": f"执行失败: {e}"}
        
        return {"success": False, "message": "重试次数已用尽"}

🧪 工具测试 ​

单元测试 ​

python
import pytest
from web_search_tool import WebSearchTool

class TestWebSearchTool:
    """Web搜索工具测试"""
    
    def setup_method(self):
        self.tool = WebSearchTool(api_key="test-key")
    
    def test_valid_input(self):
        """测试有效输入"""
        result = self.tool.execute(query="test", max_results=5)
        assert result["success"]
        assert len(result["data"]["results"]) == 5
    
    def test_invalid_query(self):
        """测试无效查询"""
        result = self.tool.execute(query="", max_results=5)
        assert not result["success"]
    
    def test_invalid_max_results(self):
        """测试无效的结果数量"""
        result = self.tool.execute(query="test", max_results=0)
        assert not result["success"]

集成测试 ​

python
@pytest.mark.asyncio
async def test_tool_integration():
    """工具集成测试"""
    registry = ToolRegistry()
    registry.register_tool(WebSearchTool(api_key="test-key"))
    
    tool = registry.get_tool("web_search")
    result = tool.execute(query="2026年AI趋势", max_results=3)
    
    assert result["success"]
    assert "results" in result["data"]

📦 工具打包 ​

创建工具包 ​

python
# setup.py
from setuptools import setup, find_packages

setup(
    name="harness-agent-tools",
    version="1.0.0",
    description="Harness Engineering Agent工具集",
    packages=find_packages(),
    install_requires=[
        "requests>=2.28.0",
        "pydantic>=2.0.0"
    ],
    entry_points={
        "agent_tools": [
            "web_search = tools.web_search:WebSearchTool",
            "calculator = tools.calculator:CalculatorTool",
            "file_read = tools.file_read:FileReadTool"
        ]
    }
)

发布工具 ​

bash
# 构建包
python setup.py sdist bdist_wheel

# 上传到PyPI
twine upload dist/*

🔗 快速导航 ​

章节内容
项目概述工具开发核心概念
工具设计工具接口与架构设计
安全实践安全验证与权限控制
高级特性缓存、异步、重试
测试发布测试方法与发布流程