基于第 08 篇教程使用 Python 实现的轻量级 Agent 系统示例。
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
pip install -r requirements.txt
pip install pytest pytest-asyncio # 开发依赖# 运行 Mock 测试（无需 OpenAI API Key）
python examples/test_no_api_key.py
# 或运行单元测试
pytest tests/ -vexport OPENAI_API_KEY=your-api-key-here
# 基本用法
python examples/basic_usage.py
# 交互式 REPL
python examples/repl.py
# 自定义工具示例
python examples/custom_tool.py
# 多 Agent 协作示例
python examples/multi_agent_collaboration.py
# MCP 集成示例
python examples/mcp_integration.pysimple-agent-python/
├── src/
│ ├── agent/
│ │ ├── __init__.py
│ │ ├── agent.py # Agent 核心类
│ │ ├── llm_client.py # OpenAI 客户端封装
│ │ └── types.py # 类型定义
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── base.py # Tool 基类
│ │ ├── bash_tool.py # Bash 工具
│ │ ├── file_read_tool.py # 文件读取工具
│ │ └── file_write_tool.py# 文件写入工具
│ ├── state/
│ │ ├── __init__.py
│ │ ├── store.py # 状态管理
│ │ └── session.py # 会话持久化
│ ├── permissions/
│ │ ├── __init__.py
│ │ ├── checker.py # 权限检查
│ │ └── types.py # 权限类型
│ └── __init__.py # 统一导出
├── examples/
│ ├── basic_usage.py # 基本用法
│ ├── repl.py # 交互式 REPL
│ └── custom_tool.py # 自定义工具
├── tests/
│ └── test_agent.py # 测试文件
├── requirements.txt
└── README.md
封装 OpenAI API，支持工具调用：
from src.agent.llm_client import LLMClient
client = LLMClient(
api_key="your-api-key",
model="gpt-4o",
max_tokens=4096,
)from src.agent.agent import Agent
from src.tools import get_builtin_tools
agent = Agent(
cwd=".",
api_key="your-api-key",
model="gpt-4o",
max_tokens=4096,
permission_mode="bypass_permissions",
)
agent.register_tools(get_builtin_tools())
agent.add_user_message("创建一个新的 Python 项目")
result = await agent.run()from src.tools.base import Tool, ToolResult
from pydantic import BaseModel
class WeatherInput(BaseModel):
city: str
async def get_weather(input: WeatherInput, context) -> ToolResult:
return ToolResult(content=f"Weather in {input.city}: sunny, 25°C")
weather_tool = Tool(
name="GetWeather",
description="Get current weather for a city",
input_schema=WeatherInput,
is_read_only=True,
call_fn=get_weather,
)| 模式 | 说明 |
|---|---|
default |
默认：需要用户确认 |
bypass_permissions |
跳过权限检查 |
dont_ask |
自动拒绝 |
accept_edits |
自动允许只读操作 |
auto |
AI 自动分类 |
SimpleAgent Python 版本包含以下健壮性改进：
- API 密钥验证：初始化时检查 API 密钥是否为空
- 模型验证：检查模型名称是否有效
- 参数范围验证：
max_tokens必须为正数，max_iterations必须为正数
- 工具输入验证：使用 Pydantic 模式验证工具输入参数
- 友好的错误消息：提供详细的验证错误信息，帮助调试
- 全局超时：通过
timeout_ms配置项设置 Agent 执行超时时间 - 工具执行超时：单个工具执行超过指定时间会自动取消
- LLM 请求超时：OpenAI API 调用支持超时设置
- 详细的错误分类：区分工具未找到、权限拒绝、输入无效、执行错误等
- 取消支持：支持
asyncio.CancelledError，可优雅取消长时间运行的任务 - 最大迭代次数保护：防止无限循环，默认 50 次，可配置
- 处理状态跟踪：
is_processing状态指示 Agent 是否正在运行 - 资源清理：确保在异常情况下正确重置状态
config = AgentConfig(
cwd=os.getcwd(),
api_key=api_key,
model="gpt-4o",
max_tokens=4096,
permission_mode="bypass_permissions",
max_iterations=20, # 限制最大迭代次数
timeout_ms=30000, # 30秒超时
)pytest tests/MIT