agent-builder

Agent 构建器

为任何领域构建 AI Agent——客户服务、研究、运营、创意工作或专业业务流程。

适用性

架构和编排指南不依赖特定提供商。目前附带的 Python 入门代码使用 Anthropic SDK 和 Anthropic 模型配置；使用其他提供商时，请调整实现层。不要误以为示例客户端代表了必需的 Agent 架构。

核心理念

模型已经知道如何成为 Agent。你要做的就是别妨碍它。

Agent 并不需要复杂的工程实现。它只是一个鼓励模型采取行动的简单循环：

LOOP:
  Model sees: context + available capabilities
  Model decides: act or respond
  If act: execute capability, add result, continue
  If respond: return to user

就是这样。 神奇之处不在代码里，而在模型里。你的代码只是提供了实现的机会。

三大要素

1. 能力（它能做什么？）

Agent 可以执行的原子操作：搜索、读取、创建、发送、查询、修改。

设计原则：从 3-5 项能力开始。只有当 Agent 因缺少某项能力而持续失败时，才添加更多能力。

2. 知识（它知道什么？）

按需注入的领域专业知识：政策、工作流、最佳实践、架构。

设计原则：让知识可供使用，而非强制使用。在相关时加载，而不是一开始就全部加载。

3. 上下文（发生了什么？）

对话历史——将各项操作串联起来，形成连贯行为的线索。

设计原则：上下文很宝贵。隔离嘈杂的子任务。截断冗长的输出。保持清晰。

Agent 设计思路

构建之前，先了解以下内容：

• 目标：这个 Agent 应该完成什么？
• 领域：它在哪个领域运作？（客户服务、研究、运营、创意工作……）
• 能力：哪些 3-5 项操作是必不可少的？
• 知识：它需要获取哪些专业知识？
• 信任：哪些决策可以交由模型处理？

重要：相信模型。不要过度设计。不要预先规定工作流。赋予它能力，让它自行推理。

渐进式复杂度

从简单开始。只有在实际使用中发现需求时，才增加复杂度：

级别	添加内容	添加时机
基础	3-5 项能力	始终从这里开始
规划	进度跟踪	多步骤任务失去连贯性时
子 Agent	隔离的子 Agent	探索过程污染上下文时
技能	按需提供知识	需要领域专业知识时

大多数 Agent 无需超越第 2 级。

领域示例

商业：CRM 查询、电子邮件、日历、审批
研究：数据库搜索、文档分析、引用
运营：监控、工单、通知、升级处理
创意：素材生成、编辑、协作、审阅

这种模式具有普适性。变化的只有能力。

核心原则

1. 模型就是 Agent——代码只负责运行循环
2. 能力赋予行动力——它能做什么
3. 知识提供指导——它知道如何做什么
4. 约束聚焦目标——限制带来清晰度
5. 信任释放潜力——让模型自行推理
6. 迭代揭示需求——从精简版本开始，根据使用情况逐步发展

反模式

模式	问题	解决方案
过度设计	尚无需求就增加复杂度	从简单开始
能力过多	让模型困惑	从 3-5 项开始
僵化的工作流	无法适应变化	让模型自行决定
一开始就加载过多知识	上下文臃肿	按需加载
事无巨细地管理	削弱智能	相信模型

资源路由

仅加载当前任务所需的内容：

用户需求	资源	不要在以下情况加载
理解或讨论架构	references/agent-philosophy.md	用户只需要可运行的入门代码
检查最小完整循环	references/minimal-agent.py	任务是概念性的，或与提供方无关
添加或调整单项能力	references/tool-templates.py	未要求实现
设计上下文隔离的子 Agent	references/subagent-pattern.py	单 Agent 循环已足够
生成本地 Python 入门项目	scripts/init_agent.py	用户只要求设计建议

这些 Python 资源是用于学习的示例，并非安全边界。其 shell 能力默认需要用户批准；生产系统仍需根据其威胁模型采取隔离、最小权限、审计日志和适当的策略。

Agent 思维方式

从：「如何让系统执行 X？」 转变为：「如何让模型能够执行 X？」

从：「这项任务的工作流是什么？」 转变为：「哪些能力有助于完成这项任务？」

最好的 Agent 代码往往平淡无奇：简单的循环、明确的能力、干净的上下文。神奇之处不在代码里。

赋予模型能力和知识。相信它能自行解决剩下的问题。