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
```
- 上下文隔离的子Agent模式

脚手架工具:

```
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代码往往简洁到近乎平淡。简单的循环、清晰的能力、干净的上下文。核心魔力不在代码里。

赋予模型能力和知识，信任它能完成剩下的工作。