HOW_TO_BUILD_AGENT.md 8.2 KB
如何快速实现自己的 Agent - 完整指南
📚 文档索引
QUICKSTART.md - 快速上手指南
- 三步快速开始
- 核心组件详解
- 实战案例
- 高级功能
- 最佳实践
examples/production_template/ - 生产级模板
- 完整的生产级代码
- 配置管理
- 错误处理
- 日志记录
- 部署指南
examples/content_finder/ - 实战案例
- 内容寻找 Agent 完整实现
- 工具、记忆、技能完整示例
- 可运行的演示代码
🚀 快速开始（5分钟）
1. 安装依赖
pip install -r requirements.txt
pip install dbutils pymysql # browser 模块依赖
2. 配置环境
cp .env.example .env
# 编辑 .env 填入 OPENROUTER_API_KEY
3. 运行模板
python examples/production_template/run.py
📖 学习路径
初学者
- 阅读 QUICKSTART.md 的"三步快速开始"部分
- 运行
examples/content_finder/demo.py查看效果 - 修改 demo.py 中的任务描述，尝试不同功能
- 创建 第一个自定义工具
进阶开发者
- 学习 QUICKSTART.md 的"核心组件"和"高级功能"
- 研究
examples/production_template/的代码结构 - 实现 自己的业务工具和 Skills
- 部署 到生产环境
生产使用
- 复制
examples/production_template/作为起点 - 替换 示例工具为实际业务工具
- 编写 业务相关的 Skills
- 配置 监控、日志、告警
- 部署 到生产环境
🎯 核心概念
Agent = Runner + Tools + Skills
┌─────────────────────────────────────┐
│ AgentRunner │
│ ┌──────────┐ ┌──────────┐ │
│ │ LLM │ │ Trace │ │
│ │ Call │ │ Store │ │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────┘
│
┌──────┴──────┐
│ │
┌───▼───┐ ┌───▼────┐
│ Tools │ │ Skills │
│ │ │ │
│ 工具 │ │ 技能 │
│ 能力 │ │ 知识 │
└───────┘ └────────┘
工具 (Tools)
- 定义：Agent 可以调用的函数
- 作用：扩展 Agent 的能力（读文件、调 API、查数据库等）
- 实现：使用
@tool装饰器
技能 (Skills)
- 定义：Markdown 格式的知识文档
- 作用：指导 Agent 如何工作（何时用什么工具、如何处理任务）
- 实现：创建
.md文件，使用 YAML frontmatter
执行追踪 (Trace)
- 定义：一次完整的 Agent 执行过程
- 作用：记录所有消息、工具调用、结果
- 用途：调试、回溯、续跑
💡 最佳实践
1. 工具设计
@tool(description="简洁清晰的描述")
async def my_tool(
param: str, # 明确的参数类型
optional: str = "default", # 可选参数有默认值
ctx: ToolContext = None, # 上下文参数
) -> ToolResult:
"""
详细的文档字符串
Args:
param: 参数说明
optional: 可选参数说明
"""
try:
# 业务逻辑
result = do_something(param)
return ToolResult(
title="成功",
output="结果描述",
data={"key": "value"}, # 结构化数据
)
except Exception as e:
logger.error(f"错误: {e}", exc_info=True)
return ToolResult(
title="失败",
output=str(e),
error=True,
)
2. Skill 编写
---
name: skill-name
description: 简短描述
category: 分类
---
# 技能名称
## 何时使用
- 明确的使用场景
- 具体的触发条件
## 工作流程
1. 第一步做什么
2. 第二步做什么
3. 如何验证结果
## 最佳实践
- 实用的建议
- 常见陷阱
3. 配置管理
# 使用环境变量
MODEL = os.getenv("MODEL", "default-model")
# 验证配置
if not API_KEY:
raise ValueError("API_KEY 未设置")
# 创建必要的目录
Path(output_dir).mkdir(parents=True, exist_ok=True)
4. 错误处理
try:
result = await agent.run(task)
except Exception as e:
logger.error(f"执行失败: {e}", exc_info=True)
# 发送告警
# 保存错误信息
# 返回友好的错误消息
🔧 常用模式
模式1：简单任务执行
runner = AgentRunner(llm_call=llm, trace_store=store)
async for item in runner.run(
messages=[{"role": "user", "content": "任务"}],
config=RunConfig(model="claude-sonnet-4.5"),
):
if isinstance(item, Message):
print(item.content)
模式2：带自定义工具
# 1. 定义工具
@tool(description="我的工具")
async def my_tool(param: str, ctx: ToolContext = None) -> ToolResult:
return ToolResult(output="结果")
# 2. 确保工具被导入
import my_tools # 触发 @tool 注册
# 3. 运行
runner = AgentRunner(llm_call=llm, trace_store=store)
async for item in runner.run(...):
pass
模式3：带 Skills
# 1. 创建 skills/my-skill.md
# 2. 加载 skills
runner = AgentRunner(
llm_call=llm,
trace_store=store,
skills_dir="./skills",
)
# 3. 指定使用的 skills
config = RunConfig(skills=["my-skill"])
模式4：生产级封装
class MyAgent:
def __init__(self, config):
self.runner = AgentRunner(...)
async def run(self, task: str) -> Dict:
try:
result = await self._execute(task)
self._save_result(result)
return result
except Exception as e:
self._handle_error(e)
raise
📊 性能优化
1. 选择合适的模型
# 简单任务：使用 Haiku（快+便宜）
llm = create_openrouter_llm_call(model="anthropic/claude-haiku-4.5")
# 复杂任务：使用 Sonnet（平衡）
llm = create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5")
# 极难任务：使用 Opus（最强）
llm = create_openrouter_llm_call(model="anthropic/claude-opus-4.6")
2. 限制迭代次数
config = RunConfig(
max_iterations=20, # 防止无限循环
)
3. 启用 Prompt Caching
config = RunConfig(
enable_prompt_caching=True, # Claude 模型支持
)
4. 限制工具权限
config = RunConfig(
agent_type="explore", # 只读权限，更快
)
🐛 调试技巧
1. 打印所有消息
async for item in runner.run(...):
print(f"[{type(item).__name__}] {item}")
2. 查看 Trace
trace = await trace_store.get_trace(trace_id)
for msg in trace.messages:
print(f"{msg.role}: {msg.content}")
3. 启动可视化
python api_server.py
# 访问 http://localhost:8000/api/traces
4. 查看日志
logging.basicConfig(level=logging.DEBUG)
📦 项目模板
my_agent/
├── run.py # 主程序
├── tools/ # 自定义工具
│ ├── __init__.py
│ ├── api.py
│ └── database.py
├── skills/ # Skills
│ ├── main.md
│ └── helper.md
├── .env # 环境变量
├── .env.example # 环境变量示例
├── requirements.txt # 依赖
└── README.md # 说明文档
🎓 下一步
- ✅ 阅读 QUICKSTART.md
- ✅ 运行
examples/content_finder/demo.py - ✅ 复制
examples/production_template/ - ✅ 实现第一个自定义工具
- ✅ 编写第一个 Skill
- ✅ 部署到生产环境
💬 获取帮助
- 文档：查看
agent/README.md和agent/docs/ - 示例：参考
examples/目录 - 问题：检查日志和 Trace
开始构建你的 Agent 吧！ 🚀