agent2

# Agent2  **将领域专家转化为生产级AI智能体** 不仅仅是他们的思考方式 — 而是他们的工作方式。工具、书籍、记忆、判断。 ## 快速开始 预期流程如下： ```bash curl -fsSL https://getagent2.dev/install.sh | bash agent2 onboard ``` 托管的 `getagent2.dev` 脚本是一个部署目标。仓库中已经包含本地安装程序： ```bash git clone https://github.com/duozokker/agent2.git cd agent2 scripts/install.sh agent2 onboard ``` 这会执行三个操作： - `agent2 setup` 编写 `.env` 和 `agent2.yaml`，选择模型，配置 Docker 配置文件和遥测，并备份现有的配置文件，然后替换它们。 - `agent2 onboard` 运行 Brain Clone 入职流程。LLM 可能有助于将面试塑造成 `AgentSpec`，但只有确定性的 Python 模板才能写入文件。 - `agent2 doctor` 检查 Docker、uv、配置文件、组合有效性、端口和本地健康端点。 您也可以手动运行这些步骤： ```bash uv sync --extra dev uv run agent2 setup uv run agent2 onboard uv run agent2 doctor ``` 用于从已检查的规范进行非交互式生成的命令： ```bash uv run agent2 onboard --from-spec tests/fixtures/roofing-agent-spec.json --no-llm uv run agent2 serve roofing-field-advisor ``` 现在，您的专家已经成为一个本地的 Agent2 API。身份验证、类型化输出、知识搜索、内存、人工审批、模拟模式和 Docker 连接都已生成。 在您想要扩展生成的智能体时，可以在 Claude Code、Codex、Cursor、OpenCode 或其他 AI 编码工具中打开仓库。`AGENTS.md`、`llms.txt` 和 `.claude/skills`、`.codex/skills`、`.gemini/skills` 和 `.github/skills` 中的技能教导编码智能体 Agent2 模式。 --- ## Agent2 的功能 每家公司都有领域专家，他们的知识被困在自己的脑海中。会计师知道使用哪个 DATEV 账户。律师发现了风险条款。合规官发现了违规行为。 Agent2 将他们整个工作场所克隆到一个 AI 智能体中： ``` 我们克隆的内容 如何 ───────────────────────────────────────────────────────── 专家如何思考 Sachbearbeiter Chain-of-Thought 提示 专家使用的工具 工具集成（数据库、电子邮件、查找） 专家阅读的书籍 知识搜索（R2R 集合） 专家记住的内容 会话之间的持久内存 专家寻求帮助时 暂停/恢复 + 澄清问题 需要审批的内容 沙盒工具 + 人工审批 专家生成的内容 Pydantic 验证的类型输出 ``` 结果是一个生产级的 HTTP 服务 — 不是聊天机器人，不是提示包装器。一个您可以调用一百万次的 类型化 API。 --- ## 功能矩阵 | 功能 | 功能描述 | 示例智能体 | 文档 | |---|---|---|---| | **完整的 Brain Clone 模式** | 专家工作空间、书籍、记忆、审批、恢复、评估 | [procurement-compliance-officer](./agents/procurement-compliance-officer) | [Brain Clone 模式](./docs/brain-clone-pattern.md) | | **类型化输出** | Pydantic 模型作为 `output_type`，验证失败时自动重试 | [support-ticket](./agents/support-ticket) | [创建智能体](./docs/creating-agents.md) | | **同步 + 异步执行** | `mode=sync` 用于内联，`mode=async` 用于带轮询的队列工作 | [invoice](./agents/invoice) | [快速入门](./docs/getting-started.md) | | **暂停/恢复** | 序列化的 `message_history` 用于多轮对话 | [resume-demo](./agents/resume-demo) | [恢复](./docs/resume-conversations.md) | | **人工审批** | `pending_actions` + 主机驱动的执行 | [approval-demo](./agents/approval-demo) | [审批](./docs/approvals.md) | | **提供商路由** | `provider_order` + `provider_policy` 用于缓存感知路由 | [provider-policy-demo](./agents/provider-policy-demo) | [提供商策略](./docs/provider-policy.md) | | **工具范围** | 按运行的工具拦截和集合筛选 | [scoped-tools-demo](./agents/scoped-tools-demo) | [功能](./docs/capabilities.md) | | **知识搜索** | R2R + FastMCP 用于共享文档集合 | [rag-test](./agents/rag-test) | [知识](./docs/knowledge-management.md) | | **可观察性** | Langfuse 跟踪、提示管理、成本跟踪 | — | [可观察性](./docs/observability.md) | | **模拟模式** | 无 LLM 密钥的全 API — 返回符合模式的模拟数据 | [code-review](./agents/code-review) | [快速入门](./docs/getting-started.md) | --- ## 手动构建您的第一个智能体 大多数用户应该从 `agent2 onboard` 开始。当您已经了解框架内部时，手动脚手架非常有用。 ### 1. 复制模板 ```bash cp -r agents/_template agents/my-agent ``` ### 2. 定义输出 ```python # agents/my-agent/schemas.py from pydantic import BaseModel, Field class InvoiceSummary(BaseModel): vendor: str = Field(description="供应商名称") total: float = Field(gt=0, description="总金额，欧元") account_code: str = Field(description="建议的记账账户") confidence: float = Field(ge=0.0, le=1.0) ``` ### 3. 创建智能体 ```python # agents/my-agent/agent.py from shared.runtime import create_agent from .schemas import InvoiceSummary agent = create_agent( name="my-agent", output_type=InvoiceSummary, instructions=( "您是一位拥有 20 年经验的会计师。 " "当您收到发票时，请逐步思考： " "这是什么类型的文档？ 检查客户文件。 " "验证正式要求。 查找正确的账户。 " "如果有不清楚的地方，请询问。" ), ) @agent.tool_plain def lookup_vendor(name: str) -> dict: """检查该供应商是否在我们的数据库中。""" return {"known": True, "default_account": "6805"} ``` ### 4. 暴露 API ```python # agents/my-agent/main.py from shared.api import create_app app = create_app("my-agent") ``` 就这样。您的智能体现在拥有一个生产级的 HTTP API，支持身份验证、速率限制、结构化输出、异步执行和错误处理。 --- ## 为什么不是 X？ | 替代方案 | 解决了什么问题 | Agent2 添加了什么 | |---|---|---| | **“您是专家”提示** | 系统提示 | 完整的专家：Sachbearbeiter Chain-of-Thought 提示、工具、知识搜索、记忆、人工审批、类型化输出和验证 | | **单独的 PydanticAI** | 智能体循环、结构化输出、工具调用 | 生产运行时：HTTP API、身份验证、异步队列、暂停/恢复、审批、提供商路由 | | **LangChain / LangServe** | 提示编排、链条组合 | 面向任务的执行（非对话式） 、类型化输出强制执行、审批工作流 | | **CrewAI / AutoGen** | 多智能体协调 | 单智能体生产部署 — 一个智能体、一个模式、一个端点。 如果需要多智能体，请编排多个 Agent2 服务 | | **OpenClaw** | 您笔记本上的个人 AI 智能体 | 企业后端智能体 — 可 HTTP 调用、多租户、类型化输出、可在任何容器平台上扩展 | | **自己构建** | 完全控制 | 您跳过编写 ~3000 LOC 的框架代码：身份验证、错误处理、异步队列、消息历史记录序列化、审批工作流、提供商路由、模拟模式、双布局检测 | --- ## 技术栈 Agent2 贴近生态系统，而不是重新发明它： | 层 | 技术 | 为什么 | |---|---|---| | 智能体运行时 | [PydanticAI](https://ai.pydantic.dev/) | 结构化输出、工具使用、重试、模型无关 | | HTTP API | [FastAPI](https://fastapi.tiangolo.com/) | 身份验证、速率限制、异步、OpenAPI 文档 | | LLM 提供商 | [OpenRouter](https://openrouter.ai/) | 任意模型 — Claude、Gemini、GPT、Llama — 一个 API 密钥 | | 知识搜索 | [R2R](https://github.com/SciPhi-AI/R2R) + [FastMCP](https://github.com/jlowin/fastmcp) | 文档摄入、混合搜索、通过 MCP 重新排序 | | OCR | [Docling](https://github.com/docling-project/docling) | PDF 提取、表格识别、布局分析 | | 可观察性 | [Langfuse](https://langfuse.com/) | 跟踪、提示注册、成本跟踪、评估 | | 评估测试 | [Promptfoo](https://promptfoo.dev/) | 智能体行为的预部署回归测试 | | 任务队列 | Redis | 异步任务状态、轮询 | | 基础设施 | Postgres、ClickHouse、MinIO | R2R 存储、Langfuse 后端 | --- ## 默认 vs. 完整栈 **默认**（`docker compose up -d`）— 快速开发者循环： - Postgres、Redis、Langfuse - example-agent、support-ticket、code-review、invoice、approval-demo、resume-demo、provider-policy-demo **完整**（`docker compose --profile full up -d`）— 完整的平台： - 上面的所有内容 + R2R、Docling、Temporal、Knowledge MCP - rag-test、scoped-tools-demo、procurement-compliance-officer --- ## 文档 | 主题 | 链接 | |---|---| | 架构 | [docs/architecture.md](./docs/architecture.md) | | CLI 入职 | [docs/cli-onboarding.md](./docs/cli-onboarding.md) | | Brain Clone 模式 | [docs/brain-clone-pattern.md](./docs/brain-clone-pattern.md) | | Sachbearbeiter 参考模式 | [docs/reference-agents/sachbearbeiter-pattern.md](./docs/reference-agents/sachbearbeiter-pattern.md) | | 快速入门 | [docs/getting-started.md](./docs/getting-started.md) | | 创建智能体 | [docs/creating-agents.md](./docs/creating-agents.md) | | 功能 | [docs/capabilities.md](./docs/capabilities.md) | | 恢复和对话 | [docs/resume-conversations.md](./docs/resume-conversations.md) | | 审批 | [docs/approvals.md](./docs/approvals.md) | | 提供商策略 | [docs/provider-policy.md](./docs/provider-policy.md) | | 知识管理 | [docs/knowledge-management.md](./docs/knowledge-management.md) | | 可观察性 | [docs/observability.md](./docs/observability.md) | | 部署和扩展 | [docs/deployment.md](./docs/deployment.md) | | 何时使用 Agent2 | [docs/comparison.md](./docs/comparison.md) | --- ## AI 辅助开发 Agent2 配备了用于 AI 编码工具的内置技能。 在 Claude Code、Cursor、Codex 或 Gemini CLI 中打开此仓库，您的智能体已经知道如何使用框架。 | 技能 | 功能描述 | 触发器 | |---|---|---| | **brain-clone** | 交互式访谈，提取专家知识并生成完整的智能体 | "brain clone", "clone expert", "create domain expert" | | **creating-agents** | 脚手架一个完整的智能体服务 | "new agent", "scaffold agent" | | **building-domain-experts** | 知识支持的文档处理智能体模式 | "expert agent", "document processing" | | **adding-knowledge** | R2R 集合、摄入、按租户划分的知识范围 | "add knowledge", "add books", "RAG" | | **adding-capabilities** | 暂停/恢复、审批、提供商路由、工具范围 | "add resume", "add approval" | | **debugging-agents** | 框架问题的系统诊断 | "agent doesn't work", "500 error" | 技能遵循 [开放的 SKILL.md 标准](https://agents.md/)，并可在 `.claude/skills/`、`.codex/skills/`、`.gemini/skills/` 和 `.github/skills/` 下找到。 --- ## 设计原则 - **框架代码位于 `shared/` 下。** 产品逻辑位于智能体模块中。 - **功能按需选择。** 暂停/恢复、审批、知识、工具范围 — 使用您需要的功能。 - **提示优先采用代码优先的方式。** Langfuse 是可选的，用于迭代和可观察性，而不是必需的。 - **错误采用 RFC 7807 格式。** 每个失败都返回 `application/problem+json`。 - **无锁定。** 标准的 Python、标准的 Docker、标准的 FastAPI。 任意部署。 --- ## 状态 Agent2 提供了生产测试的基元，用于将领域专业知识转化为 AI 智能体 — 源自为德国税务公司处理数百万文档的实际企业工作。 当前版本：**v0.4.0**（Brain Clone 流水线升级、学习系统、单一事实来源） ### 已有功能 - 使用 `create_agent()` 创建类型化的智能体 - 使用 `create_app()` 构建完整的 HTTP API - 同步和异步任务执行 - 带有序列化消息历史记录的暂停/恢复 - 人工审批工作流 - 提供商感知执行，带有缓存路由 - 工具拦截和集合范围 - 无 LLM 密钥的模拟模式 - 56 个单元测试，涵盖框架基元和入职流程 - GitHub Actions CI，包含 lint + test + Docker 验证 - 5 个用于 AI 编码工具的内置技能（Claude Code、Codex、Gemini CLI、Copilot） ### 路线图 - [ ] PyPI 包（`pip install agent2`） - [ ] Agent2 Cloud（托管托管 + 仪表盘） - [x] 用于设置、入职、诊断和生成的智能体检查的 CLI - [ ] 非技术领域专家的 Agent2 Studio UI - [ ] 多智能体编排基元 - [ ] 长运行任务的 WebSocket 流式传输 - [ ] 社区智能体模板的插件系统 - [ ] Brain Clone 市场（预建的专家模板） - [ ] 领域专家访谈 UI --- ## 由 Artesiana 构建 Agent2 源自 [Artesiana](https://artesiana.de) 的生产工作，我们在那里将领域专业知识转化为 AI 智能体。 该框架已经处理了 400 万+ 文档，并产生了 16 万+ 欧元的收入，自 2025 年 9 月以来。 我们开源核心，因为我们相信领域专家克隆的基础设施应该是一个共享的基础，而不是专有的护城河。 --- ## 使用 Agent2 构建 ### MandantLink — 税务公司的自主发票处理 [MandantLink](https://mandantlink.de) 将一位 20 年的会计师专家的专业知识转化为一个 AI 智能体，该智能体端到端处理发票：OCR → 知识支持的分析 → 澄清问题 → 人工审批 → DATEV 导出。 使用 Agent2 的专家克隆模式构建。 > **您是否使用 Agent2 构建了某些东西？** 打开一个 PR 将您的项目添加到此处。 ## 许可证 [MIT](./LICENSE)