Agent 工具开发
构建强大、安全、可复用的 Agent 工具
📋 工具开发概述
Agent 工具是连接 AI 模型与外部世界的桥梁。一个优秀的工具应该具备以下特性:
- ✅ 易用性:清晰的接口和文档
- ✅ 安全性:完善的输入验证和权限控制
- ✅ 可靠性:健壮的错误处理和重试机制
- ✅ 可扩展性:支持配置和定制
- ✅ 可观测性:详细的日志和监控
🏗️ 工具架构
工具组件
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 工具接口 │ ←→ │ 工具核心 │ ←→ │ 工具实现 │
│ (Interface) │ │ (Core) │ │ (Implementation)│
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ 输入验证 │ 业务逻辑 │ 外部调用
│ 参数解析 │ 错误处理 │ API调用
│ 格式转换 │ 缓存管理 │ 数据库操作
└──────────────────────┘ │
│
┌──────────────────┘
▼
┌─────────────────┐
│ 工具元数据 │
│ (Metadata) │
└─────────────────┘工具分类
| 类别 | 说明 | 示例 |
|---|---|---|
| 信息获取 | 获取外部信息 | Web搜索、天气、新闻 |
| 数据处理 | 处理数据 | 计算、转换、分析 |
| 文件操作 | 读写文件 | 读取、写入、列表 |
| 系统操作 | 系统级操作 | Shell命令、进程管理 |
| API调用 | 调用外部API | REST、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/*🔗 快速导航
| 章节 | 内容 |
|---|---|
| 项目概述 | 工具开发核心概念 |
| 工具设计 | 工具接口与架构设计 |
| 安全实践 | 安全验证与权限控制 |
| 高级特性 | 缓存、异步、重试 |
| 测试发布 | 测试方法与发布流程 |