# Reson Agent

可扩展的 Agent 框架。支持多步工具调用、计划管理、子 Agent 协作、回溯重跑和上下文压缩。

## Quick Start

```bash
pip install -r requirements.txt

# 配置 LLM API Key
cp .env.example .env  # 编辑填入 API Key
```

### 最小示例

```python
import asyncio
from agent import AgentRunner, RunConfig
from agent.trace import FileSystemTraceStore
from agent.llm import create_openrouter_llm_call

runner = AgentRunner(
    trace_store=FileSystemTraceStore(base_path=".trace"),
    llm_call=create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5"),
)

async def main():
    async for item in runner.run(
        messages=[{"role": "user", "content": "列出当前目录的文件"}],
        config=RunConfig(model="anthropic/claude-sonnet-4.5"),
    ):
        print(item)

asyncio.run(main())
```

## 自定义工具

用 `@tool` 装饰器注册。`RunConfig(tools=None)`（默认）时所有已注册工具自动对 LLM 可用，无需额外配置。

```python
from agent import tool, ToolResult

@tool(description="查询产品库存")
async def check_inventory(product_id: str, warehouse: str = "default") -> ToolResult:
    """查询指定仓库的产品库存

    Args:
        product_id: 产品唯一标识符
        warehouse: 仓库编码，默认为主仓库
    """
    stock = await query_db(product_id, warehouse)
    return ToolResult(output=f"库存: {stock}")

# 确保此模块在 runner.run() 之前被 import
```

**注意**: `@tool` 通过副作用注册到全局 registry，必须确保定义工具的模块在调用 `runner.run()` 前被 import。

### 参数 Schema 生成

框架从函数签名和 docstring 自动生成 OpenAI Tool Schema，无需手写 JSON：

- **参数类型**：从类型注解推断（`str`/`int`/`float`/`bool`/`list`/`dict`，支持 `Optional`、`Literal`、`List[T]`）
- **参数描述**：从 Google 风格 docstring 的 `Args:` 段提取
- **必填/可选**：有默认值的参数为可选，否则为必填
- **工具描述**：优先使用 `@tool(description=...)` 参数，其次取 docstring 首行
- `uid` 和 `context` 参数由框架自动注入，不会出现在 Schema 中

上面的 `check_inventory` 会生成：

```json
{
  "type": "function",
  "function": {
    "name": "check_inventory",
    "description": "查询产品库存",
    "parameters": {
      "type": "object",
      "properties": {
        "product_id": {"type": "string", "description": "产品唯一标识符"},
        "warehouse": {"type": "string", "description": "仓库编码，默认为主仓库", "default": "default"}
      },
      "required": ["product_id"]
    }
  }
}
```

### 限制工具范围

```python
# 只启用指定工具（在内置工具基础上追加）
config = RunConfig(tools=["check_inventory", "another_tool"])
```

## 自定义 Skills

Skills 是 Markdown 文件，提供领域知识，注入到 system prompt。

```
my_project/
└── skills/
    └── my_domain.md
```

```markdown
---
name: my-domain-skill
description: 领域专属知识
---

## Guidelines
- 规则 1
- 规则 2
```

```python
runner = AgentRunner(
    llm_call=...,
    trace_store=...,
    skills_dir="./skills",  # 指向你的 skills 目录
)
```

内置 skills（`agent/memory/skills/`）始终自动加载，`skills_dir` 的内容额外追加。

## AgentRunner 参数

```python
AgentRunner(
    llm_call,                # 必需：LLM 调用函数
    trace_store=None,        # Trace 持久化（推荐 FileSystemTraceStore）
    tool_registry=None,      # 工具注册表（默认：全局 registry）
    skills_dir=None,         # 自定义 skills 目录
    experiences_path="./.cache/experiences.md",  # 经验文件路径
    memory_store=None,       # 记忆存储
    utility_llm_call=None,   # 轻量 LLM（生成任务标题等）
)
```

## RunConfig 参数

```python
RunConfig(
    model="gpt-4o",          # 模型标识
    temperature=0.3,
    max_iterations=200,       # Agent loop 最大轮数
    tools=None,               # None=全部已注册工具，List[str]=内置+指定工具
    system_prompt=None,       # None=从 skills 自动构建
    agent_type="default",     # 预设类型：default / explore / analyst
    trace_id=None,            # 续跑/回溯时传入已有 trace ID
    after_sequence=None,      # 从哪条消息后续跑（message sequence）
)
```

## LLM Providers

框架内置两个 provider：

```python
from agent.llm import create_openrouter_llm_call, create_gemini_llm_call

# OpenRouter（支持多种模型）
llm = create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5")

# Google Gemini
llm = create_gemini_llm_call(model="gemini-2.5-flash")
```

自定义 provider 只需实现签名：

```python
async def my_llm_call(messages, model, tools, temperature, **kwargs) -> dict:
    # 调用你的 LLM
    return {
        "content": "...",
        "tool_calls": [...] or None,
        "prompt_tokens": 100,
        "completion_tokens": 50,
        "cost": 0.001,
        "finish_reason": "stop",
    }
```

## API Server

```bash
python api_server.py
```

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/traces` | 列出 Traces |
| GET | `/api/traces/{id}` | Trace 详情 |
| GET | `/api/traces/{id}/messages` | 消息列表 |
| POST | `/api/traces` | 新建并执行 |
| POST | `/api/traces/{id}/run` | 续跑/回溯 |
| POST | `/api/traces/{id}/stop` | 停止 |
| WS | `/api/traces/{id}/watch` | 实时事件 |

需在 `api_server.py` 中配置 Runner 才能启用 POST 端点。

## 项目结构

```
agent/
├── core/           # AgentRunner + 预设
├── tools/          # 工具系统（registry + 内置工具）
├── trace/          # 执行追踪 + 计划（GoalTree）+ API
├── memory/         # Skills + Experiences
└── llm/            # LLM Provider 适配
```

详细架构文档：[docs/README.md](./docs/README.md)