# Agent Core

**Agent 核心框架**：提供单个 Agent 的执行能力

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
1. **文档分层，链接代码** - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：`module/file.py:function_name`
2. **简洁快照，日志分离** - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议，或大量代码；决策依据或修改日志若有必要，可在`docs/decisions.md`另行记录

---

## 概述

Agent Core 是一个完整的 Agent 执行框架，提供：
- Trace、Message、Goal 管理
- 工具系统（文件、命令、网络、浏览器）
- LLM 集成（Gemini、OpenRouter、Yescode）
- Skills 和 Memory（跨会话知识）
- 子 Agent 机制

**独立性**：Agent Core 不依赖任何其他模块，可以独立运行。

---

## 模块结构

```
agent/
├── core/                  # 核心引擎
│   ├── runner.py          # AgentRunner + 运行时配置
│   └── presets.py         # Agent 预设（explore、analyst 等）
│
├── trace/                 # 执行追踪（含计划管理）
│   ├── models.py          # Trace, Message
│   ├── goal_models.py     # Goal, GoalTree, GoalStats
│   ├── protocols.py       # TraceStore 接口
│   ├── store.py           # FileSystemTraceStore 实现
│   ├── goal_tool.py       # goal 工具（计划管理）
│   ├── compaction.py      # Context 压缩
│   ├── api.py             # REST API
│   └── websocket.py       # WebSocket API
│
├── tools/                 # 外部交互工具
│   ├── registry.py        # 工具注册表
│   ├── schema.py          # Schema 生成器
│   ├── models.py          # ToolResult, ToolContext
│   └── builtin/
│       ├── file/          # 文件操作
│       ├── browser/       # 浏览器自动化
│       ├── bash.py        # 命令执行
│       ├── subagent.py    # 子 Agent 创建
│       └── a2a_im.py      # A2A IM 工具（桥接到 Gateway）
│
├── memory/                # 跨会话记忆
│   ├── models.py          # Experience, Skill
│   ├── stores.py          # 存储实现
│   ├── skill_loader.py    # Skill 加载器
│   └── skills/            # 内置 Skills
│
└── llm/                   # LLM 集成
    ├── gemini.py          # Gemini Provider
    ├── openrouter.py      # OpenRouter Provider
    └── yescode.py         # Yescode Provider
```

---

## 核心概念

### Trace（任务执行）

一次完整的 Agent 执行。所有 Agent（主、子、人类协助）都是 Trace。

**实现位置**：`agent/trace/models.py:Trace`

### Goal（目标节点）

计划中的一个目标，支持层级结构。

**实现位置**：`agent/trace/goal_models.py:Goal`

### Message（执行消息）

对应 LLM API 的消息，每条 Message 关联一个 Goal。

**实现位置**：`agent/trace/models.py:Message`

---

## 快速开始

### 基础使用

```python
from agent.core.runner import AgentRunner, RunConfig

# 创建 Runner
runner = AgentRunner(
    llm_call=create_llm_call(),
    trace_store=FileSystemTraceStore()
)

# 运行 Agent
async for item in runner.run(
    messages=[{"role": "user", "content": "分析项目架构"}],
    config=RunConfig(model="gpt-4o")
):
    if isinstance(item, Trace):
        print(f"Trace: {item.trace_id}")
    elif isinstance(item, Message):
        print(f"Message: {item.content}")
```

### 使用工具

```python
from agent.tools import tool, ToolContext, ToolResult

@tool(description="自定义工具")
async def my_tool(arg: str, ctx: ToolContext) -> ToolResult:
    return ToolResult(
        title="成功",
        output=f"处理结果: {arg}"
    )
```

---

## 文档

### 模块文档（agent/docs/）

- [架构设计](./docs/architecture.md)：Agent Core 完整架构设计
- [工具系统](./docs/tools.md)：工具定义、注册、双层记忆
- [Skills 指南](./docs/skills.md)：Skill 分类、编写、加载
- [Trace API](./docs/trace-api.md)：Trace 模块 REST API 和 WebSocket 接口
- [多模态支持](./docs/multimodal.md)：图片、PDF 处理
- [设计决策](./docs/decisions.md)：架构决策记录

### 项目级文档（../docs/）

- [项目总览](../docs/README.md)：完整的架构设计文档
- [A2A IM 系统](../docs/a2a-im.md)：Agent 间通讯
- [Enterprise 层](../gateway/docs/enterprise/overview.md)：组织级功能

---

## API

### REST API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET  | `/api/traces` | 列出 Traces |
| GET  | `/api/traces/{id}` | 获取 Trace 详情 |
| GET  | `/api/traces/{id}/messages` | 获取 Messages |
| POST | `/api/traces` | 新建 Trace 并执行 |
| POST | `/api/traces/{id}/run` | 续跑或回溯 |
| POST | `/api/traces/{id}/stop` | 停止运行 |

**实现位置**：`agent/trace/api.py`, `agent/trace/run_api.py`

---

## 相关项目

- [Gateway](../gateway/README.md)：A2A IM Gateway，提供 Agent 间通讯能力