Agent

Reson Agent

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

Quick Start

pip install -r requirements.txt

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

最小示例

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 可用，无需额外配置。

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 会生成：

{
  "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"]
    }
  }
}

限制工具范围

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

自定义 Skills

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

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

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

## Guidelines
- 规则 1
- 规则 2

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

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

经验系统（Experience System）

经验系统通过提取、注入、反馈、更新四个环节，让 Agent 从历史执行中学习并持续改进。

核心流程

1. 提取（Extract）

• 触发时机：Level 2 压缩时自动触发
• 提取方式：在压缩历史消息前，先调用 LLM 对当前执行过程进行反思（reflect）

• 输出格式：ACE 规范经验条目

  当 [条件/Context] 时，应该 [动作/Action]（原因：[逻辑/Reason]）
  

• 存储位置：追加到 experiences.md 文件（默认 ./.cache/experiences.md）

2. 注入（Inject）

• 触发时机：切换 Goal 时自动触发
• 检索策略：两阶段检索
  • Stage 1: 语义路由（LLM 挑选 2*k 个相关经验）
  • Stage 2: 质量精排（根据 metrics 筛选最终 k 个）
• 注入方式：将检索到的经验注入到主 Agent 的上下文中

3. 反馈（Feedback）

• 触发时机：压缩时分析历史消息中经验的使用效果
• 评价维度：
  • helpful: 经验有效，帮助完成任务
  • harmful: 经验误导，导致错误
  • mixed: 部分有效，需要改进
• 反馈来源：LLM 分析执行过程中经验的实际效果

4. 更新（Update）

• Metrics 更新：根据反馈调整 helpful 和 harmful 计数
• 内容进化：
  • helpful + 有改进建议 → 触发经验重写（evolve）
  • harmful 累积 → 降低检索权重或标记为有害
• 质量过滤：检索时自动过滤 quality_score < -2 的有害经验

经验文件格式

---
id: ex_02271430_a3f2
trace_id: 6822d4e0-8aeb-449f-962e-c431c409a5a0
tags: {intent: [解构, 图片分析], state: [多图]}
metrics: {helpful: 3, harmful: 0}
created_at: 2026-02-27 14:30:15
updated_at: 2026-02-27 15:20:42
---
当需要分析多张图片时，应该先并行读取所有图片再统一分析（原因：避免重复调用 LLM，节省 token 和时间）。

经验库瘦身

experience.py 中提供 slim_experiences() 函数，可调用顶级 LLM 合并语义相似的经验，减少冗余。

功能：

• 识别并合并语义高度相似的经验
• 保留 helpful 最高的 ID
• 合并 metrics（helpful/harmful 取各条之和）
• 保持 ACE 规范格式

状态：已实现但暂未自动调用，可在 analyze_story/run.py 的交互菜单中手动触发（选项 7）。

配置

runner = AgentRunner(
    llm_call=...,
    trace_store=...,
    experiences_path="./.cache/experiences.md",  # 自定义经验文件路径
)

AgentRunner 参数

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 参数

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：

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 只需实现签名：

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

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