# Reson Agent

可扩展、可学习的 Agent 框架，支持执行追踪和持久记忆。

## 核心特性

- **执行追踪**：每次 LLM 调用、工具调用、结论都记录为 Step，形成可视化的执行图
- **三层记忆**：Task State（任务状态）→ Experience（经验规则）→ Skill（归纳技能）
- **存储可插拔**：通过 Protocol 定义存储接口，支持内存、PostgreSQL、Neo4j 等实现
- **工具系统**：`@tool` 装饰器自动注册工具，支持 Schema 生成、确认机制、参数编辑

## 安装

```bash
# 基础安装
pip install reson-agent

# 带 PostgreSQL 支持
pip install reson-agent[postgres]

# 完整安装
pip install reson-agent[all]
```

## 快速开始

### 1. 单次调用（不需要 Agent 能力）

```python
from reson_agent import AgentRunner
from reson_agent.storage import MemoryTraceStore

# 最简使用
runner = AgentRunner(
    trace_store=MemoryTraceStore()  # 内存存储，测试用
)

result = await runner.call(
    messages=[{"role": "user", "content": "你好"}],
    model="gpt-4o"
)
print(result.reply)
```

### 2. Agent 模式（带执行追踪）

```python
from reson_agent import AgentRunner
from reson_agent.storage import MemoryTraceStore, MemoryMemoryStore
from reson_agent.tools import tool

# 注册工具
@tool(
    editable_params=["query"],
    display={"zh": {"name": "搜索", "params": {"query": "关键词"}}}
)
async def search(query: str, uid: str = "") -> str:
    """搜索相关内容"""
    return f"搜索结果: {query}"

# 创建 Runner
runner = AgentRunner(
    trace_store=MemoryTraceStore(),
    memory_store=MemoryMemoryStore(),  # 可选，启用经验/技能
)

# 执行任务
async for event in runner.run(
    task="帮我分析最近的阅读兴趣",
    agent_type="researcher",
    max_iterations=5
):
    if event.type == "llm_delta":
        print(event.data["delta"], end="")
    elif event.type == "conclusion":
        print(f"\n结论: {event.data['content']}")
```

### 3. 添加反馈

```python
# 对某个执行步骤给反馈
exp_id = await runner.add_feedback(
    trace_id="trace_abc",
    target_step_id="step_123",
    feedback_type="correction",
    content="搜索时应该限制在最近30天内"
)
```

## 核心概念

### Trace（执行轨迹）

一次完整的 LLM 交互，包含多个 Step。

```python
@dataclass
class Trace:
    trace_id: str
    mode: Literal["call", "agent"]  # 单次调用 or Agent 模式
    status: Literal["running", "completed", "failed"]
    # ...
```

### Step（执行步骤）

Trace 中的一个原子操作。

```python
@dataclass
class Step:
    step_id: str
    trace_id: str
    step_type: Literal["llm_call", "tool_call", "tool_result", "conclusion", "feedback"]
    parent_ids: List[str]  # 形成 DAG
    data: Dict[str, Any]
```

### Experience（经验）

从执行或反馈中提取的规则。

```python
@dataclass
class Experience:
    condition: str   # 什么情况下适用
    rule: str        # 应该怎么做
    evidence: List[str]  # step_ids 作为证据
```

### Skill（技能）

从经验归纳的高层知识。

```python
@dataclass
class Skill:
    name: str
    guidelines: List[str]
    derived_from: List[str]  # experience_ids
```

## 存储适配

实现 `TraceStore` 和 `MemoryStore` Protocol 即可接入任何存储。

```python
from reson_agent.storage import TraceStore, MemoryStore

class MyPostgresTraceStore(TraceStore):
    async def create_trace(self, trace: Trace) -> str: ...
    async def add_step(self, step: Step) -> str: ...
    # ...
```

## 文档

- [设计文档](docs/design.md) - 详细的架构设计和决策
- [API 参考](docs/api.md) - 完整的 API 文档

## License

MIT