# 如何快速实现自己的 Agent - 完整指南

## 📚 文档索引

1. **[QUICKSTART.md](./QUICKSTART.md)** - 快速上手指南
   - 三步快速开始
   - 核心组件详解
   - 实战案例
   - 高级功能
   - 最佳实践

2. **[examples/production_template/](./examples/production_template/)** - 生产级模板
   - 完整的生产级代码
   - 配置管理
   - 错误处理
   - 日志记录
   - 部署指南

3. **[examples/content_finder/](./examples/content_finder/)** - 实战案例
   - 内容寻找 Agent 完整实现
   - 工具、记忆、技能完整示例
   - 可运行的演示代码

## 🚀 快速开始（5分钟）

### 1. 安装依赖

```bash
pip install -r requirements.txt
pip install dbutils pymysql  # browser 模块依赖
```

### 2. 配置环境

```bash
cp .env.example .env
# 编辑 .env 填入 OPENROUTER_API_KEY
```

### 3. 运行模板

```bash
python examples/production_template/run.py
```

## 📖 学习路径

### 初学者

1. **阅读** [QUICKSTART.md](./QUICKSTART.md) 的"三步快速开始"部分
2. **运行** `examples/content_finder/demo.py` 查看效果
3. **修改** demo.py 中的任务描述，尝试不同功能
4. **创建** 第一个自定义工具

### 进阶开发者

1. **学习** [QUICKSTART.md](./QUICKSTART.md) 的"核心组件"和"高级功能"
2. **研究** `examples/production_template/` 的代码结构
3. **实现** 自己的业务工具和 Skills
4. **部署** 到生产环境

### 生产使用

1. **复制** `examples/production_template/` 作为起点
2. **替换** 示例工具为实际业务工具
3. **编写** 业务相关的 Skills
4. **配置** 监控、日志、告警
5. **部署** 到生产环境

## 🎯 核心概念

### 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. 工具设计

```python
@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 编写

```markdown
---
name: skill-name
description: 简短描述
category: 分类
---

# 技能名称

## 何时使用

- 明确的使用场景
- 具体的触发条件

## 工作流程

1. 第一步做什么
2. 第二步做什么
3. 如何验证结果

## 最佳实践

- 实用的建议
- 常见陷阱
```

### 3. 配置管理

```python
# 使用环境变量
MODEL = os.getenv("MODEL", "default-model")

# 验证配置
if not API_KEY:
    raise ValueError("API_KEY 未设置")

# 创建必要的目录
Path(output_dir).mkdir(parents=True, exist_ok=True)
```

### 4. 错误处理

```python
try:
    result = await agent.run(task)
except Exception as e:
    logger.error(f"执行失败: {e}", exc_info=True)
    # 发送告警
    # 保存错误信息
    # 返回友好的错误消息
```

## 🔧 常用模式

### 模式1：简单任务执行

```python
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：带自定义工具

```python
# 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

```python
# 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：生产级封装

```python
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. 选择合适的模型

```python
# 简单任务：使用 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. 限制迭代次数

```python
config = RunConfig(
    max_iterations=20,  # 防止无限循环
)
```

### 3. 启用 Prompt Caching

```python
config = RunConfig(
    enable_prompt_caching=True,  # Claude 模型支持
)
```

### 4. 限制工具权限

```python
config = RunConfig(
    agent_type="explore",  # 只读权限，更快
)
```

## 🐛 调试技巧

### 1. 打印所有消息

```python
async for item in runner.run(...):
    print(f"[{type(item).__name__}] {item}")
```

### 2. 查看 Trace

```python
trace = await trace_store.get_trace(trace_id)
for msg in trace.messages:
    print(f"{msg.role}: {msg.content}")
```

### 3. 启动可视化

```bash
python api_server.py
# 访问 http://localhost:8000/api/traces
```

### 4. 查看日志

```python
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           # 说明文档
```

## 🎓 下一步

1. ✅ 阅读 [QUICKSTART.md](./QUICKSTART.md)
2. ✅ 运行 `examples/content_finder/demo.py`
3. ✅ 复制 `examples/production_template/`
4. ✅ 实现第一个自定义工具
5. ✅ 编写第一个 Skill
6. ✅ 部署到生产环境

## 💬 获取帮助

- **文档**：查看 `agent/README.md` 和 `agent/docs/`
- **示例**：参考 `examples/` 目录
- **问题**：检查日志和 Trace

---

**开始构建你的 Agent 吧！** 🚀