Omni Agent

# Omni Agent

一个功能完整的 AI Agent 系统，基于 FastAPI 构建

## 核心特性

### 基础能力
- **FastAPI Web API**: 生产级 RESTful API，支持 OpenAPI 文档
- **工具执行**: 文件操作（读/写/编辑）、Bash 命令、Skills 调用
- **多模型支持**: 通过 LiteLLM 支持 100+ LLM 提供商，智能适配参数限制
  - Anthropic Claude, OpenAI GPT-4, xAI Grok, DeepSeek, Qwen
  - 自动模型名称标准化 (provider/model 格式)
  - 自动调整 max_tokens 到提供商限制
- **完整执行循环**: Agent 自动执行多步任务直到完成

### 高级功能
- **Token 管理**: 使用 tiktoken 精确计算 token，防止上下文溢出
- **自动消息总结**: 超过 token 限制时自动压缩历史消息
- **AgentLogger 日志系统**: 结构化 JSON 日志，完整追踪执行过程
- **MCP 集成**: 支持 Model Context Protocol，扩展外部工具能力
- **Skills 系统**: 内置专业 Skills，提供领域专家级指导
- **流式输出**: 支持 Server-Sent Events (SSE) 实时流式响应
- **会话记忆**: 使用 NoteTool 自动管理长期记忆和会话上下文
- **多后端 Session 存储**: 支持 File/Redis/PostgreSQL 三种存储后端
- **Web 前端**: ChatGPT 风格的 React 前端界面
- **人工确认机制**: Agent 可主动请求用户补充信息或确认敏感操作

### 多 Agent 协作
- **SpawnAgentTool**: 动态创建子 Agent 执行委派任务（类似 Claude Code Task 工具）
- **Team 系统**: Leader-Member 多 Agent 协作，支持智能任务委派
- **Graph 执行引擎**: LangGraph 风格的声明式工作流定义，支持并行执行、条件路由、状态 Reducer
- **RAG 知识库**: 混合检索（语义+关键词），基于 PostgreSQL + pgvector
- **Sandbox 沙箱隔离**: 基于 agent-sandbox，每个 Session 独立沙箱，安全执行不受信任代码
- **ACP 协议支持**: 实现 Zed Agent Client Protocol，支持代码编辑器集成

### 场景路由
- **自动场景识别**: 根据用户输入自动识别任务类型（代码开发、旅行规划、信息检索等）
- **动态工具选择**: 按场景自动配置最优工具集，减少不必要的 token 消耗
- **工具预设系统**: 预定义工具集（minimal/coding/research/travel/full）
- **工具分组管理**: 按类别组织工具（file_ops/code_tools/search_tools/maps_tools等）
- **系统提示适配**: 根据场景注入专业化的系统提示前缀
- **执行模式选择**: 自动选择 SingleAgent 或 Team 模式

### 性能与监控
- **Langfuse 可观测性**: 生产级 LLM 追踪，支持 Agent 执行流程、工具调用、Token 成本统计
- **执行时间追踪**: 精确记录每个工具的执行时间（毫秒级）
- **Token 使用监控**: 实时追踪 token 使用情况和百分比
- **独立日志文件**: 每次运行生成时间戳日志，便于调试和审计
- **TraceLogger 追踪系统**: 多 Agent 工作流追踪，支持委派链路、依赖关系可视化

## 项目结构

```
skill-agent/
├── src/
│   └── omni_agent/          # 主要代码
│       ├── main.py             # FastAPI 应用入口
│       ├── api/                # API 路由层
│       │   ├── deps.py         # 依赖注入（MCP/Session/AgentFactory）
│       │   └── v1/
│       │       ├── endpoints/
│       │       │   ├── agent.py    # Agent 端点（含流式）
│       │       │   ├── team.py     # Team 多 Agent 协作端点
│       │       │   ├── knowledge.py # RAG 知识库端点
│       │       │   └── tools.py    # 工具列表端点
│       │       └── router.py   # 主路由
│       ├── core/               # 核心组件
│       │   ├── agent.py        # Agent 核心 (含 State/Event/Hook/Loop)
│       │   ├── team.py         # Team 多 Agent 协作
│       │   ├── graph.py        # Graph 执行引擎（LangGraph 风格）
│       │   ├── agent_node.py   # AgentNode/ToolNode 封装
│       │   ├── agent_logger.py # 结构化日志系统
│       │   ├── llm_client.py   # LLM 客户端（含流式）
│       │   ├── config.py       # 配置管理
│       │   ├── scene.py            # 场景类型和配置
│       │   ├── scene_registry.py   # 预定义场景配置
│       │   ├── scene_router.py     # 场景路由器
│       │   ├── tool_groups.py      # 工具分组与预设
│       │   ├── token_manager.py    # Token 管理与消息总结
│       │   ├── file_memory.py      # AGENTS.md 文件记忆系统
│       │   ├── session.py          # Session 数据模型
│       │   ├── session_storage.py  # 存储后端抽象层
│       │   ├── session_manager.py  # 统一 Session 管理器
│       │   ├── langfuse_tracing.py # Langfuse 可观测性集成
│       │   ├── prompt_builder.py   # 结构化 Prompt 构建
│       │   ├── checkpoint.py       # 执行状态检查点
│       │   └── trace_logger.py     # 多 Agent 工作流追踪
│       ├── tools/              # 工具实现
│       │   ├── base.py         # 工具基类
│       │   ├── file_tools.py   # 文件操作
│       │   ├── bash_tool.py    # Bash 执行
│       │   ├── note_tool.py    # 会话记忆管理
│       │   ├── spawn_agent_tool.py # 子 Agent 动态创建
│       │   └── rag_tool.py     # RAG 知识库搜索
│       ├── rag/                # RAG 知识库
│       │   ├── database.py     # PostgreSQL + pgvector
│       │   ├── embedding_service.py # 向量嵌入服务
│       │   ├── document_processor.py # 文档处理
│       │   └── rag_service.py  # RAG 服务层
│       ├── sandbox/            # 沙箱隔离执行
│       │   ├── manager.py      # 沙箱生命周期管理
│       │   ├── toolkit.py      # 沙箱工具集工厂
│       │   └── tools.py        # 沙箱版工具实现
│       ├── skills/             # Skills 系统
│       │   ├── skill_tool.py   # Skill 工具实现
│       │   └── ...             # 内置 Skills
│       ├── utils/              # 工具类
│       │   └── trace_viewer.py # 追踪日志查看器
│       └── schemas/            # Pydantic 数据模型
│           ├── message.py      # Agent 请求/响应
│           └── team.py         # Team 请求/响应
├── frontend/                   # React Web 前端 (Vite + TailwindCSS)
├── tests/                      # 测试套件
├── skills/                     # 外部 Skills 定义
├── workspace/                  # Agent 工作目录
├── mcp.json.example            # MCP 服务器配置示例
├── docs/                       # 文档
│   └── TRACING_GUIDE.md        # 追踪系统使用指南
└── pyproject.toml              # 项目配置（uv）
```

## 快速开始

### 1. 安装 uv

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. 安装项目依赖

```bash
uv sync
```

### 3. 配置环境变量

创建 `.env` 文件：

```bash
# LLM 配置 (支持 100+ 提供商)
LLM_API_KEY=your_api_key_here
LLM_API_BASE=  # 留空使用默认端

... (truncated)