agent-builder

Agent 构建器

为任何领域构建 AI 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 - 深入探讨 Agent 为何有效

实现：

• references/minimal-agent.py - 完整可运行的 Agent（约 80 行）
• references/tool-templates.py - 能力定义
• references/subagent-pattern.py - 上下文隔离

脚手架：

• scripts/init_agent.py - 生成新的 Agent 项目

Agent 思维方式

从：“我如何让系统执行 X？” 转变为：“我如何让模型能够执行 X？”

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

最好的 Agent 代码几乎平淡无奇。简单的循环。清晰的能力。干净的上下文。神奇之处不在代码里。

赋予模型能力和知识。相信它能自行解决其余问题。