四行代码，
一个带记忆的 Agent。
从 pip install 到第一个 Agent，只要四行；
往上走，工具、检索、RAG、多智能体、治理，一个包里逐层解锁。
这四行就是全部。更多能力，加几个参数就挂上。
六大组件，
一次 import。
下面所有能力都随核心 import 交付：import agentmaker。没有要注册的托管服务，也没有为追踪单独再装的包。
一个框架，四层结构。
每一层只依赖它下面那一层，绝不反向。你的应用依赖 agentmaker；agentmaker 依赖你的模型厂商和一个本地数据库，对你的业务一无所知。正是这个单一方向，让整个框架小到可以从头读到尾。
统一的模型-工具循环，以及构建在它之上的范式配方。
Harness 统筹所有横切工作：调用模型、在权限与审批门后执行工具、组装上下文、记录追踪。
带 schema 校验与渐进披露的工具、MCP 集成、工具检索，以及由模型自主调用的技能（Skill）。
LLM 统一入口与各协议适配器、混合检索核心、记忆、RAG 与上下文组装。
单向法则的意义在于杠杆。Harness 是协调者而非容器：护栏、权限、审批、限额、追踪都住在它旁边，被每个 Agent 直接复用。新增一种范式，这些横切能力自动免费到手。
这里没有任何需要你隔着距离去信任的插件：治理是一层你能翻开阅读的代码，后端是一个个可以整体替换的模块，数据面默认跑在本地 SQLite 上——直到你自己决定换掉它。
一个循环，四种范式。
Chat、ReAct、Plan-and-Solve、Reflection 不是四台各自独立的引擎。四者共享同一套「运行-恢复」模板——护栏、审批、限额与追踪，对每一种范式都同样生效。
纯对话，自带记忆
多轮纯对话，按 Scope 自动回读历史。
Agent("assistant", LLMClient("deepseek")).run("总结这段对话。")
推理、行动、观察，一个循环
注册工具后，模型在一个循环里交替进行推理、工具调用与观察。
Agent("assistant", LLMClient("deepseek"), tools=[CalculatorTool(), SearchTool()])
先计划，再执行
PlanAgent 运行 Plan-and-Solve：把任务拆成有序计划，逐步执行，最后综合出答案。
PlanAgent("planner", LLMClient("deepseek")).run(task)
起草、自评、修改
ReflectionAgent 起草、自我批评、迭代修改，直到评审认为无需再改或触到上限。带上工具，评审环节还能核查事实。
ReflectionAgent("writer", LLMClient("deepseek")).run(task)
值得信任的检索。
一套混合核心同时执行稠密与稀疏检索，按名次融合两路结果，可选再重排。同一套核心服务记忆、RAG 与工具检索，由 Scope 相互隔离——一个用户的记忆绝不会漏进另一个用户的结果。
流水线的每一级都可以整体替换：默认本地 SQLite 存向量、FTS5 做关键词，重排器可选 Cohere；实现对应接口，就能换上任意同类后端。Scope 让每个用户、每个会话的结果彼此隔离。
横向对比。
下面这些框架总体上比 agentmaker 更庞大、更久经实战，生态更大、生产里程更多。
agentmaker 只主张一件事：一个精简、可读、MIT 许可的核心，把检索、记忆、RAG 与治理全部装进单一 import。
| 维度 | agentmaker | LangChain / LangGraph | LlamaIndex | CrewAI | OpenAI Agents SDK | Pydantic AI |
|---|---|---|---|---|---|---|
| 核心抽象 | 单一统一的模型-工具循环 + 范式配方（Plan / Reflection / AgentTool） | 带持久状态的节点/边图（LangGraph）；其上是 create_agent + middleware 执行框架（LangChain） |
事件驱动、类型化的 Workflows，架在文档/RAG 数据面之上 | 基于角色的 crew（role/goal/backstory）+ Flows | 轻量的 Agents + Handoffs 原语 | 类型化 Agent（依赖注入 → 结构化输出）+ capabilities；Graph 可选 |
| 单 import 全栈 | YES：一句 import agentmaker 同时拿到 Agent + 工具 + 检索 + 记忆 + RAG + 上下文 + 治理 + 追踪 |
拆为 LangChain + LangGraph 与各集成包；追踪经独立的 LangSmith | 核心 + 大量 llama-index-* 附加包（如 OTel 可观测性包） |
基本一个包搞定 crew + 记忆；部分集成走 extras | 一个轻量 SDK；RAG 与长期记忆默认靠外部 | 模块化（pydantic-ai / -slim）；核心有 embeddings API，无向量库与长期记忆（Harness 附加包尚在孵化） |
| 内置混合检索 | YES：一套混合核心，向量 + 关键词以倒数排名融合（RRF）合并，可选重排，记忆/RAG/工具共用 | 内置 Retriever 接口；RRF 融合（EnsembleRetriever）现居遗留包 langchain-classic，或用向量库原生混合检索 |
YES：检索是其核心强项（RAG、混合检索器、重排） | 检索经由向量库支撑的 memory/knowledge 源；不是通用混合检索核心 | 不内置：托管 file-search 跑在 OpenAI 向量库上，框架内没有混合核心 | 不内置；自带方案接入（有网页搜索等 Common Tools） |
| 内置记忆 | YES：Mem0 式打分记忆（相关性、新近度、重要性）+ KVStore + MemoryTool | 内置短期（checkpointer）+ 长期（LangGraph Store），含原生语义检索；embedding 模型自备 | YES：核心 Memory 类 + 可插拔 memory blocks（静态 / 事实抽取 / 向量） |
YES：内置 Memory，复合打分（语义 · 新近度 · 重要性），默认 LanceDB；Mem0 可选 |
内置 Session（短期）记忆；长期/语义记忆靠外部 | 核心不含——靠依赖注入 / 消息历史；有 Anthropic 原生 MemoryTool（存储自备） |
| 内置治理 | YES：护栏、HITL 审批/恢复、RunPolicy 限额（调用数/token/时长）、按 Scope 的持久化检查点 | LangGraph 内置 HITL + 持久状态；LangChain 1.x 内置 middleware：HITL、PII、摘要、模型/工具调用限额 | 内置 HITL 工作流事件（InputRequired / HumanResponse）；护栏靠集成，无专门治理层 | Task 护栏（函数或 LLM 评审，带重试）+ Agent 限额（max_iter / max_rpm / max_execution_time） | YES：输入/输出 + 工具调用护栏；可选 OpenAI Guardrails 附加库；限额（max_turns）较轻量 | 输出校验（Pydantic）+ 工具审批 HITL；持久化执行（Temporal / DBOS / Prefect / Restate） |
| 可观测性 / 追踪 | YES：Tracer 自动脱敏密钥与敏感路径 + 导出器（内存/JSONL/SQLite/OpenTelemetry）随核心交付；可选 LLM「Trace Detective」诊断 | 经 LangSmith（独立产品）自动追踪图的 span | YES：内置 instrumentation 模块 + OTel 导出包 | 内置追踪，托管的 AMP Traces 界面（tracing=True）+ 事件总线；集成（Langfuse / OTel / Datadog） |
YES：内置追踪 + OpenAI Traces 面板 | YES：经 Pydantic Logfire（OpenTelemetry）；任意 OTel 后端均可（Logfire 为独立产品） |
| 可替换后端 | YES：五个后端接口（向量化器、向量库、关键词索引、重排器、融合策略）逐一可换；存储默认本地 SQLite，可插换为 pgvector 等 | YES：存储/embedding/重排器的集成生态极广 | YES：检索/存储/重排集成丰富 | 记忆：默认 LanceDB，可选 Qdrant，后端可插拔；知识：默认 ChromaDB，可选 Qdrant | 经 LiteLLM 模型无关（100+ 模型）；内置多种会话存储适配器；托管工具与 Traces 面板仍限 OpenAI | 模型无关；存储/记忆自备 |
核对时间：2026 年 7 月。
站在已发表的工作之上。
agentmaker 的关键机制都参考自已发表的研究。
Agent 推理与编排
Yao, Zhao, Yu, Du, Shafran, Narasimhan, Cao. "ReAct: Synergizing Reasoning and Acting in Language Models." ICLR 2023. arXiv:2210.03629.
PlanAgent 把任务拆成有序计划，再逐步执行与汇总。Wang, Xu, Lan, Hu, Lan, Lee, Lim. "Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models." ACL 2023, pp. 2609 to 2634. arXiv:2305.04091.
ReflectionAgent 起草、自评，并在重试中修改。Shinn, Cassano, Gopinath, Narasimhan, Yao. "Reflexion: Language Agents with Verbal Reinforcement Learning." NeurIPS 2023. arXiv:2303.11366.
Schick, Dwivedi-Yu, Dessì, Raileanu, Lomeli, Hambro, Zettlemoyer, Cancedda, Scialom. "Toolformer: Language Models Can Teach Themselves to Use Tools." NeurIPS 2023. arXiv:2302.04761.
上下文组装与记忆
mmr_select 为组装好的上下文去重，在相关与多样之间取得平衡。Carbonell, Goldstein. "The Use of MMR, Diversity-Based Reranking for Reordering Documents and Producing Summaries." SIGIR 1998, pp. 335 to 336.
Memory.search 按相关性、新近度、重要性为召回打分。Park, O'Brien, Cai, Morris, Liang, Bernstein. "Generative Agents: Interactive Simulacra of Human Behavior." UIST 2023. arXiv:2304.03442.
SmartWriter 对照既有记忆调和写入：新增、更新或删除事实。Chhikara, Khant, Aryan, Singh, Yadav. "Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory." 2025. arXiv:2504.19413.
检索与融合
rag/ 模块端到端地让生成扎根于检索到的文档。Lewis, Perez, Piktus, Petroni, Karpukhin, Goyal, Küttler, Lewis, Yih, Rocktäschel, Riedel, Kiela. "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks." NeurIPS 2020, pp. 9459 to 9474. arXiv:2005.11401.
Fts5KeywordIndex 以 SQLite FTS5 的 BM25 排序作为关键词路径。Robertson, Zaragoza. "The Probabilistic Relevance Framework: BM25 and Beyond." Foundations and Trends in Information Retrieval, Vol. 3, No. 4 (2009), pp. 333 to 389.
Embedder 与 VectorStore 两个接口把查询与文段嵌入同一空间。Karpukhin, Oğuz, Min, Lewis, Wu, Edunov, Chen, Yih. "Dense Passage Retrieval for Open-Domain Question Answering." EMNLP 2020, pp. 6769 to 6781. arXiv:2004.04906.
reciprocal_rank_fusion 按名次合并稠密与关键词两路结果，k = 60。Cormack, Clarke, Büttcher. "Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods." SIGIR 2009, pp. 758 to 759.
HyDETransformer 用一个假设答案作为检索查询进行嵌入。Gao, Ma, Lin, Callan. "Precise Zero-Shot Dense Retrieval without Relevance Labels." ACL 2023. arXiv:2212.10496.
LLMContextualizer 与 HeadingContextualizer 在建索引前为每个分块补上其上下文。Anthropic. "Introducing Contextual Retrieval." Anthropic engineering blog, September 19, 2024.
协议
tools/integrations/mcp.py 通过官方 SDK 加载任意 MCP 服务器的工具。Anthropic. "Introducing the Model Context Protocol." Anthropic news, November 25, 2024. Spec: modelcontextprotocol.io.
核对时间：2026 年 7 月。