agent-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Builder

Agent构建器

Build AI agents for any domain - customer service, research, operations, creative work, or specialized business processes.

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

The Core Philosophy

核心理念

The model already knows how to be an agent. Your job is to get out of the way.

An agent is not complex engineering. It's a simple loop that invites the model to act:

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

That's it. The magic isn't in the code - it's in the model. Your code just provides the opportunity.

模型本身就具备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

就是这么简单。 魔力不在于代码——而在于模型本身。你的代码只是提供了实现的机会。

The Three Elements

三大要素

1. Capabilities (What can it DO?)

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

Atomic actions the agent can perform: search, read, create, send, query, modify.

Design principle: Start with 3-5 capabilities. Add more only when the agent consistently fails because a capability is missing.

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

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

2. Knowledge (What does it KNOW?)

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

Domain expertise injected on-demand: policies, workflows, best practices, schemas.

Design principle: Make knowledge available, not mandatory. Load it when relevant, not upfront.

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

设计原则：让知识可用，但不强制要求。仅在相关时加载，而非预先加载。

3. Context (What has happened?)

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

The conversation history - the thread connecting actions into coherent behavior.

Design principle: Context is precious. Isolate noisy subtasks. Truncate verbose outputs. Protect clarity.

对话历史——将行动连接成连贯行为的线索。

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

Agent Design Thinking

Agent设计思路

Before building, understand:

Purpose: What should this agent accomplish?
Domain: What world does it operate in? (customer service, research, operations, creative...)
Capabilities: What 3-5 actions are essential?
Knowledge: What expertise does it need access to?
Trust: What decisions can you delegate to the model?

CRITICAL: Trust the model. Don't over-engineer. Don't pre-specify workflows. Give it capabilities and let it reason.

在构建之前，先明确：

目标：这个Agent应该完成什么任务？
领域：它运行在什么场景下？（客户服务、研究、运营、创意……）
能力：哪3-5项行动是必不可少的？
知识：它需要访问哪些专业知识？
信任：你可以将哪些决策委托给模型？

关键提示：信任模型。不要过度设计。不要预先指定工作流。赋予它能力，让它自主推理。

Progressive Complexity

渐进式复杂度

Start simple. Add complexity only when real usage reveals the need:

Level	What to add	When to add it
Basic	3-5 capabilities	Always start here
Planning	Progress tracking	Multi-step tasks lose coherence
Subagents	Isolated child agents	Exploration pollutes context
Skills	On-demand knowledge	Domain expertise needed

Most agents never need to go beyond Level 2.

从简单开始。仅当实际使用中显露出需求时，再增加复杂度：

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

大多数Agent永远不需要超过第2层级。

Domain Examples

领域示例

Business: CRM queries, email, calendar, approvals Research: Database search, document analysis, citations Operations: Monitoring, tickets, notifications, escalation Creative: Asset generation, editing, collaboration, review

The pattern is universal. Only the capabilities change.

业务领域：CRM查询、邮件、日历、审批 研究领域：数据库搜索、文档分析、引用 运营领域：监控、工单、通知、升级处理 创意领域：资产生成、编辑、协作、审核

模式是通用的。只有能力会因领域而异。

Key Principles

核心原则

The model IS the agent - Code just runs the loop
Capabilities enable - What it CAN do
Knowledge informs - What it KNOWS how to do
Constraints focus - Limits create clarity
Trust liberates - Let the model reason
Iteration reveals - Start minimal, evolve from usage

模型即Agent——代码只是运行循环
能力赋能——它能做什么
知识赋能——它知道如何做
约束聚焦——限制创造清晰度
信任释放——让模型自主推理
迭代优化——从最简版本开始，根据使用情况演进

Anti-Patterns

反模式

Pattern	Problem	Solution
Over-engineering	Complexity before need	Start simple
Too many capabilities	Model confusion	3-5 to start
Rigid workflows	Can't adapt	Let model decide
Front-loaded knowledge	Context bloat	Load on-demand
Micromanagement	Undercuts intelligence	Trust the model

模式	问题	解决方案
过度设计	在有需求之前就增加复杂度	从简单开始
能力过多	导致模型困惑	从3-5项能力开始
僵化工作流	无法适应变化	让模型自主决策
预先加载知识	导致上下文膨胀	按需加载
微观管理	削弱模型智能	信任模型

Resources

资源

Philosophy & Theory:

```
references/agent-philosophy.md
```
- Deep dive into why agents work

Implementation:

```
references/minimal-agent.py
```
- Complete working agent (~80 lines)
```
references/tool-templates.py
```
- Capability definitions
```
references/subagent-pattern.py
```
- Context isolation

Scaffolding:

```
scripts/init_agent.py
```
- Generate new agent projects

理念与理论：

```
references/agent-philosophy.md
```
- 深入探讨Agent的工作原理

实现方案：

```
references/minimal-agent.py
```
- 完整的可运行Agent（约80行代码）
```
references/tool-templates.py
```
- 能力定义模板
```
references/subagent-pattern.py
```
- 上下文隔离方案

脚手架工具：

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

The Agent Mindset

Agent思维模式

From: "How do I make the system do X?" To: "How do I enable the model to do X?"

From: "What's the workflow for this task?" To: "What capabilities would help accomplish this?"

The best agent code is almost boring. Simple loops. Clear capabilities. Clean context. The magic isn't in the code.

Give the model capabilities and knowledge. Trust it to figure out the rest.

从：“我如何让系统完成X任务？” 转变为：“我如何让模型具备完成X任务的能力？”

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

最好的Agent代码几乎是平淡无奇的。简单的循环、清晰的能力、干净的上下文。魔力不在于代码。

赋予模型能力和知识。信任它，剩下的交给它自己解决。