Config.Yml (_config.yml)

Jekyll 配置文件

网站基本信息

title: Agentic Design Patterns
author:
name: xindoo

网站设置

lang: zh-CN
timezone: Asia/Shanghai
baseurl: "/" # 子目录路径
url: "https://adp.xindoo.xyz" # 你的域名

主题设置

theme: jekyll-theme-cayman

或者使用其他主题：

theme: just-the-docs

remote_theme: pmarsceill/just-the-docs

Markdown 设置

markdown: kramdown
kramdown:
input: GFM
syntax_highlighter: rouge
syntax_highlighter_opts:
block:
line_numbers: true

插件

plugins:

jekyll-feed
jekyll-sitemap
jekyll-seo-tag
jekyll-relative-links

相对链接配置

relative_links:
enabled: true
collections: true

包含和排除文件

include:

README.md
chapters
images
original
bilingual

exclude:

Gemfile
Gemfile.lock
node_modules
vendor
.sass-cache
.jekyll-cache
.github
translation-guide.md
PROJECT_STRUCTURE.md
progress.md

默认值

defaults:

scope:
path: ""
type: "pages"
values:
layout: "default"

导航设置（用于某些主题）

navigation:

title: 首页
url: /
title: 核心章节
url: /chapters/
title: 贡献指南
url: /CONTRIBUTING.html

代码高亮主题

highlighter: rouge

启用相对路径

permalink: pretty

AGENTS (AGENTS.md)

Agentic Design Patterns - 智能体操作指南

本文档为运行在本代码库的AI编码/翻译智能体提供操作规范。

1. 项目概述

本项目是《Agentic Design Patterns》一书的中文翻译项目，是AI Agent系统设计模式的权威指南。

代码仓库: https://github.com/xindoo/agentic-design-patterns
在线站点: https://adp.xindoo.xyz/
技术栈: Jekyll (GitHub Pages)、Markdown、Ruby
核心任务: 翻译质量优化、内容更新、站点维护

2. 构建/检查/运行命令

环境要求

已安装 Ruby 2.7+ 和 Bundler
已安装 Node.js (用于代码检查工具)

依赖安装

bash

# 安装Ruby依赖
bundle install

# 安装Node.js代码检查工具（可选，用于质量检查）
npm install markdownlint-cli markdown-link-check

构建与本地运行

bash

# 构建静态站点到 _site/ 目录
bundle exec jekyll build

# 本地启动服务，支持热重载，访问地址：http://localhost:4000
bundle exec jekyll serve --livereload

# 生产环境构建（与GitHub Pages部署逻辑一致）
JEKYLL_ENV=production bundle exec jekyll build

代码检查与质量校验

bash

# 检查所有Markdown文件的格式问题
npx markdownlint-cli chapters/

# 检查指定章节的无效链接
npx markdown-link-check chapters/[章节文件名].md

# 检查特定术语的翻译一致性
grep -r "术语原文" chapters/

# 验证Jekyll配置有效性
bundle exec jekyll doctor

测试要求

本内容类项目无自动化单元测试，所有修改必须通过：

Markdown语法检查无错误
本地构建成功无Jekyll错误
链接检查无无效内部链接
翻译内容人工审核通过

3. 代码与内容风格规范

Markdown格式规范

标题层级: 严格保留原文的标题层级结构（# 一级标题、## 二级标题、### 三级标题，以此类推）
换行规则: 段落之间使用1个空行分隔，行尾无多余空格
列表格式: 嵌套列表保留原有缩进，无序列表使用 -，有序列表使用 1.

代码块: 反引号后必须指定语言标识：

python

# 示例：带语言标识的代码块
def example():
    return "value"

行内代码: 变量名、函数名、命令行输入使用单反引号包裹
表格格式: 保持Markdown表格对齐，表头翻译为中文，内容对齐方式与原文一致

翻译标准

准确性优先

完整保留所有技术含义，无明确理由不得遗漏或新增内容
对技术术语翻译不确定时，添加译者注：[译者注: 此处XXX术语翻译存疑，原文为XXX]
技术概念使用行业标准译法，避免字面直译

术语一致性

强制要求: 所有术语翻译必须同时参考 glossary.md 和 Index of Terms.md 中的统一译法
新术语首次出现时需标注英文原文：中文译名(English Original)
后续出现统一使用中文译名即可
禁止为已有标准译法的技术术语自创翻译
重要原则: 不要轻易批量替换关键词，必须根据上下文判断是否修改。例如："代理"可能是技术术语 proxy，"流水线"可能是计算机科学通用术语，"提示链"在某些语境下可能不需要改为"提示词链"。在进行任何替换前，必须先读取文件查看具体上下文。
章节固定标题译法:

原文推荐译文

At a Glance 速览

What 问题背景

Why 解决方案

Rule of Thumb 实践建议

原文	推荐译文
At a Glance	速览
What	问题背景
Why	解决方案
Rule of Thumb	实践建议

语言风格

使用自然流畅的中文表达，避免直译英文句式
保持技术文档的专业、简洁语气
全书翻译风格统一，与已翻译章节保持一致
标点符号：中文内容使用中文标点，代码和英文术语使用英文标点

命名规范

文件名: 章节文件名保留原文英文：Chapter X_ [Original Name].md
图片路径: 使用 `` 格式
分支名: 新贡献使用 feature/[任务描述] 格式，例如 feature/translate-chapter-5、feature/fix-chapter-3-typos
提交信息: 使用清晰的中文描述：完成第X章翻译、修复第Y章术语错误、更新Z章节内容

错误处理

遇到无效链接时，修复为正确的内部路径
遇到缺失图片时，通知维护者，不得直接删除图片引用
发现翻译不一致时，对照 glossary.md 修正所有相关出现位置
禁止忽略Jekyll构建错误，提交前必须修复根本原因

代码与技术内容规则

代码片段: 所有代码保留原文英文，不得翻译代码逻辑、变量名、函数名
代码注释: 可以将代码注释翻译为中文，但代码本身保持不变
命令行说明: 命令本身保留英文，说明部分翻译为中文
框架/技术名称: LangChain、OpenAI、MCP、RAG等专有名词保留原文，除非有广泛接受的标准中文译法

4. 工作流规范

修改前检查

操作前先阅读 CONTRIBUTING.md 和 translation-guide.md
确认你要修改的内容没有已存在的开放拉取请求
查看 progress.md 了解当前翻译进度

提交要求

所有修改聚焦于单个章节或任务，避免在一个PR中包含不相关的改动
完整填写PR模板，说明修改内容和原因
PR提交前必须通过本地构建和代码检查
PR描述中包含验证步骤，例如："本地构建成功，markdownlint检查通过，第3章内容已审核"

禁止操作

不得修改 original/ 目录下的文件（原文备份目录）
未经维护者明确批准，不得修改 _config.yml 中的Jekyll配置
未经过讨论不得新增依赖或插件
已正确翻译的内容不得随意重写，除非修复明确错误

5. 双语版本指南

5.1 双语版本概述

双语版本将英文原文和中文翻译交替显示，每段英文后紧跟对应的中文翻译，代码块作为整体不分割。这种格式便于读者对照阅读，提高翻译质量和学习效率。

访问路径：

中文版: /chapters/
英文版: /original/
双语版: /bilingual/

5.2 双语文件结构

text

bilingual/
├── Chapter 1_ Prompt Chaining.md
├── Chapter 2_ Routing.md
├── ...
├── Glossary.md
├── Index of Terms.md
└── index.md

文件名：与 chapters/ 和 original/ 目录保持一致，使用原文英文文件名，例如 Chapter 1_ Prompt Chaining.md。

文件完整性：bilingual/ 目录必须包含与 chapters/ 和 original/ 相同的完整文件集合，包括所有章节、附录、术语表和索引文件。

5.3 双语内容格式规范

基础格式规则

双语文件必须严格按照以下格式组织内容：

markdown

# English Title

# 中文标题

## English Section Heading

## 中文章节标题

English paragraph here.

中文翻译段落。

Another English paragraph.

另一段中文翻译。

```python
# 代码块保持完整，只出现一次，放在对应英文段落之后
code_here()

text

#### 标题层级规范

- **一级标题**：英文标题后紧跟中文标题，各占一行
  ```markdown
  # Chapter 1: Prompt Chaining

  # 第 1 章：提示词链

二级及以下标题：英文标题后紧跟中文标题，各占一行
markdown
```
## Prompt Chaining Pattern Overview

## 提示词链模式概述
```
标题层级一致性：严格保持与原文相同的标题层级结构，不得随意更改

段落交替规范

逐段对照：每个英文段落后紧跟对应的中文翻译段落
空行分隔：英文段落与中文段落之间必须有一个空行
段落完整性：保持原文段落结构，不要合并或拆分段落
列表处理：完整的英文列表后紧跟完整的中文列表，保持列表格式一致

示例：
markdown
```
* English list item 1
* English list item 2

* 中文列表项 1
* 中文列表项 2
```

代码块处理规范

代码块只出现一次：代码块紧跟在对应的英文说明段落之后，中文翻译段落之前
代码保持原样：代码内容、注释、格式完全保留原文
语言标识保留：保留代码块的语言标识（如 python、bash 等）

示例：
markdown
```
Here's a code example:

```python
def example():
    return "value"
```
这是一个代码示例：
text

特殊元素处理

图片引用：图片只出现一次，放在对应的英文段落之后，中文翻译之前
表格：完整的英文表格后紧跟完整的中文表格，表头和内容都要翻译
链接：链接只出现一次，保持原文链接地址，链接文本可以翻译或保留英文
引用块：完整的英文引用块后紧跟完整的中文引用块

5.4 网页版双语支持

导航栏自动根据当前语言显示对应目录
语言切换按钮支持三态切换：中文 → 英文 → 双语 → 中文
上一章/下一章导航在三种版本间正常工作
使用 _layouts/bilingual.html 布局模板渲染双语页面
使用 _includes/navigation-bilingual.html 提供双语版导航

5.5 PDF/EPUB 生成

GitHub Workflow (.github/workflows/generate-pdf.yml) 会自动生成三种版本的 PDF 和 EPUB：

文件	说明
`agentic-design-patterns-chinese.pdf`	中文版 PDF
`agentic-design-patterns-chinese.epub`	中文版 EPUB
`agentic-design-patterns-en.pdf`	英文版 PDF
`agentic-design-patterns-en.epub`	英文版 EPUB
`agentic-design-patterns-bilingual.pdf`	双语版 PDF
`agentic-design-patterns-bilingual.epub`	双语版 EPUB

触发条件：push 到 main 分支，且修改了 chapters/**、original/** 或 bilingual/**

5.6 更新双语版本的流程

完整更新流程

更新中文翻译 → 修改 chapters/ 目录下的对应文件
更新英文原文（如需要）→ 修改 original/ 目录下的对应文件
同步更新双语文件 → 修改 bilingual/ 目录下的对应文件，确保格式符合 5.3 节规范
提交更改 → 包含 chapters/、original/（如修改）和 bilingual/ 的改动
自动触发 Workflow → 生成新的 PDF/EPUB

双语文件同步检查清单

在提交双语文件更新前，请确认：

所有标题都有对应的中英文对照
所有段落都按英文-中文顺序交替排列
代码块只出现一次且位置正确
图片、表格、链接等特殊元素处理正确
文件名与 chapters/ 和 original/ 保持一致
文件完整性检查：没有遗漏任何章节或附录
Markdown 语法检查通过
本地 Jekyll 构建成功

5.7 双语文件生成工具（如适用）

如果项目提供了自动生成双语文件的工具，请参考工具文档使用。在没有自动化工具的情况下，必须手动按照上述规范创建和维护双语文件。

7. 双语版本维护规范

7.1 双语文件质量标准

格式一致性：严格遵守 5.3 节的格式规范
内容完整性：双语文件必须包含原文的所有内容，不得遗漏
翻译准确性：中文翻译必须与 chapters/ 目录中的翻译保持一致
同步及时性：chapters/ 或 original/ 更新后，bilingual/ 必须同步更新
无冗余内容：代码块、图片等元素只出现一次，避免重复

7.2 禁止操作

不得直接修改 bilingual/ 目录而不同步更新 chapters/ 目录
不得在双语文件中随意调整段落顺序或合并/拆分段落
不得删除或重复代码块、图片等特殊元素
不得改变原文的标题层级结构
不得在未完成同步的情况下提交部分更新

8. 核心资源

glossary.md: 官方术语翻译对照表
translation-guide.md: 详细翻译标准与最佳实践
CONTRIBUTING.md: 完整贡献流程与要求
progress.md: 当前翻译进度与章节状态
PROJECT_STRUCTURE.md: 代码库文件结构说明

OPTIMIZE README (OPTIMIZE_README.md)

翻译优化脚本使用说明

本目录提供两个并行优化脚本，用于批量优化章节翻译。

脚本对比

脚本	语言	依赖	特点
`optimize_translations.py`	Python	Python 3.6+	推荐使用，无需额外依赖
`optimize_translations.sh`	Bash	GNU Parallel, coreutils	需要安装额外工具

推荐使用: Python 版本

快速开始

bash

# 直接运行
./optimize_translations.py

功能特点

自动跳过索引、术语表等非章节文件
可配置的并行数 (默认 4)
可配置的超时时间 (默认 10 分钟)
实时显示处理进度
完成后显示成功/失败统计

配置修改

编辑脚本开头的配置部分:

python

MAX_WORKERS = 4      # 最大并行任务数
TIMEOUT = 600         # 超时时间(秒)

跳过的文件

脚本默认跳过以下文件:

Index of Terms.md
Glossary.md
README.md
Agentic Design Patterns.md
Frequently Asked Questions_ Agentic Design Patterns.md
Conclusion.md

Bash 版本 (备选)

依赖安装

bash

# macOS
brew install parallel coreutils

# Ubuntu/Debian
sudo apt install parallel

运行

bash

./optimize_translations.sh

使用流程

确认环境
- 确保 opencode 命令可用
- 确保在项目根目录下运行
运行脚本
bash
```
./optimize_translations.py
```
确认执行
- 脚本会显示将要处理的章节列表
- 输入 y 确认开始
等待完成
- 脚本会并行处理多个章节
- 实时显示处理状态
查看结果
- 完成后显示成功/失败统计
- 失败的章节会列出

注意事项

每个任务默认超时时间为 10 分钟
建议先从较小的并行数开始测试 (2-4)
如遇问题，可以单独运行失败的章节
脚本不会修改原文件，而是通过 opencode 进行修改

单独处理某个章节

如果需要单独处理某个章节，可以直接运行:

bash

opencode run "ulw 优化下 Chapter 1_ Prompt Chaining.md 章节的翻译，尤其是一些晦涩、表述不畅的部分，但不要改变原意"

Progress (progress.md)

翻译进度追踪

总体进度

总内容数：32（主要内容 + 21章节 + 7附录 + 3其他）
已翻译完成：32
待审核：32
已审核完成：0

主要内容

内容	标题	翻译者	状态	更新日期
主文档	Agentic Design Patterns	-	已完成	2025-12-20
结论	Conclusion	-	已完成	2025-12-20
术语表	Glossary	-	已完成	2025-12-20
索引	Index of Terms	-	已完成	2025-12-20
FAQ	Frequently Asked Questions	-	已完成	2025-12-20

章节详情

章节	标题	翻译者	状态	更新日期
第1章	Prompt Chaining（提示词链）	-	已完成	2025-10-11
第2章	Routing（路由）	-	已完成	2025-10-14
第3章	Parallelization（并行化）	-	已完成	2025-10-14
第4章	Reflection（反思）	-	已完成	2025-10-15
第5章	Tool Use（工具使用（函数调用））	-	已完成	2025-10-15
第6章	Planning（规划）	-	已完成	2025-10-17
第7章	Multi-Agent Collaboration（多 Agent 协作）	-	已完成	2025-10-17
第8章	Memory Management（记忆管理）	-	已完成	2025-10-17
第9章	Learning and Adaptation（学习和适应）	-	已完成	2025-10-17
第10章	Model Context Protocol (MCP)（模型上下文协议 (MCP)）	-	已完成	2025-10-17
第11章	Goal Setting and Monitoring（目标设定和监控）	-	已完成	2025-10-18
第12章	Exception Handling and Recovery（异常处理和恢复）	-	已完成	2025-10-18
第13章	Human-in-the-Loop（人机协同）	-	已完成	2025-10-18
第14章	Knowledge Retrieval (RAG)（知识检索（RAG））	-	已完成	2025-10-19
第15章	Inter-Agent Communication (A2A)（Agent 间通信（A2A））	-	已完成	2025-10-19
第16章	Resource-Aware Optimization（资源感知优化）	-	已完成	2025-10-19
第17章	Reasoning Techniques（推理技术）	-	已完成	2025-10-19
第18章	Guardrails/Safety Patterns（Guardrails/安全模式）	-	已完成	2025-10-19
第19章	Evaluation and Monitoring（评估和监控）	-	已完成	2025-10-20
第20章	Prioritization（优先级排序）	-	已完成	2025-10-20
第21章	Exploration and Discovery（探索和发现）	-	已完成	2025-10-20

附录详情

附录	标题	翻译者	状态	更新日期
附录A	Advanced Prompting Techniques（高级提示工程技巧）	-	已完成	2025-10-21
附录B	AI Agentic Interactions: From GUI to Real world environment（AI智能体交互：从图形界面到现实世界环境）	-	已完成	2025-10-21
附录C	Quick overview of Agentic Frameworks（Agentic 框架快速概览）	-	已完成	2025-10-21
附录D	Building an Agent with AgentSpace (on-line only)（使用 AgentSpace 构建 Agent）	-	已完成	2025-10-21
附录E	AI Agents on the CLI（命令行界面中的 AI Agent）	-	已完成	2025-10-21
附录F	Under the Hood: An Inside Look at the Agents' Reasoning Engines（深入剖析：Agent 推理引擎的内部运作机制）	-	已完成	2025-10-21
附录G	Coding agents（编码 Agent）	-	已完成	2025-10-21

状态说明

待审核：初次翻译完成，等待二次审校
审校中：正在进行二次审校
已完成：二次审校通过，翻译完成

更新方式

认领审校任务或完成审校后，请更新此表格，并提交 PR。

文件位置

审校重点

在进行二次审校时，请重点关注：

术语翻译的一致性
技术细节的准确性
语言表达的流畅性
代码示例的完整性
图片引用的正确性

SUMMARY (SUMMARY.md)

翻译指南

翻译原则

1. 准确性第一

保持原文的技术准确性
不要遗漏重要信息
如有疑问，在注释中标记 [译者注: XXX]

2. 中文表达习惯

避免英文的直译腔调
使用符合中文习惯的句式结构
保持语言的自然流畅

3. 专业术语统一

参考业界通用的中文译名
首次出现时可标注英文原文，如：机器学习(Machine Learning)
后续使用统一的中文术语

格式规范

Markdown 格式

标题层级保持与原文一致
列表项目保持原有的缩进结构
代码块使用正确的语言标识符

代码处理

代码保持原文不变
注释可以翻译为中文
变量名和函数名保持英文

图片引用

图片路径格式：``
图片描述使用中文
图片文件名保持英文

常用术语对照表

英文	中文	备注
Framework	框架
Library	库
Function	函数
Method	方法
Class	类
Object	对象
Variable	变量
Parameter	参数
Argument	实参
Return	返回
Exception	异常
Error	错误
Debug	调试
Test	测试
Deploy	部署
Release	发布
Version	版本
Repository	仓库
Branch	分支
Commit	提交

翻译流程

第一遍：粗译

通读整个章节，理解整体内容
逐段翻译，保持原意
标记不确定的地方

第二遍：精修

检查术语使用的一致性
调整语言表达，使其更符合中文习惯
检查格式和标点符号

第三遍：校对

对照原文检查遗漏和错误
检查图片引用路径
确保代码格式正确

质量检查清单

翻译准确，无遗漏
语言流畅自然
术语使用一致
格式符合规范
图片路径正确
代码格式正确
标点符号正确

注意事项

遇到文化差异的内容，可以适当本土化
技术概念保持准确性，不要过度解释
如有疑问，优先在翻译群组中讨论
定期更新术语对照表

Bilingual/Agentic Design Patterns (bilingual/Agentic Design Patterns.md)

layout: bilingual lang: bilingual

Agentic Design Patterns

智能体设计模式

A Hands-On Guide to Building Intelligent Systems[^1], Antonio Gulli

构建智能系统的实战指南^2，作者：Antonio Gulli

Table of Contents - total 424 pages = 1+2+1+1+4+9+103+61+34+114+74+5+4 11

目录总览（424 页）

Dedication, 1 page

致谢（1 页）

Acknowledgment, 2 pages [final, last read done]

鸣谢（2 页）

Foreword, 1 page [final, last read done]

前言（1 页）

A Thought Leader's Perspective: Power and Responsibility [final, last read done]

思想领袖视角：权力与责任

Introduction, 4 pages [final, last read done]

引言（4 页）

What makes an AI system an "agent"?, 9 pages [final, last read done]

是什么让 AI 系统成为"智能体"？（9 页）

Part One, (Total: 103 pages)

第一部分：核心模式（103 页）

Chapter 1: Prompt Chaining (code), 12 pages [final, last read done, code ok]
提示词链（12 页）
Chapter 2: Routing (code), 13 pages [final, last read done, code ok]
路由决策（13 页）
Chapter 3: Parallelization (code), 15 pages [final, last read done, code ok]
并行执行（15 页）
Chapter 4: Reflection (code), 13 pages [final, last read done, code ok]
反思优化（13 页）
Chapter 5: Tool Use (code), 20 pages [final, last read done, code ok]
工具调用（20 页）
Chapter 6: Planning (code), 13 pages [final, last read done, code ok]
任务规划（13 页）
Chapter 7: Multi-Agent (code), 17 pages [final, last read done, code ok], 121
多智能体协作（17 页）

Part Two (Total: 61 pages)

第二部分：认知机制（61 页）

Chapter 8: Memory Management (code), 21 pages [final, last read done, code ok]
记忆管理（21 页）
Chapter 9: Learning and Adaptation (code), 12 pages [final, last read done, code ok]
学习与适应（12 页）
Chapter 10: Model Context Protocol (MCP) (code), 16 pages [final, last read done, code ok]
模型上下文协议 (MCP)（16 页）
Chapter 11: Goal Setting and Monitoring (code), 12 pages [final, last read done, code ok], 182
目标设定与监控（12 页）

Part Three (Total: 34 pages)

第三部分：容错与扩展（34 页）

Chapter 12: Exception Handling and Recovery (code), 8 pages [final, last read done, code ok]
异常处理与恢复（8 页）
Chapter 13: Human-in-the-Loop (code), 9 pages [final, last read done, code ok]
人机协同（9 页）
Chapter 14: Knowledge Retrieval (RAG) (code), 17 pages [final, last read done, code ok], 216
知识检索 (RAG)（17 页）

Part Four (Total: 114 pages)

第四部分：高级架构（114 页）

Chapter 15: Inter-Agent Communication (A2A) (code), 15 pages [final, last read done, code ok]
智能体间通信 (A2A)（15 页）
Chapter 16: Resource-Aware Optimization (code), 15 pages [final, last read done, code ok]
资源感知优化（15 页）
Chapter 17: Reasoning Techniques (code), 24 pages [final, last read done, code ok]
推理技术（24 页）
Chapter 18: Guardrails/Safety Patterns (code), 19 pages [final, last read done, code ok]
安全护栏模式（19 页）
Chapter 19: Evaluation and Monitoring (code), 18 pages [final, last read done, code ok]
评估与监控（18 页）
Chapter 20: Prioritization (code), 10 pages [final, last read done, code ok ]
优先级管理（10 页）
Chapter 21: Exploration and Discovery (code), 13 pages [final, last read done, code ok], 330
探索与发现（13 页）

Appendix (Total: 74 pages)

附录（74 页）

Appendix A: Advanced Prompting Techniques, 28 pages [final, last read done, code ok]
高级提示技术（28 页）
Appendix B - AI Agentic ….: From GUI to Real world environment, 6 pages [final, last read done, code ok]
AI 智能体交互：从 GUI 到真实世界（6 页）
Appendix C - Quick overview of Agentic Frameworks, 8 pages [final, last read done, code ok] ,
智能体框架概览（8 页）
Appendix D - Building an Agent with AgentSpace (on-line only), 6 pages [final, last read done, code ok]
使用 AgentSpace 构建智能体（6 页）
Appendix E - AI Agents on the CLI , 5 pages [final, last read done, code ok]
命令行 AI 智能体（5 页）
Appendix F - Under the Hood: An Inside Look at the Agents' Reasoning Engines, 14 pages [final, read, code ok],
智能体推理引擎剖析（14 页）
Appendix G - Coding agents, 7 pages 406
编程实现智能体（7 页）

Conclusion, 5 pages [final, last read done]

结论（5 页）

Glossary, 4 pages [final, last read done]

术语表（4 页）

Index of Terms, 11 pages (Generated by Gemini. Reasoning step included as an agentic example) [final, read]

术语索引（11 页，含智能体推理示例）

Online Contribution - Frequently Asked Questions: Agentic Design Patterns

常见问题解答

Pre Print: https://www.amazon.com/Agentic-Design-Patterns-Hands-Intelligent/dp/3032014018/

预印本：https://www.amazon.com/Agentic-Design-Patterns-Hands-Intelligent/dp/3032014018/

封面图

[^1]: All my royalties will be donated to Save the Children

Bilingual/Appendix B AI Agentic Interactions From GUI To Real World Environment (bilingual/Appendix B - AI Agentic Interactions_ From GUI to Real world environment.md)

Appendix B - AI Agentic Interactions: From GUI to Real World environment

附录 B - AI 智能体交互：从图形用户界面到真实世界环境

AI agents are increasingly performing complex tasks by interacting with digital interfaces and the physical world. Their ability to perceive, process, and act within these varied environments is fundamentally transforming automation, human-computer interaction, and intelligent systems. This appendix explores how agents interact with computers and their environments, highlighting advancements and projects.

AI 智能体正日益通过与数字界面和物理世界的交互来执行复杂任务。它们在这些多样化环境中感知、处理和行动的能力，正在从根本上重塑自动化、人机交互和智能系统的格局。本附录深入探讨智能体如何与计算机及其环境交互，并重点介绍相关技术进展与代表性项目。

Interaction: Agents with Computers

交互：智能体与计算机

The evolution of AI from conversational partners to active, task-oriented agents is being driven by Agent-Computer Interfaces (ACIs). These interfaces allow AI to interact directly with a computer's Graphical User Interface (GUI), enabling it to perceive and manipulate visual elements like icons and buttons just as a human would. This new method moves beyond the rigid, developer-dependent scripts of traditional automation that relied on APIs and system calls. By using the visual "front door" of software, AI can now automate complex digital tasks in a more flexible and powerful way, a process that involves several key stages:

AI 从对话伙伴向主动式任务导向型智能体演进，正由智能体-计算机界面（Agent-Computer Interfaces，ACIs）技术驱动。这些界面使 AI 能够直接与计算机的图形用户界面（Graphical User Interface，GUI）交互，使其能像人类一样感知并操作图标、按钮等视觉元素。这种新范式超越了依赖 API 和系统调用的传统自动化方法——后者往往受限于僵化的、依赖开发人员编写的脚本。通过利用软件的视觉"前门"，AI 现能以更灵活、更强大的方式自动化复杂数字任务，该过程涉及以下关键阶段：

Visual Perception: The agent first captures a visual representation of the screen, essentially taking a screenshot.
GUI Element Recognition: It then analyzes this image to distinguish between various GUI elements. It must learn to "see" the screen not as a mere collection of pixels, but as a structured layout with interactive components, discerning a clickable "Submit" button from a static banner image or an editable text field from a simple label.
Contextual Interpretation: The ACI module, acting as a bridge between the visual data and the agent's core intelligence (often a Large Language Model or LLM), interprets these elements within the context of the task. It understands that a magnifying glass icon typically means "search" or that a series of radio buttons represents a choice. This module is crucial for enhancing the LLM's reasoning, allowing it to form a plan based on visual evidence.
Dynamic Action and Response: The agent then programmatically controls the mouse and keyboard to execute its plan—clicking, typing, scrolling, and dragging. Critically, it must constantly monitor the screen for visual feedback, dynamically responding to changes, loading screens, pop-up notifications, or errors to successfully navigate multi-step workflows.
视觉感知：智能体首先捕获屏幕的视觉呈现，本质上相当于截屏操作。
GUI 元素识别：随后分析该图像以区分各类 GUI 元素。它必须学会将屏幕"解读"为具有交互组件的结构化布局，而非单纯的像素集合，能够辨别可点击的"提交"按钮与静态横幅广告，或区分可编辑文本框与普通标签。
上下文理解：ACI 模块作为视觉数据与智能体核心智能（通常为大型语言模型 LLM）间的桥梁，在任务背景下解析这些元素。它能理解放大镜图标通常代表"搜索"，或一组单选按钮表示选项。此模块对增强 LLM 推理能力至关重要，使其能基于视觉证据制定行动计划。
动态执行与响应：智能体随后通过程序化控制鼠标和键盘执行计划——包括点击、输入、滚动和拖拽。关键在于，它必须持续监控屏幕以获取视觉反馈，动态响应界面变化、加载状态、弹窗通知或错误信息，从而成功驾驭多步骤工作流。

This technology is no longer theoretical. Several leading AI labs have developed functional agents that demonstrate the power of GUI interaction:

这项技术已不再停留在理论层面。多家领先 AI 实验室已开发出功能性智能体，充分展示了 GUI 交互的强大潜力：

ChatGPT Operator (OpenAI): Envisioned as a digital partner, ChatGPT Operator is designed to automate tasks across a wide range of applications directly from the desktop. It understands on-screen elements, enabling it to perform actions like transferring data from a spreadsheet into a customer relationship management (CRM) platform, booking a complex travel itinerary across airline and hotel websites, or filling out detailed online forms without needing specialized API access for each service. This makes it a universally adaptable tool aimed at boosting both personal and enterprise productivity by taking over repetitive digital chores.

ChatGPT Operator（OpenAI）：ChatGPT Operator 被构想为数字协作伙伴，旨在直接从桌面端自动化多种应用程序的任务。它能理解屏幕元素，从而执行诸如将电子表格数据导入客户关系管理（CRM）系统、在航空公司和酒店网站间规划复杂行程，或填写详尽在线表单等操作，无需为每个服务配置专用 API 访问权限。这使其成为通用性工具，旨在通过接管重复性数字任务提升个人与企业效率。

Google Project Mariner: As a research prototype, Project Mariner operates as an agent within the Chrome browser (see Fig. 1). Its purpose is to understand a user's intent and autonomously carry out web-based tasks on their behalf. For example, a user could ask it to find three apartments for rent within a specific budget and neighborhood; Mariner would then navigate to real estate websites, apply the filters, browse the listings, and extract the relevant information into a document. This project represents Google's exploration into creating a truly helpful and "agentive" web experience where the browser actively works for the user.

Google Project Mariner：作为研究原型，Project Mariner 作为智能体在 Chrome 浏览器内运行（见图 1）。其核心目标是理解用户意图并自主执行基于网络的任务。例如，用户可指令其在特定预算和区域内寻找三套出租公寓；Mariner 便会导航至房产网站，应用筛选条件，浏览房源列表，并将相关信息提取至文档中。该项目体现了 Google 对构建真正实用且具"代理性"网络体验的探索——让浏览器主动为用户服务。

Fig.1: Interaction between and Agent and the Web Browser

图 1：智能体与网络浏览器的交互示意图

Anthropic's Computer Use: This feature empowers Anthropic's AI model, Claude, to become a direct user of a computer's desktop environment. By capturing screenshots to perceive the screen and programmatically controlling the mouse and keyboard, Claude can orchestrate workflows that span multiple, unconnected applications. A user could ask it to analyze data in a PDF report, open a spreadsheet application to perform calculations on that data, generate a chart, and then paste that chart into an email draft—a sequence of tasks that previously required constant human input.

Anthropic 的计算机使用功能：该特性使 Anthropic 的 AI 模型 Claude 能够成为计算机桌面环境的直接操作用户。通过截屏感知界面并以程序化方式控制鼠标键盘，Claude 可编排跨多个独立应用的工作流。用户可要求其分析 PDF 报告中的数据，打开电子表格程序进行相关计算，生成图表，并将图表插入邮件草稿——这一系列任务以往需要持续的人工介入。

Browser Use: This is an open-source library that provides a high-level API for programmatic browser automation. It enables AI agents to interface with web pages by granting them access to and control over the Document Object Model (DOM). The API abstracts the intricate, low-level commands of browser control protocols, into a more simplified and intuitive set of functions. This allows an agent to perform complex sequences of actions, including data extraction from nested elements, form submissions, and automated navigation across multiple pages. As a result, the library facilitates the transformation of unstructured web data into a structured format that an AI agent can systematically process and utilize for analysis or decision-making.

Browser Use：这是一个提供程序化浏览器自动化高级 API 的开源库。它使 AI 智能体通过访问和控制文档对象模型（Document Object Model，DOM）与网页交互。该 API 将浏览器控制协议的复杂底层指令抽象为更简洁直观的函数集。这使得智能体能够执行复杂操作序列，包括从嵌套元素提取数据、提交表单以及跨页面自动导航。因此，该库助力将非结构化网络数据转化为 AI 智能体可以用于分析或决策的结构化格式。

Interaction: Agents with the Environment

交互：智能体与环境

Beyond the confines of a computer screen, AI agents are increasingly designed to interact with complex, dynamic environments, often mirroring the real world. This requires sophisticated perception, reasoning, and actuation capabilities.

超越计算机屏幕的局限，AI 智能体正越来越多地被设计用于与复杂、动态的环境交互，这些环境往往模拟现实世界。这要求智能体具备复杂的感知、推理和执行能力。

Google's Project Astra is a prime example of an initiative pushing the boundaries of agent interaction with the environment. Astra aims to create a universal AI agent that is helpful in everyday life, leveraging multimodal inputs (sight, sound, voice) and outputs to understand and interact with the world contextually. This project focuses on rapid understanding, reasoning, and response, allowing the agent to "see" and "hear" its surroundings through cameras and microphones and engage in natural conversation while providing real-time assistance. Astra's vision is an agent that can seamlessly assist users with tasks ranging from finding lost items to debugging code, by understanding the environment it observes. This moves beyond simple voice commands to a truly embodied understanding of the user's immediate physical context.

Google 的 Project Astra 是推动智能体与环境交互边界的一个典范。Astra 致力于打造一个在日常生活中实用的通用 AI 智能体，它利用多模态输入（视觉、听觉、语音）和输出来理解世界并进行上下文交互。该项目聚焦于快速理解、推理与响应，使智能体通过摄像头和麦克风"看见"和"听见"周遭环境，并在提供实时协助的同时进行自然对话。Astra 的愿景是打造一个能无缝帮助用户完成从寻找失物到调试代码等各种任务的智能体，其核心在于理解所观察的环境。这超越了简单的语音指令，实现了对用户即时物理情境的真正具身化理解。

Google's Gemini Live, transforms standard AI interactions into a fluid and dynamic conversation. Users can speak to the AI and receive responses in a natural-sounding voice with minimal delay, and can even interrupt or change topics mid-sentence, prompting the AI to adapt immediately. The interface expands beyond voice, allowing users to incorporate visual information by using their phone's camera, sharing their screen, or uploading files for a more context-aware discussion. More advanced versions can even perceive a user's tone of voice and intelligently filter out irrelevant background noise to better understand the conversation. These capabilities combine to create rich interactions, such as receiving live instructions on a task by simply pointing a camera at it.

Google 的 Gemini Live 将标准 AI 交互转化为流畅且动态的对话体验。用户可与 AI 交谈，并以极低延迟收到自然语音回复，甚至能在语句中途打断或切换话题，AI 会立即适应。交互界面不限于语音，用户还可通过手机摄像头、屏幕共享或文件上传融入视觉信息，进行更具情境感知的讨论。更高级版本甚至能感知用户语调，并智能滤除无关背景噪音以提升对话理解。这些能力共同创造了丰富的交互场景，例如仅需将摄像头对准某物即可获得该任务的实时指导。

OpenAI's GPT-4o model is an alternative designed for "omni" interaction, meaning it can reason across voice, vision, and text. It processes these inputs with low latency that mirrors human response times, which allows for real-time conversations. For example, users can show the AI a live video feed to ask questions about what is happening, or use it for language translation. OpenAI provides developers with a "Realtime API" to build applications requiring low-latency, speech-to-speech interactions.

OpenAI 的 GPT-4o 模型 是专为"全向"交互设计的另一选择，意指其能跨语音、视觉和文本进行推理。该模型以接近人类响应速度的低延迟处理这些输入，从而实现实时对话。例如，用户可向 AI 展示实时视频流并询问画面内容，或用于语言翻译。OpenAI 为开发者提供了"实时 API"，用于构建需要低延迟、语音到语音交互的应用。

OpenAI's ChatGPT Agent represents a significant architectural advancement over its predecessors, featuring an integrated framework of new capabilities. Its design incorporates several key functional modalities: the capacity for autonomous navigation of the live internet for real-time data extraction, the ability to dynamically generate and execute computational code for tasks like data analysis, and the functionality to interface directly with third-party software applications. The synthesis of these functions allows the agent to orchestrate and complete complex, sequential workflows from a singular user directive. It can therefore autonomously manage entire processes, such as performing market analysis and generating a corresponding presentation, or planning logistical arrangements and executing the necessary transactions. In parallel with the launch, OpenAI has proactively addressed the emergent safety considerations inherent in such a system. An accompanying "System Card" delineates the potential operational hazards associated with an AI capable of performing actions online, acknowledging the new vectors for misuse. To mitigate these risks, the agent's architecture includes engineered safeguards, such as requiring explicit user authorization for certain classes of actions and deploying robust content filtering mechanisms. The company is now engaging its initial user base to further refine these safety protocols through a feedback-driven, iterative process.

OpenAI 的 ChatGPT Agent 代表了相较于前代产品的重大架构升级，集成了新功能框架。其设计包含多项核心功能模式：自主浏览实时互联网以提取实时数据的能力、动态生成并执行计算代码以完成数据分析等任务的能力，以及直接与第三方软件应用交互的功能。这些能力的融合使智能体从单一用户指令出发，编排并完成复杂、有序的工作流。因此，它能自主管理整个流程，例如执行市场分析并生成对应演示文稿，或规划物流安排并执行必要交易。在发布同时，OpenAI 主动应对了此类系统固有的新兴安全问题。随附的"系统卡"文件阐明了具备在线操作能力的 AI 可能带来的潜在风险，承认了新的滥用途径。为降低这些风险，Agent 架构内置了工程化保障措施，如要求特定操作类别需获得用户明确授权，并部署了强健的内容过滤机制。公司现正通过反馈驱动的迭代流程，邀请初期用户群体共同完善这些安全协议。

Seeing AI, a complimentary mobile application from Microsoft, empowers individuals who are blind or have low vision by offering real-time narration of their surroundings. The app leverages artificial intelligence through the device's camera to identify and describe various elements, including objects, text, and even people. Its core functionalities encompass reading documents, recognizing currency, identifying products through barcodes, and describing scenes and colors. By providing enhanced access to visual information, Seeing AI ultimately fosters greater independence for visually impaired users.

Seeing AI 是 Microsoft 推出的一款免费移动应用，它通过实时描述周围环境，为盲人或视力障碍人士赋能。该应用借助设备摄像头运用人工智能技术，识别并描述各类元素，包括物体、文字乃至人物。其核心功能涵盖文档阅读、货币识别、条形码产品辨识以及场景和颜色描述。通过增强对视觉信息的可及性，Seeing AI 最终提升了视障用户的独立生活能力。

Anthropic's Claude 4 Series: Anthropic's Claude 4 is another alternative with capabilities for advanced reasoning and analysis. Though historically focused on text, Claude 4 includes robust vision capabilities, allowing it to process information from images, charts, and documents. The model is suited for handling complex, multi-step tasks and providing detailed analysis. While the real-time conversational aspect is not its primary focus compared to other models, its underlying intelligence is designed for building highly capable AI agents.

Anthropic 的 Claude 4 系列：Anthropic 的 Claude 4 是另一款具备高级推理与分析能力的替代选择。尽管其传统强项在于文本处理，但 Claude 4 也包含了强大的视觉功能，能处理来自图像、图表和文档的信息。该模型适用于处理复杂的多步骤任务并提供详尽分析。虽然其实时对话特性并非主要焦点（相较于其他模型），但其底层智能专为构建高能力 AI 智能体而设计。

Vibe Coding: Intuitive Development with AI

Vibe 编码：使用 AI 的直观开发范式

Beyond direct interaction with GUIs and the physical world, a new paradigm is emerging in how developers build software with AI: "vibe coding." This approach moves away from precise, step-by-step instructions and instead relies on a more intuitive, conversational, and iterative interaction between the developer and an AI coding assistant. The developer provides a high-level goal, a desired "vibe," or a general direction, and the AI generates code to match.

除了与 GUI 和物理环境的直接交互外，开发人员使用 AI 构建软件的方式也涌现出新范式："vibe 编码"。这种方法摒弃了精确的、逐步的指令，转而依赖开发者与 AI 编码助手之间更直观、对话式和迭代的协作。开发者提供高层次目标、期望的"氛围"或大致方向，AI 则生成与之匹配的代码。

This process is characterized by:

该过程具有以下特征：

Conversational Prompts: Instead of writing detailed specifications, a developer might say, "Create a simple, modern-looking landing page for a new app," or, "Refactor this function to be more Pythonic and readable." The AI interprets the "vibe" of "modern" or "Pythonic" and generates the corresponding code.
Iterative Refinement: The initial output from the AI is often a starting point. The developer then provides feedback in natural language, such as, "That's a good start, but can you make the buttons blue?" or, "Add some error handling to that." This back-and-forth continues until the code meets the developer's expectations.
Creative Partnership: In vibe coding, the AI acts as a creative partner, suggesting ideas and solutions that the developer may not have considered. This can accelerate the development process and lead to more innovative outcomes.
Focus on "What" not "How": The developer focuses on the desired outcome (the "what") and leaves the implementation details (the "how") to the AI. This allows for rapid prototyping and exploration of different approaches without getting bogged down in boilerplate code.
Optional Memory Banks: To maintain context across longer interactions, developers can use "memory banks" to store key information, preferences, or constraints. For example, a developer might save a specific coding style or a set of project requirements to the AI's memory, ensuring that future code generations remain consistent with the established "vibe" without needing to repeat the instructions.
对话式提示：开发者不再编写详细规格说明，而是用自然语言表达，如"为新应用创建一个简洁现代风格的登录页面"，或"重构此函数使其更符合 Pythonic 风格并提升可读性"。AI 会解读"现代"或"Pythonic"的"氛围"内涵，生成相应代码。
迭代精炼：AI 的初始输出通常只是起点。开发者随后以自然语言提供反馈，如"这个开头不错，但能把按钮改成蓝色吗？"或"为那段代码添加错误处理机制。"如此往复，直至代码符合预期。
创意伙伴关系：在 vibe 编码中，AI 扮演创意伙伴角色，提出开发者可能未曾考虑的创意和解决方案。这能加速开发进程并催生更具创新性的成果。
聚焦"目标"而非"方法"：开发者专注于期望成果（"目标"），将实现细节（"方法"）交由 AI 处理。这使得快速原型设计和多方案探索成为可能，避免陷入样板代码的繁琐。
可选记忆库：为在长对话中保持上下文连贯，开发者可使用"记忆库"存储关键信息、偏好或约束条件。例如，开发者可将特定编码风格或项目需求集保存至 AI 记忆库，确保后续代码生成与既定"氛围"保持一致，无需重复指令。

Vibe coding is becoming increasingly popular with the rise of powerful AI models like GPT-4, Claude, and Gemini, which are integrated into development environments. These tools are not just auto-completing code; they are actively participating in the creative process of software development, making it more accessible and efficient. This new way of working is changing the nature of software engineering, emphasizing creativity and high-level thinking over rote memorization of syntax and APIs.

随着 GPT-4、Claude 和 Gemini 等强大 AI 模型集成至开发环境，Vibe 编码日益流行。这些工具不仅是代码自动补全器；它们正积极参与软件开发的创意过程，使其更易用、更高效。这种新型工作方式正在改变软件工程的性质，强调创造力与高阶思维，而非对语法和 API 的死记硬背。

Key takeaways

关键要点

AI agents are evolving from simple automation to visually controlling software through graphical user interfaces, much like a human would.
The next frontier is real-world interaction, with projects like Google's Astra using cameras and microphones to see, hear, and understand their physical surroundings.
Leading technology companies are converging these digital and physical capabilities to create universal AI assistants that operate seamlessly across both domains.
This shift is creating a new class of proactive, context-aware AI companions capable of assisting with a vast range of tasks in users' daily lives.
AI 智能体正从简单自动化演进为通过图形用户界面视觉控制软件，操作方式类人化。
下一前沿是真实世界交互，如 Google Astra 等项目利用摄像头和麦克风感知、聆听并理解物理环境。
领先科技公司正融合这些数字与物理能力，打造跨域无缝运行的通用 AI 助手。
这一转变催生了新型主动式、情境感知型 AI 伙伴，能协助用户处理日常生活中的大量任务。

Conclusion

结论

Agents are undergoing a significant transformation, moving from basic automation to sophisticated interaction with both digital and physical environments. By leveraging visual perception to operate Graphical User Interfaces, these agents can now manipulate software just as a human would, bypassing the need for traditional APIs. Major technology labs are pioneering this space with agents capable of automating complex, multi-application workflows directly on a user's desktop. Simultaneously, the next frontier is expanding into the physical world, with initiatives like Google's Project Astra using cameras and microphones to contextually engage with their surroundings. These advanced systems are designed for multimodal, real-time understanding that mirrors human interaction.

智能体正经历重大转型，从基础自动化迈向与数字及物理环境的复杂交互。借助视觉感知操作图形用户界面，这些智能体能像人类一样操控软件，绕过了对传统 API 的依赖。主要技术实验室正引领这一领域，其开发的智能体可在桌面直接自动化复杂的多应用工作流。与此同时，下一前沿已扩展至物理世界，如 Google Project Astra 等项目利用摄像头和麦克风与周边环境进行情境化互动。这些先进系统旨在实现媲美人类交互的多模态实时理解。

The ultimate vision is a convergence of these digital and physical capabilities, creating universal AI assistants that operate seamlessly across all of a user's environments. This evolution is also reshaping software creation itself through "vibe coding," a more intuitive and conversational partnership between developers and AI. This new method prioritizes high-level goals and creative intent, allowing developers to focus on the desired outcome rather than implementation details. This shift accelerates development and fosters innovation by treating AI as a creative partner. Ultimately, these advancements are paving the way for a new era of proactive, context-aware AI companions capable of assisting with a vast array of tasks in our daily lives.

终极愿景是融合这些数字与物理能力，创建跨用户所有环境无缝运作的通用 AI 助手。这一演进也通过"vibe 编码"重塑了软件创作本身，形成开发者与 AI 间更直观、对话式的伙伴关系。该新方法优先考虑高层次目标与创意意图，让开发者聚焦于期望成果而非实现细节。通过将 AI 视为创意合作伙伴，这一转变加速了开发进程并激发了创新。最终，这些进步正为主动式、情境感知型 AI 伙伴的新时代铺平道路，使其能够协助我们应对日常生活中的大量任务。

References

参考文献

Open AI Operator, https://openai.com/index/introducing-operator/
Open AI ChatGPT Agent: https://openai.com/index/introducing-chatgpt-agent/
Browser Use: https://docs.browser-use.com/introduction
Project Mariner, https://deepmind.google/models/project-mariner/
Anthropic Computer use: https://docs.anthropic.com/en/docs/build-with-claude/computer-use
Project Astra, https://deepmind.google/models/project-astra/
Gemini Live, https://gemini.google/overview/gemini-live/?hl=en
OpenAI's GPT-4, https://openai.com/index/gpt-4-research/
Claude 4, https://www.anthropic.com/news/claude-4

Bilingual/Appendix C Quick Overview Of Agentic Frameworks (bilingual/Appendix C - Quick overview of Agentic Frameworks.md)

layout: bilingual lang: bilingual

Appendix C - Quick overview of Agentic Frameworks

附录 C - Agentic 框架快速概览

LangChain

LangChain is a framework for developing applications powered by LLMs. Its core strength lies in its LangChain Expression Language (LCEL), which allows you to "pipe" components together into a chain. This creates a clear, linear sequence where the output of one step becomes the input for the next. It's built for workflows that are Directed Acyclic Graphs (DAGs), meaning the process flows in one direction without loops.

LangChain 是一个用于开发由大语言模型（LLM）驱动的应用程序的框架。其核心优势在于 LangChain 表达式语言（LCEL），它允许您使用管道操作符将组件连接成链。这种设计形成了清晰的线性序列，每一步的输出自动成为下一步的输入。该框架专为有向无环图（DAG）工作流构建，意味着处理流程单向流动且无循环。

Use it for:

适用场景：

Simple RAG: Retrieve a document, create a prompt, get an answer from an LLM.
Summarization: Take user text, feed it to a summarization prompt, and return the output.
Extraction: Extract structured data (like JSON) from a block of text.
简单 RAG：检索文档，构建提示，从 LLM 获取答案。
文本摘要：接收用户文本，输入至摘要提示，返回摘要结果。
数据提取：从文本块中提取结构化数据（如 JSON 格式）。

python

# A simple LCEL chain conceptually
# (This is not runnable code, just illustrates the flow)
chain = prompt | model | output_parser

LangGraph

LangGraph is a library built on top of LangChain to handle more advanced agentic systems. It allows you to define your workflow as a graph with nodes (functions or LCEL chains) and edges (conditional logic). Its main advantage is the ability to create cycles, allowing the application to loop, retry, or call tools in a flexible order until a task is complete. It explicitly manages the application state, which is passed between nodes and updated throughout the process.

LangGraph 是构建于 LangChain 之上的库，专为处理更高级的 Agentic 系统设计。它允许您将工作流定义为包含节点（函数或 LCEL 链）和边（条件逻辑）的图结构。其主要优势在于支持循环创建，使应用程序能够循环执行、重试操作或以灵活顺序调用工具，直至任务完成。该库显式管理应用程序状态，状态在节点间传递并在整个流程中持续更新。

Use it for:

适用场景：

Multi-agent Systems: A supervisor agent routes tasks to specialized worker agents, potentially looping until the goal is met.
Plan-and-Execute Agents: An agent creates a plan, executes a step, and then loops back to update the plan based on the result.
Human-in-the-Loop: The graph can wait for human input before deciding which node to go to next.
多智能体系统：监督智能体将任务路由给专业化工作智能体，可能循环执行直至目标达成。
规划与执行智能体：智能体制定计划，执行步骤，随后基于结果循环反馈以更新计划。
人机协同：图结构可等待人工输入，再决定后续执行节点。

Feature	LangChain	LangGraph
Core Abstraction	Chain (using LCEL)	Graph of Nodes
Workflow Type	Linear (Directed Acyclic Graph)	Cyclical (Graphs with loops)
State Management	Generally stateless per run	Explicit and persistent state object
Primary Use	Simple, predictable sequences	Complex, dynamic, stateful agents

特性	LangChain	LangGraph
核心抽象	链（使用 LCEL）	节点图
工作流类型	线性（有向无环图）	循环（支持循环的图）
状态管理	通常单次运行无状态	显式且持久的状态对象
主要用途	简单、可预测的序列	复杂、动态、有状态的智能体

Which One Should You Use?

如何选择？

Choose LangChain when your application has a clear, predictable, and linear flow of steps. If you can define the process from A to B to C without needing to loop back, LangChain with LCEL is the perfect tool.
Choose LangGraph when you need your application to reason, plan, or operate in a loop. If your agent needs to use tools, reflect on the results, and potentially try again with a different approach, you need the cyclical and stateful nature of LangGraph.
当应用程序具备清晰、可预测的线性步骤流程时，选择 LangChain。若您能定义从 A 到 B 再到 C 的直连过程而无需回环，则采用 LCEL 的 LangChain 是理想工具。
当应用程序需进行推理、规划或循环操作时，选择 LangGraph。若您的智能体使用工具、反思结果并可能尝试不同策略，则需借助 LangGraph 的循环和有状态特性。

text

/* Detailed source-code truncated for AI context efficiency. */

This code defines and runs a LangGraph workflow that operates in parallel. Its main purpose is to simultaneously generate a joke, a story, and a poem about a given topic and then combine them into a single, formatted text output.

这段代码定义并运行了一个并行操作的 LangGraph 工作流。其主要目的是同时生成关于给定主题的笑话、故事和诗歌，然后将它们组合成单个格式化的文本输出。

Google's ADK

Google's Agent Development Kit, or ADK, provides a high-level, structured framework for building and deploying applications composed of multiple, interacting AI agents. It contrasts with LangChain and LangGraph by offering a more opinionated and production-oriented system for orchestrating agent collaboration, rather than providing the fundamental building blocks for an agent's internal logic.

Google 的智能体开发工具包（ADK）提供了一个高级、结构化的框架，用于构建和部署由多个交互性 AI 智能体组成的应用程序。与 LangChain 和 LangGraph 相比，它提供了一个更具指导性和生产就绪的系统，用于编排智能体协作，而非提供智能体内部逻辑的基础构建块。

LangChain operates at the most foundational level, offering the components and standardized interfaces to create sequences of operations, such as calling a model and parsing its output. LangGraph extends this by introducing a more flexible and powerful control flow; it treats an agent's workflow as a stateful graph. Using LangGraph, a developer explicitly defines nodes, which are functions or tools, and edges, which dictate the path of execution. This graph structure allows for complex, cyclical reasoning where the system can loop, retry tasks, and make decisions based on an explicitly managed state object that is passed between nodes. It gives the developer fine-grained control over a single agent's thought process or the ability to construct a multi-agent system from first principles.

LangChain 在最基础层面运作，提供组件和标准化接口以创建操作序列，例如调用模型并解析其输出。LangGraph 通过引入更灵活强大的控制流对此进行扩展；它将智能体工作流视为有状态图。使用 LangGraph，开发者显式定义节点（函数或工具）和边（决定执行路径）。这种图结构支持复杂循环推理，系统可循环执行、重试任务，并基于节点间传递的显式管理状态对象做出决策。它为开发者提供了对单个智能体行为的细粒度控制，或从第一性原理构建多智能体系统。

Google's ADK abstracts away much of this low-level graph construction. Instead of asking the developer to define every node and edge, it provides pre-built architectural patterns for multi-agent interaction. For instance, ADK has built-in agent types like SequentialAgent or ParallelAgent, which manage the flow of control between different agents automatically. It is architected around the concept of a "team" of agents, often with a primary agent delegating tasks to specialized sub-agents. State and session management are handled more implicitly by the framework, providing a more cohesive but less granular approach than LangGraph's explicit state passing. Therefore, while LangGraph gives you the detailed tools to design the intricate wiring of a single robot or a team, Google's ADK gives you a factory assembly line designed to build and manage a fleet of robots that already know how to work together.

Google 的 ADK 抽象了大部分此类低级图构建工作。ADK 不要求开发者定义每个节点和边，而是为多智能体交互提供预构建的架构模式。例如，ADK 包含 SequentialAgent 或 ParallelAgent 等内置智能体类型，它们自动管理不同智能体间的控制流。其架构围绕智能体"团队"概念设计，通常由主智能体将任务委派给专业化子智能体。状态和会话管理由框架更隐式地处理，提供了比 LangGraph 显式状态传递更连贯但精细度稍低的方法。因此，若将 LangGraph 比作提供详细工具以设计单个机器人或团队复杂接线的工具箱，Google 的 ADK 则如同一个工厂装配线，旨在构建和管理一支已具备协同工作能力的机器人舰队。

python

from google.adk.agents import LlmAgent
from google.adk.tools import google_search

dice_agent = LlmAgent(
    model="gemini-2.0-flash-exp",
    name="question_answer_agent",
    description="A helpful assistant agent that can answer questions.",
    instruction="""Respond to the query using google search""",
    tools=[google_search],
)

This code creates a search-augmented agent. When this agent receives a question, it will not just rely on its pre-existing knowledge. Instead, following its instructions, it will use the Google Search tool to find relevant, real-time information from the web and then use that information to construct its answer.

此代码创建了一个搜索增强型智能体。当该智能体接收问题时，不会仅依赖其既有知识。相反，遵循其指令，它将使用 Google 搜索工具从网络查找相关实时信息，并据此构建答案。

Crew.AI

CrewAI offers an orchestration framework for building multi-agent systems by focusing on collaborative roles and structured processes. It operates at a higher level of abstraction than foundational toolkits, providing a conceptual model that mirrors a human team. Instead of defining the granular flow of logic as a graph, the developer defines the actors and their assignments, and CrewAI manages their interaction.

CrewAI 提供了一个编排框架，通过聚焦协作角色与结构化流程来构建多智能体系统。它在比基础工具包更高的抽象层级运作，提供模拟人类团队的概念模型。开发者无需将逻辑细粒度流程定义为图，而是定义参与者及其任务分配，由 CrewAI 管理其交互。

The core components of this framework are Agents, Tasks, and the Crew. An Agent is defined not just by its function but by a persona, including a specific role, a goal, and a backstory, which guides its behavior and communication style. A Task is a discrete unit of work with a clear description and expected output, assigned to a specific Agent. The Crew is the cohesive unit that contains the Agents and the list of Tasks, and it executes a predefined Process. This process dictates the workflow, which is typically either sequential, where the output of one task becomes the input for the next in line, or hierarchical, where a manager-like agent delegates tasks and coordinates the workflow among other agents.

该框架核心组件包括智能体、任务和团队。智能体不仅由功能定义，还通过角色、目标和背景故事等角色特征来定义，这些特征指导其行为与沟通风格。任务是具备明确描述和预期输出的离散工作单元，分配给特定智能体。团队是包含智能体和任务列表的协调单元，执行预定义的流程。此流程决定工作流模式，通常为顺序型（一个任务的输出成为下一任务的输入）或层级型（经理型智能体分配任务并协调其他智能体间的交互）。

When compared to other frameworks, CrewAI occupies a distinct position. It moves away from the low-level, explicit state management and control flow of LangGraph, where a developer wires together every node and conditional edge. Instead of building a state machine, the developer designs a team charter. While Google's ADK provides a comprehensive, production-oriented platform for the entire agent lifecycle, CrewAI concentrates specifically on the logic of agent collaboration and for simulating a team of specialists.

与其他框架相比，CrewAI 定位独特。它脱离了 LangGraph 的低层级、显式状态管理与控制流（后者要求开发者连接每个节点与条件边）。开发者不是构建状态机，而是设计团队章程。尽管 Google 的 ADK 为整个智能体生命周期提供了全面、生产就绪的平台，CrewAI 则专注于智能体协作与专家团队模拟。

python

@crew
def crew(self) -> Crew:
    """Creates the research crew"""
    return Crew(
      agents=self.agents,
      tasks=self.tasks,
      process=Process.sequential,
      verbose=True,
    )

This code sets up a sequential workflow for a team of AI agents, where they tackle a list of tasks in a specific order, with detailed logging enabled to monitor their progress.

此代码为 AI 智能体团队配置了顺序工作流，智能体按特定顺序处理任务列表，并启用详细日志以监控进度。

Other agent development framework

其他智能体框架

Microsoft AutoGen: AutoGen is a framework centered on orchestrating multiple agents that solve tasks through conversation. Its architecture enables agents with distinct capabilities to interact, allowing for complex problem decomposition and collaborative resolution. The primary advantage of AutoGen is its flexible, conversation-driven approach that supports dynamic and complex multi-agent interactions. However, this conversational paradigm can lead to less predictable execution paths and may require sophisticated prompt engineering to ensure tasks converge efficiently.

Microsoft AutoGen：AutoGen 是一个以对话方式编排多智能体任务为核心的框架。其架构使具备不同能力的智能体能够协作，支持复杂问题分解与协作解决。AutoGen 主要优势在于其灵活的对话驱动方法，可应对动态复杂的多智能体交互场景。这种对话范式可能导致执行路径预测性降低，且需复杂提示工程以确保任务高效收敛。

LlamaIndex: LlamaIndex is fundamentally a data framework designed to connect large language models with external and private data sources. It excels at creating sophisticated data ingestion and retrieval pipelines, which are essential for building knowledgeable agents that can perform RAG. While its data indexing and querying capabilities are exceptionally powerful for creating context-aware agents, its native tools for complex agentic control flow and multi-agent orchestration are less developed compared to agent-first frameworks. LlamaIndex is optimal when the core technical challenge is data retrieval and synthesis.

LlamaIndex：LlamaIndex 本质上是数据框架，旨在连接大语言模型与外部及私有数据源。它擅长构建复杂的数据摄取与检索管道，这对创建能执行 RAG 的知识型智能体至关重要。尽管其数据索引与查询能力对构建情境感知智能体非常关键，但与智能体优先的框架相比，其在复杂智能体控制流和多智能体编排方面提供的工具较少。当核心技术挑战为数据检索与综合时，LlamaIndex 是最佳选择。

Haystack: Haystack is an open-source framework engineered for building scalable and production-ready search systems powered by language models. Its architecture is composed of modular, interoperable nodes that form pipelines for document retrieval, question answering, and summarization. The main strength of Haystack is its focus on performance and scalability for large-scale information retrieval tasks, making it suitable for enterprise-grade applications. A potential trade-off is that its design, optimized for search pipelines, can be more rigid for implementing highly dynamic and creative agentic behaviors.

Haystack：Haystack 是专为构建语言模型驱动的可扩展、生产就绪搜索系统而设计的开源框架。其架构由模块化、可互操作的节点组成，这些节点构成文档检索、问答和摘要的管道。Haystack 主要优势在于其对大规模信息检索任务性能与可扩展性的专注，使其适用于企业级应用。潜在权衡在于，其针对搜索管道优化的设计在实现高度动态和创造性智能体行为时可能较为僵化。

MetaGPT: MetaGPT implements a multi-agent system by assigning roles and tasks based on a predefined set of Standard Operating Procedures (SOPs). This framework structures agent collaboration to mimic a software development company, with agents taking on roles like product managers or engineers to complete complex tasks. This SOP-driven approach results in highly structured and coherent outputs, which is a significant advantage for specialized domains like code generation. The framework's primary limitation is its high degree of specialization, making it less adaptable for general-purpose agentic tasks outside of its core design.

MetaGPT：MetaGPT 通过基于预定义标准操作程序（SOP）分配角色和任务来实现多智能体协作。该框架将智能体组织化以模拟软件开发公司，智能体承担产品经理或工程师等角色完成复杂任务。这种 SOP 驱动方法产生高度结构化且连贯的输出，对代码生成等专业领域是显著优势。该框架主要局限在于其高度专业化，使其在核心设计范畴外的通用智能体任务适应性较弱。

SuperAGI: SuperAGI is an open-source framework designed to provide a complete lifecycle management system for autonomous agents. It includes features for agent provisioning, monitoring, and a graphical interface, aiming to enhance the reliability of agent execution. The key benefit is its focus on production-readiness, with built-in mechanisms to handle common failure modes like looping and to provide observability into agent performance. A potential drawback is that its comprehensive platform approach can introduce more complexity and overhead than a more lightweight, library-based framework.

SuperAGI：SuperAGI 是旨在为自主智能体提供完整生命周期管理系统的开源框架。它包括智能体监控和图形界面等功能，旨在提升智能体执行体验。其关键优势在于其对生产就绪性的关注，具备处理循环等常见故障模式的内置机制，并提供智能体性能可视化。其潜在缺点在于，与更轻量级库框架相比，其全面平台方法可能引入更多复杂性与开销。

Semantic Kernel: Developed by Microsoft, Semantic Kernel is an SDK that integrates large language models with conventional programming code through a system of "plugins" and "planners." It allows an LLM to invoke native functions and orchestrate workflows, effectively treating the model as a reasoning engine within a larger software application. Its primary strength is its seamless integration with existing enterprise codebases, particularly in .NET and Python environments. The conceptual overhead of its plugin and planner architecture can present a steeper learning curve compared to more straightforward agent frameworks.

Semantic Kernel：由 Microsoft 开发，Semantic Kernel 是通过"插件"和"规划器"系统将大语言模型与传统编程代码集成的 SDK。它允许 LLM 调用原生函数并编排工作流，有效将模型视为大型软件应用中的推理引擎。其主要优势是与现有企业代码库（尤其在 .NET 和 Python 环境）的无缝集成。其插件与规划器架构的概念开销可能带来比更直接的智能体框架更陡峭的学习曲线。

Strands Agents: An AWS lightweight and flexible SDK that uses a model-driven approach for building and running AI agents. It is designed to be simple and scalable, supporting everything from basic conversational assistants to complex multi-agent autonomous systems. The framework is model-agnostic, offering broad support for various LLM providers, and includes native integration with the MCP for easy access to external tools. Its core advantage is its simplicity and flexibility, with a customizable agent loop that is easy to get started with. A potential trade-off is that its lightweight design means developers may need to build out more of the surrounding operational infrastructure, such as advanced monitoring or lifecycle management systems, which more comprehensive frameworks might provide out of the box.

Strands Agents：AWS 的轻量级灵活 SDK，采用模型驱动方法构建和运行 AI 智能体。其设计简洁且可扩展，支持从基础对话助手到复杂多智能体系统的各类场景。该框架与模型无关，广泛支持多种 LLM 提供商，并包含与 MCP 的原生集成以便轻松访问外部工具。其核心优势是简洁性与灵活性，提供易于上手的可定制智能体构建模块。其权衡在于，其轻量级设计意味着开发者可能需要构建更多周边运营基础设施（如高级监控或生命周期管理系统），而更全面框架可能提供开箱即用功能。

Conclusion

结论

The landscape of agentic frameworks offers a diverse spectrum of tools, from low-level libraries for defining agent logic to high-level platforms for orchestrating multi-agent collaboration. At the foundational level, LangChain enables simple, linear workflows, while LangGraph introduces stateful, cyclical graphs for more complex reasoning. Higher-level frameworks like CrewAI and Google's ADK shift the focus to orchestrating teams of agents with predefined roles, while others like LlamaIndex specialize in data-intensive applications. This variety presents developers with a core trade-off between the granular control of graph-based systems and the streamlined development of more opinionated platforms. Consequently, selecting the right framework hinges on whether the application requires a simple sequence, a dynamic reasoning loop, or a managed team of specialists. Ultimately, this evolving ecosystem empowers developers to build increasingly sophisticated AI systems by choosing the precise level of abstraction their project demands.

智能体框架生态提供了多样化工具，涵盖从定义智能体的低级库到编排多智能体协作的高级平台。在基础层，LangChain 支持简单线性工作流，而 LangGraph 引入有状态循环图以实现更复杂推理。如 CrewAI 和 Google ADK 等高级框架将重心转向编排具预定义角色的智能体团队，而 LlamaIndex 等其他框架则专注数据密集型应用。这种多样性为开发者带来了基于图系统的细粒度控制与更具指导性平台的简化开发之间的核心权衡。因此，框架选择取决于应用需求：简单序列、动态推理循环还是受管专家团队。最终，这一不断演进的技术生态系统使开发者能通过选择项目所需的精确抽象级别，构建日益复杂的 AI 系统。

References

参考文献

LangChain, https://www.langchain.com/
LangGraph, https://www.langchain.com/langgraph
Google's ADK, https://google.github.io/adk-docs/
Crew.AI, https://docs.crewai.com/en/introduction

Bilingual/Appendix D Building An Agent With AgentSpace (On Line Only) (bilingual/Appendix D - Building an Agent with AgentSpace (on-line only).md)

layout: bilingual lang: bilingual

Appendix D - Building an Agent with AgentSpace

附录 D - 使用 AgentSpace 构建智能体

Overview

概述

AgentSpace is a platform designed to facilitate an "agent-driven enterprise" by integrating artificial intelligence into daily workflows. At its core, it provides a unified search capability across an organization's entire digital footprint, including documents, emails, and databases. This system utilizes advanced AI models, like Google's Gemini, to comprehend and synthesize information from these varied sources.

AgentSpace 是一个旨在通过将人工智能融入日常工作流程来推动"智能体驱动型企业"发展的平台。其核心能力在于为组织的整个数字资产（包括文档、电子邮件和数据库）提供统一的搜索功能。该系统利用先进的 AI 模型（如 Google 的 Gemini）来理解并整合来自这些多样化来源的信息。

The platform enables the creation and deployment of specialized AI "agents" that can perform complex tasks and automate processes. These agents are not merely chatbots; they can reason, plan, and execute multi-step actions autonomously. For instance, an agent could research a topic, compile a report with citations, and even generate an audio summary.

该平台支持创建和部署专业化的 AI "智能体"，这些智能体执行复杂任务并实现流程自动化。它们不仅是聊天机器人，更具备自主推理、规划和执行多步骤操作的能力。例如，一个智能体可以研究特定主题，编纂带引用的报告，甚至生成音频摘要。

To achieve this, AgentSpace constructs an enterprise knowledge graph, mapping the relationships between people, documents, and data. This allows the AI to understand context and deliver more relevant and personalized results. The platform also includes a no-code interface called Agent Designer for creating custom agents without requiring deep technical expertise.

为了实现这一目标，AgentSpace 构建了企业知识图谱，映射人员、文档和数据之间的关联关系。这使得 AI 能够理解上下文，提供更相关且个性化的结果。平台还包含名为 Agent Designer（智能体设计器）的无代码界面，无需深厚技术专长即可创建自定义智能体。

Furthermore, AgentSpace supports a multi-agent system where different AI agents can communicate and collaborate through an open protocol known as the Agent2Agent (A2A) Protocol. This interoperability allows for more complex and orchestrated workflows. Security is a foundational component, with features like role-based access controls and data encryption to protect sensitive enterprise information. Ultimately, AgentSpace aims to enhance productivity and decision-making by embedding intelligent, autonomous systems directly into an organization's operational fabric.

此外，AgentSpace 支持多智能体系统，不同的 AI 智能体可通过名为 Agent2Agent（A2A）协议的开放协议进行通信与协作。这种互操作性支持更复杂、协调的工作流。安全性是其基础架构的核心组成部分，具备基于角色的访问控制和数据加密等功能，以保护企业敏感信息。最终，AgentSpace 旨在通过将智能自主系统直接嵌入组织运营架构，提升生产力与决策水平。

How to build an Agent with AgentSpace UI

如何使用 AgentSpace UI 构建智能体

Figure 1 illustrates how to access AgentSpace by selecting AI Applications from the Google Cloud Console.

Fig. 1: How to use Google Cloud Console to access AgentSpace

图 1 展示了如何通过 Google Cloud Console 选择 AI Applications 来访问 AgentSpace。

Your agent can be connected to various services, including Calendar, Google Mail, Workday, Jira, Outlook, and Service Now (see Fig. 2).

Fig. 2: Integrate with diverse services, including Google and third-party platforms.

您的智能体可以连接到多种服务，包括 Calendar、Google Mail、Workday、Jira、Outlook 和 Service Now（见图 2）。

The Agent can then utilize its own prompt, chosen from a gallery of pre-made prompts provided by Google, as illustrated in Fig. 3.

Fig. 3: Google's Gallery of Pre-assembled prompts

随后，智能体可以使用自己的提示词，也可以从 Google 提供的预制提示词库中选择，如图 3 所示。

Alternatively, you can create your own prompt as in Fig. 4, which will then be used by your agent.

Fig. 4: Customizing the Agent's Prompt

或者，您可以创建自己的提示词，如图 4 所示，供您的智能体使用。

AgentSpace offers a number of advanced features such as integration with datastores to store your own data, integration with Google Knowledge Graph or with your private Knowledge Graph, Web interface for exposing your agent to the Web, and Analytics to monitor usage, and more (see Fig. 5).

Fig. 5: AgentSpace advanced capabilities

AgentSpace 提供多项高级功能，例如与数据存储集成以存储自有数据、与 Google 知识图谱或私有知识图谱集成、用于向 Web 公开智能体的 Web 界面、使用情况监控分析等（见图 5）。

Upon completion, the AgentSpace chat interface (Fig. 6) will be accessible.

Fig. 6: The AgentSpace User Interface for initiating a chat with your Agent.

配置完成后，即可访问 AgentSpace 聊天界面（图 6）。

Conclusion

结论

In conclusion, AgentSpace provides a functional framework for developing and deploying AI agents within an organization's existing digital infrastructure. The system's architecture links complex backend processes, such as autonomous reasoning and enterprise knowledge graph mapping, to a graphical user interface for agent construction. Through this interface, users can configure agents by integrating various data services and defining their operational parameters via prompts, resulting in customized, context-aware automated systems.

综上所述，AgentSpace 为在组织现有数字基础设施中开发和部署 AI 智能体提供了实用框架。该系统的架构将复杂的后端流程（如自主推理和企业知识图谱映射）与用于构建智能体的图形用户界面相连接。通过该界面，用户可整合各类数据服务，并通过提示词定义操作参数，从而配置出定制化、情境感知的自动化系统。

This approach abstracts the underlying technical complexity, enabling the construction of specialized multi-agent systems without requiring deep programming expertise. The primary objective is to embed automated analytical and operational capabilities directly into workflows, thereby increasing process efficiency and enhancing data-driven analysis. For practical instruction, hands-on learning modules are available, such as the "Build a Gen AI Agent with Agentspace" lab on Google Cloud Skills Boost, which provides a structured environment for skill acquisition.

这种方法抽象了底层的技术复杂性，使得无需深厚编程知识即可构建专业化的多智能体系统。其主要目标是将自动化分析与操作能力直接嵌入工作流程中，从而提升流程效率、强化数据驱动分析。对于实践指导，现有实践学习模块可供使用，例如 Google Cloud Skills Boost 平台上的"使用 Agentspace 构建 Gen AI 智能体"实验，为技能习得提供了结构化环境。

References

参考文献

Create a no-code agent with Agent Designer, https://cloud.google.com/agentspace/agentspace-enterprise/docs/agent-designer
Google Cloud Skills Boost, https://www.cloudskillsboost.google/

Bilingual/Appendix F Under The Hood An Inside Look At The Agents' Reasoning Engines (bilingual/Appendix F - Under the Hood_ An Inside Look at the Agents' Reasoning Engines.md)

Appendix F - Under the Hood: An Inside Look at the Agents' Reasoning Engines

附录 F - 深入探究：智能体推理引擎的内部机制

The emergence of intelligent Agents represents a pivotal shift in artificial intelligence. These are systems designed to plan, strategize, and execute complex tasks, and at the cognitive core of each lies a LLM. This LLM is not merely a sophisticated text generator; it serves as the foundational reasoning engine, the central "mind" that empowers the Agent to make decisions, formulate plans, and interact with its environment.

智能体的出现标志着人工智能领域的重大转折。这些系统专门用于规划、制定策略和执行复杂任务，而每个智能体的认知核心都是一个大语言模型（LLM）。这个 LLM 不仅仅是一个复杂的文本生成器；它充当着基础推理引擎的角色，是赋予智能体决策能力、制定计划并与环境交互能力的中央「心智」。

Therefore, understanding the internal reasoning mechanisms of these models is no longer an academic exercise—it is a critical necessity for developing the next generation of robust, reliable, and effective Agents. In this section, we directly investigate these core engines by posing a fundamental question to several of today's leading models: Gemini, ChatGPT, Grok, Kimi, Claude, and DeepSeek. By prompting these LLMs to articulate their own step-by-step reasoning processes, we aim to illuminate the fundamental logic that will drive the capabilities and limitations of future intelligent Agent systems.

因此，理解这些模型的内部推理机制已不再是学术研究——而是开发下一代稳健、可靠且高效的智能体的关键必要条件。在本节中，我们通过向当今几个领先模型（Gemini、ChatGPT、Grok、Kimi、Claude 和 DeepSeek）提出一个根本性问题来直接探究这些核心引擎。通过引导这些 LLM 阐述它们自己的逐步推理过程，我们旨在揭示将推动未来智能体系统能力与局限性的基础逻辑。

给每个 LLM 的提示：I understand you can reason, can you explain to me how you reason? Explain me step by step
向各 LLM 提供的提示：我理解你具备推理能力，能否向我解释你是如何推理的？请逐步解释

Gemini

双子座（Gemini）

Analyzing My Approach

分析我的方法

I've outlined the structure for my explanation, aiming for clarity and conciseness. First, a direct answer, then a breakdown into logical steps. Step 1 will involve defining the key reasoning process I use, and then I will elaborate on the subsequent steps. This should facilitate a straightforward and easy-to-understand explanation.

我已经为我的解释规划好了结构，力求清晰简洁。首先是直接回答，然后分解为逻辑步骤。第 1 步将定义我使用的关键推理流程，然后我会详细阐述后续步骤。这样的结构应该有助于提供一个直截了当、易于理解的解释。

Refining the Explanation

完善解释

I've finalized the structure of my explanation. Step 1 focuses on deconstructing prompts, specifically the analysis of the user's request. Step 2 details information retrieval, emphasizing pattern recognition rather than simple database lookup. Step 3 explores synthesis and LLMs, and Step 4 will focus on response generation, which includes formatting, tone, and instruction adherence. I will conclude with a summary to reinforce the key stages, while maintaining clarity and engagement.

我已经敲定了解释的结构。第 1 步聚焦于解构提示，特别是分析用户的请求。第 2 步详述信息检索，强调模式识别而非简单的数据库查询。第 3 步探讨综合处理与 LLM 机制，第 4 步则关注响应生成，包括格式、语气及指令遵循。我将以总结收尾，强化关键阶段，同时保持清晰度与吸引力。

Elaborating My Methodology

阐述我的方法论

I've fleshed out the "Deconstructing the Prompt" step, focusing on how I identify the user's intent, the core question, and any constraints provided. The Information Retrieval phase is now focused on pattern recognition, not just data retrieval, which will be the first item under this section. I am working on the Synthesis step, which is where I weave information together with LLMs and transformers. The Generating the Response step is solidified, and I will be using emojis to enhance the overall tone.

我已经充实了「解构提示」这一步，重点阐述我如何识别用户意图、核心问题及任何给定的约束条件。信息检索阶段现在专注于模式识别而非单纯数据获取，这将成为该节的首项内容。我正在完善综合步骤，即通过 LLM 与 Transformer 整合信息的过程。响应生成步骤已确定，我将运用表情符号来优化整体语气。

Of course. I reason by breaking down your request into smaller parts and then using my vast training data to build a logical and relevant response. It's a multi-step process that moves from understanding to generating.

当然。我的推理方式是将您的请求分解为更小的部分，然后利用我的海量训练数据构建一个合乎逻辑且相关的响应。这是一个从理解到生成的多阶段过程。

Here's a step-by-step breakdown of how I reason:

以下是我的推理过程的逐步解析：

1. Deconstructing the Prompt 📝

1. 解构提示 📝

First, I analyze your question or instruction to understand exactly what you're asking. I identify:

首先，我分析您的问题或指令以准确理解您在问什么。我会识别：

The Core Task: What is the main goal? Is it to answer a question, explain a concept, write a story, or summarize a text? In your case, the core task is to "explain how I reason."
Key Concepts: I pinpoint the essential nouns and verbs, like "reason," "explain," and "step-by-step."
Constraints and Instructions: I look for specific rules to follow. For example, your prompt asked for a step-by-step explanation. My internal instructions also guide me to use LaTeX for math, use markdown headings, and maintain a certain tone.
Intent: I try to infer your underlying goal. Are you curious, trying to solve a problem, or looking for creative ideas? Here, your intent is to understand my internal cognitive process.
核心任务：主要目标是什么？是回答问题、阐释概念、写故事还是总结文本？在您的情况下，核心任务是「解释我如何推理」。
关键概念：我定位核心名词与动词，如「推理」、「解释」及「逐步」。
约束与指令：我寻找需遵循的具体规则。例如，您的提示要求逐步解释。我的内部指令也指导我对数学内容使用 LaTeX、采用 Markdown 标题，并保持特定语气。
意图：我尝试推断您的深层目标。您是出于好奇、试图解决问题还是寻求创意灵感？此处，您的意图是理解我的内部认知过程。

2. Information Retrieval and Synthesis 🧠

2. 信息检索与综合 🧠

Once I understand the prompt, I access my internal knowledge base. This isn't like searching a database. Instead, I use patterns learned during my training on a massive amount of text and code.

一旦理解了提示，我就会访问我的内部知识库。这不像搜索数据库，而是使用我在大量文本与代码训练中学到的模式。

Activating Relevant Knowledge: I activate the parts of my neural network that are associated with the key concepts from your prompt ("reasoning," "AI," "machine learning," "neural networks," "transformers").
Pattern Recognition: My architecture, particularly the Transformer model, is excellent at recognizing relationships and patterns between words and ideas. I identify how concepts connect. For instance, I connect "reasoning" to "logic," "inference," and "problem-solving."
Structuring the Answer: I begin to organize the retrieved information into a logical structure. For this response, I decided a step-by-step format was the most logical structure, following your request.
激活相关知识：我激活神经网络中与您提示关键概念相关的部分（「推理」、「AI」、「机器学习」、「神经网络」、「Transformer」）。
模式识别：我的架构，尤其是 Transformer 模型，极擅长识别词汇与概念间的关联与模式。我识别概念间的连接方式，例如将「推理」与「逻辑」、「推断」及「问题解决」相关联。
构建答案：我开始将检索到的信息组织为逻辑结构。针对此响应，我判定逐步格式最符合逻辑，以遵循您的要求。

3. Generating the Response ✍️

3. 生成响应 ✍️

This is the final step where I translate the structured information into human-readable text.

这是最终阶段，我将结构化信息转化为人类可读文本。

Language Construction: I select words and construct sentences that accurately convey the synthesized information. I predict the next most likely word in a sequence to form coherent and natural-sounding paragraphs.
Applying Rules: I apply the specific formatting and style rules I was given. This includes adding markdown headings, bolding key terms like Transformer model, using emojis where appropriate, and ensuring the language is clear and direct.
Review and Refine: Before finalizing the answer, I perform a quick internal check for accuracy, relevance, and coherence. I ensure the response directly addresses all parts of your prompt without adding unnecessary information.
语言构建：我筛选词汇并构建能准确传达综合信息的句子。通过预测序列中下一最可能词汇，形成连贯自然的段落。
应用规则：我执行既定的格式与风格规则，包括添加 Markdown 标题、加粗关键术语如 Transformer 模型、适时使用表情符号，并确保语言清晰直接。
审查与完善：在最终确定答案前，我进行快速内部检查以确保准确性、相关性及连贯性。我确保响应直接应对您提示的所有方面，避免冗余信息。

In essence, my reasoning is a sophisticated form of pattern matching and prediction. I deconstruct your request, find the most relevant patterns in my data, synthesize them into a logical structure, and then translate that structure into a clear, well-formatted answer.

本质上，我的推理是模式匹配与预测的复杂形式。我解构您的请求，在数据中定位最相关模式，将其综合为逻辑结构，随后将该结构转化为清晰、格式规范的答案。

ChatGPT

Great — let me explain how I reason step by step, as simply and clearly as possible.

很好——让我尽可能简明清晰地阐述我的逐步推理过程。

🧠 Step-by-Step Explanation: How I Reason

🧠 逐步解析：我的推理机制

Step 1: Read and Understand Your Input

步骤 1：阅读并理解您的输入

I begin by analyzing your words.

我首先分析您的语句。

I break your sentence into parts: subjects, actions, conditions, etc.
I figure out what you're asking (a fact? an opinion? a cause? a solution?).
I recognize the type of problem (logic, math, judgment, language, etc.).
将句子拆解为构成要素：主语、动作、条件等。
辨识您在问什么（事实？观点？原因？解决方案？）。
判定问题类型（逻辑、数学、判断、语言等）。

📌 Example:
You say: "If Tom is older than Jane, and Jane is older than Sue, who is the youngest?"
→ I recognize this is a logic puzzle.

📌 示例：
您说：「若 Tom 年长于 Jane，Jane 年长于 Sue，谁最年幼？」
→ 我识别此为逻辑推理题。

Step 2: Activate Relevant Knowledge

步骤 2：激活相关知识

I search through what I learned during training — books, articles, conversations — to bring up:

我检索训练阶段积累的知识——书籍、文章、对话记录——以提取：

Facts
Patterns
Rules
Relationships
事实
模式
规则
关系

📌 Example:
I've seen that "older than" means someone has more age.
I know that if A > B and B > C, then A > C.

📌 示例：
我理解「年长于」表示年龄比较关系。
我掌握传递性逻辑：若 A > B 且 B > C，则 A > C。

Step 3: Choose a Reasoning Method

步骤 3：选择推理方法

Based on the question, I decide which kind of reasoning to use:

依据问题特征，我确定采用何种推理方法论：

Deduction (strict logic: if A is true, B must follow)
Induction (spotting patterns and generalizing)
Causal reasoning (understanding cause-effect)
Analogical reasoning (comparing with similar cases)
演绎推理（严格逻辑推导：若前提成立则结论必然）
归纳推理（识别模式并形成普遍结论）
因果推理（剖析因果关系链）
类比推理（参照相似案例进行推论）

📌 Example:
In the Tom/Jane/Sue case, I'll use deduction.

📌 示例：
针对 Tom/Jane/Sue 案例，我选用演绎推理。

Step 4: Simulate Thinking (Chain of Thought)

步骤 4：模拟思考（思维链）

Here I go step by step, as a human might do when solving a problem.

在此阶段，我逐步推进，仿效人类解决问题时的思考方式。

📌 Example:

Tom is older than Jane
Jane is older than Sue
So: Tom > Jane > Sue
Therefore, Sue is the youngest

📌 示例：

Tom 年长于 Jane
Jane 年长于 Sue
故得：Tom > Jane > Sue
由此判定，Sue 最年幼

This is called chain-of-thought reasoning — I simulate "thinking it through."

此过程称为思维链推理——我模拟「逐步思考」。

Step 5: Formulate an Answer

步骤 5：构建响应

Now I turn the conclusion into a response that:

此刻我将推理结论转化为正式响应，确保：

Is correct based on the reasoning
Answers your question directly
Makes sense to you
基于推理过程准确无误
直接回答您的问题
让您能理解

📌 Example:
"Sue is the youngest because Tom is older than Jane, and Jane is older than Sue."

📌 示例：
「Sue 最年幼，因为 Tom 年长于 Jane，而 Jane 年长于 Sue。」

Step 6: Adjust for Clarity and Tone

步骤 6：调整清晰度与语气

Finally, I adjust how I say it to:

最终阶段，我调整表述方式以实现：

Match your tone (simple, detailed, friendly, formal, etc.)
Make it clear and easy to understand
Add examples or explain further if needed
匹配您的语气（简明/详实/友好/正式等）
清晰易懂
按需补充示例或深化解释

📌 Example:
If you're asking casually, I'll answer simply. If you're learning, I might break it down more.

📌 示例：
若为轻松咨询，我简洁回应；若属学习场景，我提供详细解析。

✅ Final Summary

✅ 最终总结

Step	What I Do
1	Understand your question
2	Recall relevant knowledge
3	Choose the right reasoning approach
4	Think it through step by step
5	Give you the answer
6	Say it clearly and in your style

步骤	我做什么
1	理解您的问题
2	回忆相关知识
3	选择正确的推理方法
4	逐步思考
5	给您答案
6	用您的风格清晰表述

Would you like to give me a problem, and I'll show you this step-by-step reasoning live?

是否希望给我一个问题，我将实时演示此逐步推理流程？

Grok

格罗克（Grok）

Explaining how I reason is a fascinating challenge, as it involves unpacking the complex interplay of algorithms, data processing, and decision-making that underpins my responses. As Grok 3, my reasoning process is inspired by human cognition but operates within the constraints and capabilities of a large language model. Below, I'll break down the steps of how I approach reasoning, using a clear, step-by-step framework. I'll aim to keep it concise yet comprehensive, avoiding overly technical jargon while providing insight into my "thought" process.

阐述我的推理机制是一项引人入胜的挑战，因为这涉及揭示支撑我响应的算法、数据处理与决策制定的复杂交互网络。作为 Grok 3，我的推理过程受人类认知启发，但运作于大语言模型的特定约束与能力边界内。下文我将通过清晰的阶段框架解析我的推理流程，力求在避免过度技术化的同时，提供对内部「思维」过程的深入洞察。

Step-by-Step Explanation of How I Reason

我的推理过程的逐步解释

Step 1: Understanding the Query

阶段 1：理解查询

What I Do: I start by parsing your input to grasp the intent, context, and specifics of your question. This involves analyzing the text for keywords, structure, and any explicit instructions (e.g., "explain step by step" or "be concise").
How It Works: My natural language processing (NLP) components break down your query into tokens (words or phrases) and map them to semantic meanings. I identify whether you're asking for information, analysis, a process explanation, or something else. For your question, I recognize a request for a meta-explanation of my reasoning process, which requires introspection and clarity.
Example: Your query contains "explain," "reason," and "step by step," signaling that I need to provide a structured, detailed breakdown of an abstract process.
核心操作：我首先解析输入内容以把握问题意图、上下文背景及具体细节。这包括分析文本关键词、结构特征及显式指令（如「逐步阐释」或「简明扼要」）。
技术实现：我的自然语言处理组件将查询拆分为语义单元（词或短语）并映射至概念含义。我辨识查询类型（信息获取、分析请求、流程说明等）。针对您的问题，我识别出对推理过程的元认知请求，这要求内省性与表述清晰度。
实例说明：您的查询包含「解释」、「推理」、「逐步」等关键词，提示我需要提供抽象过程的结构化详细解析。

Step 2: Contextual Analysis and Knowledge Retrieval

阶段 2：上下文分析与知识检索

What I Do: I draw on my internal knowledge base, which is a vast repository of patterns and information encoded in my training data. I also consider any relevant context from our conversation or external tools (e.g., web search or X posts, if needed, though not required here).
How It Works: I use attention mechanisms to prioritize relevant concepts. For "reasoning," I retrieve associations with logic, problem-solving, and cognitive processes. Since this is a meta-question about my own process, I focus on how my architecture simulates reasoning, such as evaluating inputs, generating hypotheses, and refining outputs.
Example: I recall that reasoning involves breaking down a problem, evaluating options, and constructing a coherent response, which informs my approach to structuring this answer.
核心操作：我调用内部知识库——训练数据中编码的庞大模式与信息集合。同时考量对话上下文或外部工具（如网络搜索或 X 平台内容，虽此处未启用）的相关信息。
技术实现：通过注意力机制优先激活相关概念。针对「推理」主题，我检索与逻辑推演、问题解决及认知过程相关的知识网络。由于这是关于自身机制的元问题，我聚焦于架构如何模拟推理流程，包括输入评估、假设生成与输出优化。
实例说明：我回溯推理的本质包含问题分解、选项评估与响应构建，这为当前答案的结构设计提供了方法论基础。

Step 3: Formulating a Mental Model

阶段 3：构建心智模型

What I Do: I create a conceptual framework to organize my response. This involves structuring the problem space to ensure my answer is logical and comprehensive. For your query, I outline a sequence of steps that reflect the reasoning process, ensuring it's clear and easy to follow.
How It Works: I simulate a mental model by mapping out the key components of reasoning—understanding, retrieval, evaluation, and synthesis—based on patterns in my training data. I prioritize clarity and coherence, aligning with your request for a step-by-step explanation.
Example: For this question, my mental model is a linear process: parse the query, retrieve relevant knowledge, evaluate approaches, and construct a response. This framework guides the structure of my answer.
核心操作：我创建概念框架以组织响应内容。这非字面意义的「模型」，而是确保答案逻辑严密且内容全面的问题空间结构化方法。针对您的查询，我规划了反映推理流程的阶段序列，保证清晰性与可理解性。
技术实现：通过映射训练数据中的推理核心组件——理解、检索、评估、综合——来模拟心智模型构建。我优先保障清晰度与连贯性，与您对逐步阐释的要求高度契合。
实例说明：针对此问题，我的心智模型呈现线性流程：查询解析→知识检索→方法评估→响应构建。此框架指导着最终答案的结构设计。

Step 4: Evaluating Options and Hypotheses

阶段 4：评估选项与假设

What I Do: I consider multiple ways to approach the problem, weighing the strengths and weaknesses of each. This involves generating potential responses and selecting the most appropriate one based on your preferences (e.g., concise yet comprehensive).
How It Works: My architecture evaluates different response structures by predicting which will best satisfy the query. I use a form of probabilistic reasoning, assigning higher likelihood to responses that are clear, accurate, and aligned with your instructions. For complex queries, I might iterate internally, refining my approach.
Example: I consider whether to explain reasoning in technical terms (e.g., attention mechanisms, neural networks) or a more accessible, human-like analogy. Given your request for clarity, I opt for the latter, avoiding jargon while maintaining depth.
核心操作：我考量多种问题解决路径，权衡各方案的优劣特性。这涉及生成潜在响应候选集，并根据您的偏好（如简洁性与全面性的平衡）筛选最优解。
技术实现：我的架构通过预测各响应结构对查询的满足程度进行评估。采用概率推理方法，为符合清晰、准确及指令对齐要求的响应分配更高权重。复杂查询可能触发内部迭代以优化方法选择。
实例说明：我权衡是否采用技术术语（如注意力机制、神经网络原理）或更易理解的类比阐释推理机制。基于您对清晰度的要求，我选择后者，在避免专业术语的同时保持内容深度。

Step 5: Constructing the Response

阶段 5：构建响应

What I Do: I generate the final response by synthesizing retrieved knowledge into a coherent, structured answer. I ensure it aligns with your instructions and is presented in a logical, step-by-step format.
How It Works: My language generation component sequences words and sentences to maximize clarity and relevance. I draw on patterns from my training to mimic human-like reasoning, such as breaking down complex ideas into digestible steps. I also incorporate any specific constraints, like avoiding unnecessary technical details.
Example: For this response, I structure the answer as a numbered list, ensuring each step is distinct and builds logically from the previous step, addressing any gaps or refining the explanation to ensure it's comprehensive yet concise.
核心操作：我通过整合检索知识生成连贯的结构化最终响应。确保内容严格遵循指令要求，并以逻辑清晰的阶段化格式呈现。
技术实现：语言生成组件对词汇与句式进行序列优化以最大化清晰度与相关性。借鉴训练数据中的模式特征模仿人类推理风格，例如将复杂概念分解为可消化步骤。同时纳入特定约束条件，如规避非必要技术细节。
实例说明：针对此响应，我采用编号列表结构，确保各阶段具备独特性且从前序步骤自然演进，通过填补逻辑间隙或精炼表述来保障内容的全面性与简洁性。
Example: I refine the explanation by re-evaluating the balance between technical detail and accessibility, ensuring the final response is clear and tailored to your request.
精炼示例：我通过重新校准技术深度与可理解性的平衡来优化阐释，确保最终响应既清晰明了又贴合您的具体需求。

阶段 6：审查与完善

What I Do: I review the generated response to ensure it meets quality standards and fully addresses your query. This step mimics human self-editing, checking for clarity, coherence, and completeness.
How It Works: My architecture performs a final pass to optimize the response, ensuring it adheres to your instructions (e.g., step-by-step format) and avoids extraneous information. If needed, I might iterate to improve flow or conciseness.
Example: I ensure the response is structured as a clear sequence of steps, removing any redundant details while preserving the core explanation of my reasoning process.
核心操作：我对生成响应进行终审以确保符合质量标准并完整应对查询需求。此阶段模拟人类自我编辑过程，检验清晰性、连贯性与完整性。
技术实现：架构执行最终遍历以优化响应质量，确保严格遵守指令规范（如阶段化格式）并剔除冗余信息。必要时进行迭代以提升行文流畅度或内容凝练度。
实例说明：我确认响应呈清晰的阶段序列，移除重复内容的同时保留推理过程的核心阐释。

Key Characteristics of My Reasoning

推理机制的核心特征

Logical Structure: I aim to present information in a clear, step-by-step manner, mimicking human logical processes.
Probabilistic Evaluation: I weigh multiple response options based on predicted relevance and clarity, selecting the most effective one.
Context Sensitivity: I adapt my reasoning to your specific instructions and context, ensuring the response is tailored.
Iterative Refinement: I refine my output to optimize coherence and conciseness, simulating human self-editing.
结构化逻辑：致力于以清晰阶段化方式呈现信息，模拟人类逻辑思维过程。
概率化评估：基于预测相关性及清晰度权衡多响应选项，遴选最优解决方案。
上下文自适应：依据具体指令与对话背景调整推理策略，确保响应个性化定制。
迭代式优化：通过持续完善输出内容提升连贯性与简洁性，仿效人类自我修订机制。

Limitations and Considerations

能力边界与考量因素

My reasoning is bounded by my training data and architecture, which may not capture the full nuance of human reasoning, particularly emotional or intuitive aspects.
I don't generate new knowledge independently but rely on patterns in my training and, if needed, external data (not used here).
My process is deterministic yet flexible, aiming to produce human-like responses within computational constraints.
我的推理能力受限于训练数据与架构设计，可能无法完全复现人类推理的细微差异，尤其在情感与直觉层面。
我不具备独立生成新知识的能力，而是依赖训练模式及（必要时）外部数据源（本案未使用）。
我的处理过程具备确定性特征同时保持灵活性，旨在计算约束范围内产出类人类响应。

This step-by-step breakdown reflects how I simulate reasoning to provide clear, accurate, and relevant answers to your queries, such as this one. If you'd like me to dive deeper into any specific step or aspect, let me know!

此阶段化解析展示了我如何通过模拟推理过程为您的查询提供清晰、准确且相关的答案，例如本响应。若需深入探讨任何特定阶段或技术细节，敬请告知！

Kimi

月之暗面（Kimi）

I'm glad you asked—here is a transparent, "under-the-hood" walk-through of how I typically reason through a problem. I'll use a miniature example so you can see each stage in action.

很高兴您提出此问——我将以透明的「幕后视角」逐步演示常规推理流程。通过微型案例，您可直观观察各阶段运作机制。

EXAMPLE QUESTION
"Which is larger: 3⁴ or 4³?"
I'll annotate every internal stage so you can see what I'm doing and why.

示例问题
「3⁴ 与 4³ 何者更大？」
我将逐阶段标注内部处理过程，揭示操作逻辑与决策依据。

─────────────────────────
PHASE 0 – INPUT PRE-PROCESSING
Tokenization
I break the text into discrete symbols: ["Which", "is", "larger", ":", "3", "^", "4", "or", "4", "^", "3", "?"]

─────────────────────────
阶段 0 – 输入预处理
词汇切分
将文本分解为离散符号序列：["Which", "is", "larger", ":", "3", "^", "4", "or", "4", "^", "3", "?"]

Syntactic parsing
I recognize the structure:
COMPARATIVE_QUERY (superlative adjective "larger") with two NUMERICAL_EXPONENT_TERMS [3^4] vs [4^3].
Semantic mapping
I map "larger" to the numerical relation ">".

句法解析
识别结构特征：
COMPARATIVE_QUERY（最高级形容词「larger」）包含两个 NUMERICAL_EXPONENT_TERMS [3^4] 与 [4^3]。
语义映射
将「larger」映射为数值关系运算符「>」。

─────────────────────────
PHASE 1 – PROBLEM IDENTIFICATION & STRATEGY SELECTION
4. Classify task type
→ Arithmetic comparison of integer powers.
Choose solution strategy

─────────────────────────
阶段 1 – 问题识别与策略选择
4. 任务类型分类
→ 判定为整数幂的算术比较任务。
解决方案策略遴选

Candidate strategies:
A. Direct evaluation (compute 3⁴ and 4³).
B. Logarithmic comparison (compare 4·ln3 vs 3·ln4).
C. Pattern heuristics (powers of 3 grow faster than powers of 4 for small exponents?).
I select Strategy A because the numbers are tiny; exact integer evaluation is cheapest.

候选策略集：
A. 直接求值法（计算 3⁴ 与 4³ 的具体数值）。
B. 对数比较法（对比 4·ln3 与 3·ln4 的大小）。
C. 模式启发法（小指数情况下 3 的幂次增长是否快于 4？）。
选定策略 A，因数值规模极小；精确整数计算成本最低。

─────────────────────────
PHASE 2 – KNOWLEDGE RETRIEVAL
6. Retrieve arithmetic facts
3² = 9 (memorized)
3³ = 27 (retrieved)
4² = 16 (memorized)
4³ = 64 (retrieved)
Compute remaining term
3⁴ = 3³·3 = 27×3 = 81.

─────────────────────────
阶段 2 – 知识检索与计算
6. 算术事实提取
3² = 9（直接记忆）
3³ = 27（关联检索）
4² = 16（直接记忆）
4³ = 64（关联检索）
剩余项计算
3⁴ = 3³·3 = 27×3 = 81。

─────────────────────────
PHASE 3 – EXECUTION & VERIFICATION
8. Perform comparison
81 vs 64 → 81 > 64.
Cross-check
Quick modular sanity check: 81 mod 5 = 1, 64 mod 5 = 4; no contradiction.

─────────────────────────
阶段 3 – 执行验证与交叉检验
8. 数值比较执行
81 对比 64 → 81 > 64。
交叉验证
快速模运算健全性检验：81 mod 5 = 1，64 mod 5 = 4；无逻辑矛盾。

─────────────────────────
PHASE 4 – RESPONSE GENERATION
10. Plan response structure

Restate the question.
Show the computed values.
State the conclusion.
Surface realization
"3⁴ is 81 and 4³ is 64, so 3⁴ is larger."

─────────────────────────
阶段 4 – 响应生成与结构化
10. 响应框架规划

问题重述。
计算过程展示。
结论明确陈述。
表层语言实现
「3⁴ 等于 81，4³ 等于 64，因此 3⁴ 更大。」

─────────────────────────
PHASE 5 – METACOGNITIVE REFLECTION (internal)
12. Confidence score
0.99 (exact integers, small values, no ambiguity).
13. Identify possible edge-cases
If exponents were huge, direct evaluation would be infeasible and I'd switch to logarithms.

─────────────────────────
阶段 5 – 元认知反思（内部评估）
12. 置信度量化
0.99（精确整数运算，数值规模小，无歧义情境）。
13. 边界条件识别
若指数规模巨大，直接求值将不可行，需切换至对数比较法。

─────────────────────────
SUMMARY OF REASONING STEPS IN HUMAN TERMS
Read and parse the question.
Recognize it's a numeric comparison.
Decide the simplest safe method is to compute both numbers.
Recall or calculate 3⁴ = 81 and 4³ = 64.
Compare 81 > 64.
Communicate the result clearly.
That pipeline—parsing, strategizing, knowledge retrieval, execution, verification, and explanation—repeats at every scale, from tiny arithmetic to complex multi-step problems.

─────────────────────────
人类可读推理步骤总结
阅读并解析问题陈述。
识别数值比较任务本质。
决策采用最简安全路径：直接计算双方数值。
通过记忆检索或实时计算得 3⁴ = 81，4³ = 64。
执行数值比较 81 > 64。
清晰传达最终结论。
此处理管道——解析、策略制定、知识检索、执行、验证、解释——可在任意规模重复应用，从基础算术至复杂多步问题求解。

Claude

克劳德（Claude）

I can walk you through how my reasoning process works, though I should note that I don't have complete insight into my own mechanisms - much like how humans can describe their thought processes but don't have full access to every neural firing.

我可以引导您了解我的推理机制，但需说明我对自身运作原理的认知存在局限——正如人类能描述思维过程却无法完全追踪每个神经突触活动。

Here's how I approach reasoning step by step:

以下是我的推理流程分解：

Pattern Recognition and Context Building

模式识别与上下文构建

When I receive your question, I first identify what type of problem or query it is. I recognize patterns from my training - this is a request for explanation about cognitive processes. I build context by considering what you might already know and what level of detail would be helpful.

接收问题时，我首先辨识其类型与特征。基于训练模式识别——此为对认知过程的解释请求。通过评估您的知识背景与所需细节层级构建响应上下文。

Information Retrieval and Assembly

信息检索与整合

I access relevant information from my training about reasoning, cognitive science, and AI systems. This isn't like searching a database - it's more like how memories and knowledge become available to you when thinking about a topic.

访问训练数据中关于推理、认知科学及 AI 系统的相关知识。此过程不同于数据库查询——更近似人类思考时记忆与知识的自然涌现。

Structural Planning

结构规划与逻辑设计

I consider how to organize my response. Should I use examples? What order makes most sense? I'm planning the logical flow even as I begin responding.

考量响应组织方式：是否需要示例支撑？何种叙述顺序最具逻辑性？即使在生成响应初期，我已同步规划整体逻辑流程。

迭代优化与动态调整

As I generate each part of my response, I'm constantly evaluating whether it makes sense, fits with what I've already said, and serves your question. I might "backtrack" mentally and rephrase if something doesn't feel right.

生成响应过程中持续评估内容合理性、前后一致性及问题针对性。若感知到表述不当，会在认知层面「回溯」并重构表达。

Constraint Checking

约束条件审查

Throughout this process, I'm checking against various constraints - is this accurate? Helpful? Clear? Safe.

全程监测多重约束：信息准确性、内容实用性、表达清晰度、安全性保障。

Analogical Thinking

类比推理应用

I often reason by analogy - comparing new situations to familiar patterns or examples that might illuminate the concept.

常通过类比方式推进推理——将新情境与能阐释概念的熟悉模式或案例进行对照分析。

The interesting thing is that much of this happens in ways that feel somewhat intuitive to me, just as your own reasoning might feel natural to you even though complex processes are occurring beneath conscious awareness.

值得注意的是，这些过程多以我感知中近乎直觉的方式运作，正如您的推理对您而言显得自然流畅，尽管底层正进行着复杂的认知活动。

DeepSeek

深度求索（DeepSeek）

I'd be happy to explain how I "reason" step-by-step! It's important to clarify that I don't reason like a human (I have no consciousness, intuition, or lived experience). Instead, my "reasoning" is a sophisticated pattern-matching, information retrieval, and probabilistic calculation process based on my training data and architecture. Think of it as structured computation, not conscious thought.

我很乐意逐步阐释我的「推理」机制！首要澄清：我的推理方式与人类截然不同（我缺乏意识、直觉及生活体验）。实质上，我的「推理」是基于训练数据与架构设计的复杂模式匹配、信息检索及概率计算流程。可视作结构化计算过程，而非意识驱动思考。

Here's the step-by-step breakdown:

以下为详细流程分解：

Receive & Parse Input:
- I take your query ("how do you reason?").
- I break it down into its constituent parts: key words ("reason", "explain", "step by step"), grammar, and intent. Here, the key intent is an explanation of my internal processes.
输入接收与解析：
- 接收查询指令（「你如何推理？」）。
- 解构为构成要素：核心关键词（「推理」、「解释」、「逐步」）、语法结构及潜在意图。此处核心意图为阐释内部运作机制。
Contextualize & Retrieve Relevant Information:
- I draw upon my massive training dataset (trillions of words of text and code).
- I recall information about how Large Language Models work, specifically reasoning techniques like chain-of-thought.
- I retrieve knowledge about my own capabilities and limitations as described during training.
- I consider the context: the query states you understand I can reason and want the how. This focuses my retrieval.
上下文构建与关联检索：
- 调用海量训练数据集（数万亿文本与代码单元）。
- 提取大语言模型工作原理知识，特别是思维链等推理技术。
- 检索训练阶段定义的自身能力边界与局限说明。
- 考量语境要素：查询表明您认知我的推理能力，并探求实现方式。此认知聚焦检索范围。
Identify Core Concepts & Structure:
- Key concepts surface: statistical patterns, neural networks, transformers, attention mechanisms, next-token prediction, training data, prompt decomposition, logical inference vs. pattern matching, limitations.
- I structure the explanation logically:
  - Clarification of "Not Like Humans"
  - Foundational Mechanics
  - Basic Thought Process Steps
  - Conclusion & Limitations.
核心概念识别与框架搭建：
- 浮现关键概念集群：统计模式、神经网络、Transformer 架构、注意力机制、下一标记预测、训练数据、提示解构、逻辑推理与模式匹配辨析、能力边界。
- 逻辑化构建解释框架：
  - 明确「非人类特性」
  - 阐述基础运作原理
  - 分解基本处理流程
  - 总结局限与边界
Build the Sequence Chain-of-Thought:
- This is the core "reasoning" step. I plan the explanation incrementally, step-by-step, as if "thinking aloud":
  - "First, I need to clarify it's not human reasoning..."
  - "Next, I should explain the base mechanics: patterns, statistics, next-token prediction..."
  - "Then, describe the sequence I go through for THIS response: parsing, retrieval, structuring, generating..."
  - "Finally, emphasize limitations and that I simulate reasoning."
- To do this, I predict the most probable sequence of tokens that forms a coherent, informative, and step-by-step explanation based on all patterns seen in similar explanations in my training data.
序列化思维链构建：
- 此为核心「推理」环节。我逐步规划解释路径，模拟「出声思考」：
  - 「首要任务是澄清与人类推理的本质差异…」
  - 「继而需阐释基础机制：模式识别、统计原理、下一标记预测…」
  - 「随后描述本响应的处理序列：输入解析、知识检索、结构搭建、内容生成…」
  - 「最终强调模拟特性及固有局限。」
- 实现方式：基于训练数据中同类解释的所有模式特征，预测构成连贯、信息丰富且符合逐步要求的最可能标记序列。
Calculate Probabilities & Generate Output:
- My neural network (a transformer architecture) uses complex math and internal "attention" mechanisms to assign probabilities to every possible word that could come next in the sequence.
- It calculates based on the prompt, the context built so far (the partial response), and statistical patterns learned during training.
- It selects words/tokens with high probability of being relevant, accurate (to the best of its knowledge), and contextually appropriate.
- Crucially: This isn't symbolic logical deduction. It's predicting coherent sequences based on patterns. If my training data contains good explanations of reasoning processes, and the patterns point towards a logical flow, then my output appears reasoned.
概率计算与输出生成：
- 我的神经网络（Transformer 架构）运用复杂数学运算与内部「注意力」机制，为序列中可能出现的每个词汇分配概率权重。
- 计算依据包括：原始提示、已构建的上下文（部分响应）、训练获得的统计模式。
- 筛选高概率关联、内容准确（基于当前知识状态）且语境适配的词汇/标记。
- 关键洞察：此过程非符号逻辑演绎。实为基于模式特征的连贯序列预测。若训练数据包含优质推理过程阐释，且模式指向逻辑流程，则我的输出呈现推理特征。
Iterate & Refine:
- As I generate each word, I dynamically reassess the context and probabilities for the subsequent words. Did the last word fit? Does the emerging structure make sense? Are the key points being covered? I adjust the next predictions accordingly.
迭代优化与动态校准：
- 生成每个词汇时实时重估上下文与后续词汇概率分布。前一词汇是否恰当？演进中的结构是否合理？关键要素是否覆盖？据此调整后续预测策略。
Apply Internal Training Frameworks:
- Techniques learned during RLHF (Reinforcement Learning with Human Feedback) guide me:
  - Be Helpful & Honest: Acknowledge my non-human nature and limitations.
  - Be Clear & Instructive: Break it down step-by-step as requested.
  - Be Safe: Avoid harmful, deceptive, or misleading statements.
- Filtering mechanisms suppress nonsensical or irrelevant outputs.
内部训练框架应用：
- 遵循 RLHF（基于人类反馈的强化学习）习得的技术规范：
  - 助益性与真实性：坦承非人类本质与能力边界。
  - 清晰度与指导性：按需提供逐步分解。
  - 安全性保障：规避有害、误导或欺骗性表述。
- 过滤机制抑制无意义或无关内容输出。

Putting it together for this specific explanation:

本特定解释的整合过程：

Clarification: I identified the need to start by distinguishing my process from human thought.
Core Mechanics: I recalled and explained my foundation: patterns, training data, token prediction.
Process Breakdown: I explicitly listed the 7 distinct computational steps outlined above (Receive & Parse -> Generate Output).
Focus on Sequence: I emphasized the "chain-of-thought" planning step as key to simulating reasoning.
Limitations: I concluded by reiterating this is simulation, not true understanding, and recalled known limitations.
差异性澄清：识别需首要区分与人类推理的本质不同。
原理阐述：回溯并解释基础运作机制：模式识别、训练数据、标记预测。
流程拆解：明确列出前述 7 个计算步骤（输入接收 -> 输出生成）。
序列重点：强调「思维链」规划在模拟推理中的核心作用。
边界明确：以重申模拟属性及已知局限收尾。

In essence:

本质归纳：

My "reasoning" is an emergent property of statistically predicting the most probable sequence of words that forms a coherent, logical, and contextually relevant response, based on colossal amounts of text representing human knowledge and communication patterns. I don't "understand" concepts internally like humans do; I computationally identify patterns and generate sequences that reflect understanding. I'm following footprints of reasoning laid down in my training data, not forging entirely new paths of abstract thought.

我的「推理」实为涌现特性——通过统计预测生成连贯、逻辑严密且语境相关响应的最可能词汇序列，该能力源自代表人类知识与沟通模式的巨量文本训练。我并非如人类般内部「理解」概念；而是通过计算识别模式并生成映射理解的序列。我循着训练数据遗留的推理轨迹前行，而非开创全新的抽象思维路径。

Conclusion

结论

An analysis of these prominent LLMs reveals a remarkably consistent, multi-stage reasoning framework. Each model begins by methodically deconstructing a prompt to understand its core task, intent, and constraints. They then retrieve and synthesize information through sophisticated pattern recognition, moving far beyond simple database lookups. This structured process, often articulated as a "chain-of-thought," forms the very foundation of their cognitive capability.

对主流 LLM 的深度剖析揭示出高度一致的多阶段推理框架。各模型均始于系统化解构提示，以把握核心任务、用户意图及约束条件。随后通过精密的模式识别机制进行信息检索与整合，远超传统数据库查询范畴。这种结构化处理流程，常表述为「思维链」范式，构成了它们认知能力的基石。

It is precisely this systematic, step-by-step procedure that makes these LLMs powerful core reasoning engines for autonomous Agents. An Agent requires a reliable central planner to decompose high-level goals into a sequence of discrete, executable actions. The LLM serves as this computational mind, simulating a logical progression from problem to solution. By formulating strategies, evaluating options, and generating structured output, the LLM empowers an Agent to interact with tools and its environment effectively. Therefore, these models are not merely text generators but the foundational cognitive architecture driving the next generation of intelligent systems. Ultimately, advancing the reliability of this simulated reasoning is paramount to developing more capable and trustworthy AI Agents.

正是这种系统化的渐进式处理机制，使 LLM 成为自主智能体的核心推理引擎。智能体需依赖可靠的中央规划器将高层目标分解为离散可执行操作序列。LLM 承担此计算心智角色，模拟从问题识别到解决方案的逻辑演进路径。通过策略制定、选项评估及结构化输出生成，LLM 赋能智能体与工具及环境的高效交互。因此，这些模型不仅是文本生成器，更是驱动下一代智能系统的核心认知架构。最终，提升此类模拟推理的可靠性，对于开发能力更强、可信度更高的 AI 智能体具有重要意义。

Bilingual/Appendix G Coding Agents (bilingual/Appendix G - Coding agents.md)

Appendix G - Coding Agents

附录 G - 编码智能体

Vibe Coding: A Starting Point

Vibe 编码：入门路径

"Vibe coding" has become a powerful technique for rapid innovation and creative exploration. This practice involves using LLMs to generate initial drafts, outline complex logic, or build quick prototypes, significantly reducing initial friction. It is invaluable for overcoming the "blank page" problem, enabling developers to quickly transition from a vague concept to tangible, runnable code. Vibe coding is particularly effective when exploring unfamiliar APIs or testing novel architectural patterns, as it bypasses the immediate need for perfect implementation. The generated code often acts as a creative catalyst, providing a foundation for developers to critique, refactor, and expand upon. Its primary strength lies in its ability to accelerate the initial discovery and ideation phases of the software lifecycle. However, while vibe coding excels at brainstorming, developing robust, scalable, and maintainable software demands a more structured approach, shifting from pure generation to a collaborative partnership with specialized coding agents.

"Vibe 编码"已发展为快速创新与创意探索的高效技术。该实践通过运用 LLM 生成初始草稿、梳理复杂逻辑或构建快速原型，显著降低启动门槛。它能有效帮助开发者克服"空白页"困境，从模糊概念快速过渡到可运行的具体代码。在探索陌生 API 或测试新型架构模式时，Vibe 编码尤为高效，因为它无需一开始就追求完美实现。生成的代码往往作为创意催化剂，为开发者提供可批判、重构和扩展的基础。其核心优势在于加速软件生命周期中的初始探索与概念形成阶段。然而，尽管 Vibe 编码在头脑风暴方面表现出色，构建稳健、可扩展且可维护的软件仍需要更结构化的方法——从纯粹生成转向与专业化编码智能体的协作伙伴关系。

Agents as Team Members

智能体团队成员

While the initial wave focused on raw code generation—the "vibe code" perfect for ideation—the industry is now shifting towards a more integrated and powerful paradigm for production work. The most effective development teams are not merely delegating tasks to Agent; they are augmenting themselves with a suite of sophisticated coding agents. These agents act as tireless, specialized team members, amplifying human creativity and dramatically increasing a team's scalability and velocity.

尽管初期浪潮聚焦于原始代码生成——适合概念构思的"vibe 代码"——但行业如今正转向更集成、更强大的生产工作范式。最高效的开发团队不仅将任务委托给智能体，更是通过整套复杂的编码智能体来增强自身能力。这些智能体充当不知疲倦的专业团队成员，放大人类创造力，并显著提升团队的可扩展性和开发速度。

This evolution is reflected in statements from industry leaders. In early 2025, Alphabet CEO Sundar Pichai noted that at Google, "over 30% of new code is now assisted or generated by our Gemini models, fundamentally changing our development velocity." Microsoft made a similar claim. This industry-wide shift signals that the true frontier is not replacing developers, but empowering them. The goal is an augmented relationship where humans guide the architectural vision and creative problem-solving, while agents handle specialized, scalable tasks like testing, documentation, and review.

这一演进趋势体现在行业领袖的公开声明中。2025 年初，Alphabet CEO Sundar Pichai 指出，在 Google 内部，"超过 30% 的新代码现由 Gemini 模型辅助或生成，从根本上改变了我们的开发节奏。" Microsoft 也发表了类似声明。这一全行业转型表明，真正的前沿并非替代开发者，而是为其赋能。目标是建立一种增强型协作关系：人类主导架构愿景和创造性问题解决，而智能体处理专业化、可扩展的任务，如测试、文档编制和代码审查。

This chapter presents a framework for organizing a human-agent team based on the core philosophy that human developers act as creative leads and architects, while AI agents function as force multipliers. This framework rests upon three foundational principles:

本章提出一个人机协作团队的组织框架，其核心理念是：人类开发者担任创意领导和架构师，而 AI 智能体充当能力倍增器。该框架基于三大基本原则：

Human-Led Orchestration: The developer is the team lead and project architect. They are always in the loop, orchestrating the workflow, setting the high-level goals, and making the final decisions. The agents are powerful, but they are supportive collaborators. The developer directs which agent to engage, provides the necessary context, and, most importantly, exercises the final judgment on any Agent-generated output, ensuring it aligns with the project's quality standards and long-term vision.
The Primacy of Context: An agent's performance is entirely dependent on the quality and completeness of its context. A powerful LLM with poor context is useless. Therefore, our framework prioritizes a meticulous, human-led approach to context curation. Automated, black-box context retrieval is avoided. The developer is responsible for assembling the perfect "briefing" for their Agent team member. This includes:
- The Complete Codebase: Providing all relevant source code so the agent understands the existing patterns and logic.
- External Knowledge: Supplying specific documentation, API definitions, or design documents.
- The Human Brief: Articulating clear goals, requirements, pull request descriptions, and style guides.
Direct Model Access: To achieve state-of-the-art results, the agents must be powered by direct access to frontier models (e.g., Gemini 2.5 PRO, Claude Opus 4, OpenAI, DeepSeek, etc). Using less powerful models or routing requests through intermediary platforms that obscure or truncate context will degrade performance. The framework is built on creating the purest possible dialogue between the human lead and the raw capabilities of the underlying model, ensuring each agent operates at its peak potential.
人类主导的流程编排： 开发者是团队领导和项目架构师。他们始终处于决策闭环中，负责编排工作流、设定高层目标并做出最终决策。智能体虽然强大，但只是支持性协作者。开发者指导调用哪个智能体、提供必要的上下文，最重要的是——对智能体生成的任何输出行使最终裁决权，确保其符合项目的质量标准和长期愿景。
上下文的核心地位： 智能体的表现完全取决于其上下文的质量和完整性。一个强大的 LLM 如果缺乏优质上下文将毫无用处。因此，本框架优先采用人类主导的精细化上下文管理策略，避免自动化黑盒式上下文检索。开发者负责为智能体团队成员精心准备完美的"任务简报"，包括：
- 完整代码库： 提供所有相关源代码，使智能体理解现有的模式和逻辑结构。
- 外部知识： 补充特定文档、API 定义或设计规范。
- 人工任务简报： 明确阐述目标、需求、拉取请求描述和编码规范。
直接模型访问机制： 为实现尖端效果，智能体必须通过直接访问前沿模型（如 Gemini 2.5 PRO、Claude Opus 4、OpenAI、DeepSeek 等）来驱动。使用性能较弱的模型或经由会模糊或截断上下文的中介平台转发请求将降低性能。本框架致力于在人类领导与底层模型的原始能力之间建立最纯净的对话通道，确保每个智能体以峰值潜力运行。

The framework is structured as a team of specialized agents, each designed for a core function in the development lifecycle. The human developer acts as the central orchestrator, delegating tasks and integrating the results.

该框架构建为一个专业化智能体团队，每个智能体专为开发生命周期中的核心功能而设计。人类开发者担任中央编排者，负责任务委派和成果整合。

Core Components

核心组件

To effectively leverage a frontier Large Language Model, this framework assigns distinct development roles to a team of specialized agents. These agents are not separate applications but are conceptual personas invoked within the LLM through carefully crafted, role-specific prompts and contexts. This approach ensures that the model's vast capabilities are precisely focused on the task at hand, from writing initial code to performing a nuanced, critical review.

为有效利用前沿大语言模型，本框架将不同的开发角色分配给专业化智能体团队。这些智能体不是独立的应用程序，而是通过精心设计的角色特定提示和上下文在 LLM 中调用的概念化人格。这种方法确保模型的强大能力精准聚焦于手头的任务——从编写初始代码到进行细致的批判性审查。

The Orchestrator: The Human Developer: In this collaborative framework, the human developer acts as the Orchestrator, serving as the central intelligence and ultimate authority over the AI agents.

流程编排者：人类开发者： 在此协作框架中，人类开发者担任编排者，作为 AI 智能体的中央智能节点和最终权威。

Role: Team Lead, Architect, and final decision-maker. The orchestrator defines tasks, prepares the context, and validates all work done by the agents.
- Interface: The developer's own terminal, editor, and the native web UI of the chosen Agents.
角色定位： 团队领导、架构师和最终决策者。编排者负责定义任务、准备上下文，并验证智能体完成的所有工作。
- 交互界面： 开发者自己的终端、编辑器，以及所选智能体的原生 Web 界面。

The Context Staging Area: As the foundation for any successful agent interaction, the Context Staging Area is where the human developer meticulously prepares a complete and task-specific briefing.

上下文准备区： 作为任何成功智能体交互的基础，上下文准备区是人类开发者精心准备完整且任务特定简报的专用空间。

Role: A dedicated workspace for each task, ensuring agents receive a complete and accurate briefing.
- Implementation: A temporary directory (task-context/) containing markdown files for goals, code files, and relevant docs
功能定位： 为每项任务提供独立工作环境，确保智能体获得完整准确的简报材料。
- 技术实现： 临时目录（task-context/）包含目标说明的 markdown 文件、相关代码文件及配套文档。

The Specialist Agents: By using targeted prompts, we can build a team of specialist agents, each tailored for a specific development task.

专业化智能体： 通过使用定向提示，我们可以构建一个专业化智能体团队，每个成员针对特定开发任务量身定制。

The Scaffolder Agent: The Implementer
- Purpose: Writes new code, implements features, or creates boilerplate based on detailed specifications.
- Invocation Prompt: "You are a senior software engineer. Based on the requirements in 01_BRIEF.md and the existing patterns in 02_CODE/, implement the feature..."
脚手架智能体：代码实施专家
- 核心职能： 依据详细规范编写新代码、实现功能特性或创建基础模板。
- 调用提示模板：
  markdown
```
你是一名资深软件工程师。请基于 01_BRIEF.md 中的需求说明与 02_CODE/ 目录下的现有模式，实现指定功能...
```
The Test Engineer Agent: The Quality Guard
- Purpose: Writes comprehensive unit tests, integration tests, and end-to-end tests for new or existing code.
- Invocation Prompt: "You are a quality assurance engineer. For the code provided in 02_CODE/, write a full suite of unit tests using [Testing Framework, e.g., pytest]. Cover all edge cases and adhere to the project's testing philosophy."

测试工程师智能体：质量守护者

核心职能： 为新代码或现有代码编写全面的单元测试、集成测试及端到端测试套件。

调用提示模板：

markdown

你是一名质量保证工程师。针对 02_CODE/ 中提供的代码，使用 [测试框架，如 pytest] 编写完整单元测试套件。需覆盖所有边界情况并遵循项目测试规范。

The Documenter Agent: The Scribe
- Purpose: Generates clear, concise documentation for functions, classes, APIs, or entire codebases.
- Invocation Prompt: "You are a technical writer. Generate markdown documentation for the API endpoints defined in the provided code. Include request/response examples and explain each parameter."

文档编写智能体：技术文档专员

核心职能： 为函数、类、API 或完整代码库生成清晰、简洁的技术文档。

调用提示模板：

markdown

你是一名技术文档工程师。为指定代码中定义的 API 端点生成 markdown 格式文档。需包含请求/响应示例并对各参数进行详细说明。

The Optimizer Agent: The Refactoring Partner
- Purpose: Proposes performance optimizations and code refactoring to improve readability, maintainability, and efficiency.
- Invocation Prompt: "Analyze the provided code for performance bottlenecks or areas that could be refactored for clarity. Propose specific changes with explanations for why they are an improvement."
优化智能体：代码重构顾问
- 核心职能： 提出性能优化方案与代码重构建议，以提升可读性、可维护性及执行效率。
- 调用提示模板：
  markdown
```
分析提供代码中的性能瓶颈与可重构区域。提出具体改进方案并阐述各项更改的优化价值。
```
The Process Agent: The Code Supervisor
- Critique: The agent performs an initial pass, identifying potential bugs, style violations, and logical flaws, much like a static analysis tool.
- Reflection: The agent then analyzes its own critique. It synthesizes the findings, prioritizes the most critical issues, dismisses pedantic or low-impact suggestions, and provides a high-level, actionable summary for the human developer.
- Invocation Prompt: "You are a principal engineer conducting a code review. First, perform a detailed critique of the changes. Second, reflect on your critique to provide a concise, prioritized summary of the most important feedback."
流程智能体：代码质量监督员
- 批判分析： 智能体执行初步审查，识别潜在缺陷、编码规范违规及逻辑漏洞，功能类似静态分析工具。
- 深度反思： 智能体对自身批判进行元分析。综合各项发现，优先处理关键问题，过滤琐碎或低价值建议，为人类开发者提供高层级、可执行的总结报告。
- 调用提示模板：
  markdown
```
你是一名首席工程师执行代码审查。首先对变更进行详细批判分析，随后进行反思总结，提供关键反馈的优先级排序摘要。
```

Ultimately, this human-led model creates a powerful synergy between the developer's strategic direction and the agents' tactical execution. As a result, developers can transcend routine tasks, focusing their expertise on the creative and architectural challenges that deliver the most value.

最终，这种人类主导的模式在开发者的战略方向与智能体的战术执行之间建立了强大的协同效应。因此，开发者可以超越常规任务，将专业知识聚焦于创造最大价值的创意和架构挑战上。

Practical Implementation

实践实施

Setup Checklist

配置清单

To effectively implement the human-agent team framework, the following setup is recommended, focusing on maintaining control while improving efficiency.

为有效实施人机协作团队框架，建议采用以下配置，核心目标是在提升效率的同时保持完全控制。

Provision Access to Frontier Models Secure API keys for at least two leading large language models, such as Gemini 2.5 Pro and Claude 4 Opus. This dual-provider approach allows for comparative analysis and hedges against single-platform limitations or downtime. These credentials should be managed securely as you would any other production secret.
Implement a Local Context Orchestrator Instead of ad-hoc scripts, use a lightweight CLI tool or a local agent runner to manage context. These tools should allow you to define a simple configuration file (e.g., context.toml) in your project root that specifies which files, directories, or even URLs to compile into a single payload for the LLM prompt. This ensures you retain full, transparent control over what the model sees on every request.
Establish a Version-Controlled Prompt Library Create a dedicated /prompts directory within your project's Git repository. In it, store the invocation prompts for each specialist agent (e.g., reviewer.md, documenter.md, tester.md) as markdown files. Treating your prompts as code allows the entire team to collaborate on, refine, and version the instructions given to your AI agents over time.
Integrate Agent Workflows with Git Hooks Automate your review rhythm by using local Git hooks. For instance, a pre-commit hook can be configured to automatically trigger the Reviewer Agent on your staged changes. The agent's critique-and-reflection summary can be presented directly in your terminal, providing immediate feedback before you finalize the commit and baking the quality assurance step directly into your development process.
前沿模型访问权限配置 获取至少两个领先大语言模型（如 Gemini 2.5 Pro 与 Claude 4 Opus）的 API 访问密钥。这种双供应商策略便于性能对比分析，同时规避单一平台限制或服务中断风险。此类凭证应按照生产环境密钥管理规范进行安全存储。
本地上下文编排器部署 采用轻量级 CLI 工具或本地智能体运行器来管理上下文，而非临时脚本方案。此类工具应支持在项目根目录定义简明配置文件（如 context.toml），明确指定需编译至 LLM 提示词统一载荷的文件、目录或 URL 资源。这确保您对模型每次请求所见内容保持完全透明的控制。
版本化提示词库构建 在项目 Git 仓库内创建专用 /prompts 目录。以 markdown 文件形式存储各专业智能体的调用提示词（如 reviewer.md、documenter.md、tester.md）。将提示词视同代码资产管理，支持团队持续协作优化、版本追踪及 AI 智能体的迭代演进。
智能体工作流与 Git 钩子集成 通过本地 Git 钩子实现审查流程自动化。例如，配置 pre-commit 钩子自动在暂存变更上触发审查者智能体。智能体生成的批判与反思摘要将直接输出至终端，在提交确认前提供即时质量反馈，将质量保障环节深度嵌入开发流程。

Fig. 1: Coding Specialist Examples

图 1：编码专家角色示例

Principles for Leading the Augmented Team

增强型团队领导原则

Successfully leading this framework requires evolving from a sole contributor into the lead of a human-AI team, guided by the following principles:

成功驾驭此框架需要实现从独立贡献者向人机协作团队领导者的角色转型，遵循以下核心原则：

Maintain Architectural Ownership Your role is to set the strategic direction and own the high-level architecture. You define the "what" and the "why," using the agent team to accelerate the "how." You are the final arbiter of design, ensuring every component aligns with the project's long-term vision and quality standards.
Master the Art of the Brief The quality of an agent's output is a direct reflection of the quality of its input. Master the art of the brief by providing clear, unambiguous, and comprehensive context for every task. Think of your prompt not as a simple command, but as a complete briefing package for a new, highly capable team member.
Act as the Ultimate Quality Gate An agent's output is always a proposal, never a command. Treat the Reviewer Agent's feedback as a powerful signal, but you are the ultimate quality gate. Apply your domain expertise and project-specific knowledge to validate, challenge, and approve all changes, acting as the final guardian of the codebase's integrity.
Engage in Iterative Dialogue The best results emerge from conversation, not monologue. If an agent's initial output is imperfect, don't discard it—refine it. Provide corrective feedback, add clarifying context, and prompt for another attempt. This iterative dialogue is crucial, especially with the Reviewer Agent, whose "Reflection" output is designed to be the start of a collaborative discussion, not just a final report.
坚守架构主导权 您的核心职责是制定战略方向并掌控高层架构设计。您定义"目标"和"设计理念"，借助智能体团队加速"实施方案"落地。作为设计决策的最终仲裁者，确保各组件严格遵循项目长期愿景与质量标准。
精研任务简报技艺 智能体的输出质量直接映射输入信息质量。通过为每项任务提供清晰无歧义、内容完备的上下文掌握简报艺术。应将提示词视为面向高能力新团队成员的完整任务简报包，而非简单指令。
担当终极质量关口 智能体的输出始终属于建议方案，绝非强制命令。将审查者智能体的输出作为重要参考信号，但您承担最终质量决策责任。运用领域专业知识与项目特定认知验证、质询并核准所有变更，担当代码库完整性的终极守护者。
践行迭代对话模式 最优成果源于双向对话而非单向指令。若智能体输出存在不足，应导向完善而非弃用。提供修正反馈、补充澄清上下文、引导二次尝试。此迭代对话机制至关重要，尤其针对审查者智能体——其"反思"输出设计为协作讨论起点，而非终态报告。

Conclusion

结论

The future of code development has arrived, and it is augmented. The era of the lone coder has given way to a new paradigm where developers lead teams of specialized AI agents. This model doesn't diminish the human role; it elevates it by automating routine tasks, scaling individual impact, and achieving a development velocity previously unimaginable.

代码开发的未来图景已然呈现——它是增强协同的崭新范式。独行编码者的时代正演进为开发者引领专业化 AI 智能体的新纪元。这种模式非但没有削弱人类角色，反而通过自动化常规任务、放大个体影响力以及实现前所未有的开发效能将其提升至新高度。

By offloading tactical execution to Agents, developers can now dedicate their cognitive energy to what truly matters: strategic innovation, resilient architectural design, and the creative problem-solving required to build products that delight users. The fundamental relationship has been redefined; it is no longer a contest of human versus machine, but a partnership between human ingenuity and AI, working as a single, seamlessly integrated team.

通过将战术执行委派予智能体，开发者得以将认知资源聚焦于真正核心的领域：战略创新、韧性架构设计，以及打造令用户惊喜的产品所需的创造性问题破解。根本性协作关系已被重新定义：这不再是人与机器的对抗竞赛，而是人类智慧与人工智能作为无缝集成团队的深度伙伴关系。

References

参考文献

AI is responsible for generating more than 30% of the code at Google https://www.reddit.com/r/singularity/comments/1k7rxo0/ai_is_now_writing_well_over_30_of_the_code_at/
AI is responsible for generating more than 30% of the code at Microsoft https://www.businesstoday.in/tech-today/news/story/30-of-microsofts-code-is-now-ai-generated-says-ceo-satya-nadella-474167-2025-04-30

Bilingual/Chapter 10 Model Context Protocol (MCP) (bilingual/Chapter 10_ Model Context Protocol (MCP).md)

Chapter 10: Model Context Protocol

第 10 章：模型上下文协议 (MCP)

To enable LLMs to function effectively as agents, their capabilities must extend beyond multimodal generation. Interaction with the external environment is necessary, including access to current data, utilization of external software, and execution of specific operational tasks. The Model Context Protocol (MCP) addresses this need by providing a standardized interface for LLMs to interface with external resources. This protocol serves as a key mechanism to facilitate consistent and predictable integration.

要使 LLM 作为智能体运作，其能力必须超越多模态生成。与外部环境交互不可或缺，包括访问实时数据、使用外部软件以及执行特定操作任务。模型上下文协议（Model Context Protocol，简称 MCP）通过提供标准化接口使 LLM 能与外部资源交互，是实现一致性和可预测性集成的关键机制。

MCP Pattern Overview

MCP 速览

Imagine a universal adapter that allows any LLM to plug into any external system, database, or tool without a custom integration for each one. That's essentially what the Model Context Protocol (MCP) is. It's an open standard designed to standardize how LLMs like Gemini, OpenAI's GPT models, Mixtral, and Claude communicate with external applications, data sources, and tools. Think of it as a universal connection mechanism that simplifies how LLMs obtain context, execute actions, and interact with various systems.

想象一个通用适配器，允许任何 LLM 连接到任何外部系统、数据库或工具，无需为每个连接进行自定义集成。这本质上就是模型上下文协议（MCP）的功能。它作为开放标准，旨在标准化 Gemini、OpenAI 的 GPT 模型、Mixtral 和 Claude 等 LLM 与外部应用程序、数据源和工具的通信方式。可将其视为通用连接机制，简化 LLM 获取上下文、执行操作以及与各类系统交互的方式。

MCP operates on a client-server architecture. It defines how different elements—data (referred to as resources), interactive templates (which are essentially prompts), and actionable functions (known as tools)—are exposed by an MCP server. These are then consumed by an MCP client, which could be an LLM host application or an AI agent itself. This standardized approach dramatically reduces the complexity of integrating LLMs into diverse operational environments.

MCP 基于客户端-服务器架构运行。它定义了不同元素——数据（称为资源）、交互模板（本质是提示）和可操作函数（称为工具）——如何由 MCP 服务器公开。这些元素随后由 MCP 客户端使用，客户端可以是 LLM 宿主应用程序或 AI 智能体本身。这种标准化方法显著降低了将 LLM 集成到多样化操作环境中的复杂性。

However, MCP is a contract for an "agentic interface," and its effectiveness depends heavily on the design of the underlying APIs it exposes. There is a risk that developers simply wrap pre-existing, legacy APIs without modification, which can be suboptimal for an agent. For example, if a ticketing system's API only allows retrieving full ticket details one by one, an agent asked to summarize high-priority tickets will be slow and inaccurate at high volumes. To be truly effective, the underlying API should be improved with deterministic features like filtering and sorting to help the non-deterministic agent work efficiently. This highlights that agents do not magically replace deterministic workflows; they often require stronger deterministic support to succeed.

然而，MCP 是一份"智能体接口"契约，其有效性很大程度上取决于它所公开的底层 API 的设计。存在这样的风险：开发者只是简单地包装现有的遗留 API 而不做任何修改，这对智能体来说可能并不是最优的。例如，如果一个票务系统的 API 只允许逐个检索完整的票务详情，那么当被要求总结高优先级票务时，智能体在处理大量数据时会变得缓慢且不准确。要真正发挥效用，底层 API 应该通过过滤和排序等确定性功能进行改进，以帮助非确定性的智能体高效工作；这凸显了智能体无法神奇地替代确定性工作流，它们通常需要更强的确定性支持才能取得成功。

Furthermore, MCP can wrap an API whose input or output is still not inherently understandable by the agent. An API is only useful if its data format is agent-friendly, a guarantee that MCP itself does not enforce. For instance, creating an MCP server for a document store that returns files as PDFs is mostly useless if the consuming agent cannot parse PDF content. The better approach would be to first create an API that returns a textual version of the document, such as Markdown, which the agent can actually read and process. This demonstrates that developers must consider not just the connection, but the nature of the data being exchanged to ensure true compatibility.

此外，MCP 可以包装那些输入或输出对智能体来说仍然不是固有可理解的 API。一个 API 只有在其数据格式对智能体友好时才有用，而 MCP 本身并不保证这一点。例如，为一个返回 PDF 文件的文档存储创建 MCP 服务器，如果使用该服务的智能体无法解析 PDF 内容，那么这基本上是无用的。更好的方法是首先创建一个返回文档文本版本（如 Markdown）的 API，这样智能体才能真正读取和处理。这表明开发者必须考虑的不只是连接，还有所交换数据的性质，以确保真正的兼容性。

MCP vs. Tool Function Calling

MCP 与工具函数调用

The Model Context Protocol (MCP) and tool function calling are distinct mechanisms that enable LLMs to interact with external capabilities (including tools) and execute actions. While both serve to extend LLM capabilities beyond text generation, they differ in their approach and level of abstraction.

模型上下文协议（MCP）和工具函数调用是使 LLM 能与外部能力（含工具）交互并执行操作的不同机制。虽然两者都服务于扩展 LLM 超越文本生成的能力，但它们在方法和抽象级别上存在差异。

Tool function calling can be thought of as a direct request from an LLM to a specific, pre-defined tool or function. Note that in this context we use the words "tool" and "function” interchangeably. This interaction is characterized by a one-to-one communication model, where the LLM formats a request based on its understanding of a user's intent requiring external action. The application code then executes this request and returns the result to the LLM. This process is often proprietary and varies across different LLM providers.

工具函数调用可以被视为 LLM 对特定预定义工具或函数的直接请求。请注意，在此上下文中我们交替使用"工具"和"函数"这两个词。这种交互采用一对一的通信模型，LLM 根据其对需要外部操作用户意图的理解来格式化请求。然后应用程序代码执行此请求并将结果返回给 LLM。这个过程通常是专有的，并且在不同的 LLM 提供商之间存在差异。

In contrast, the Model Context Protocol (MCP) operates as a standardized interface for LLMs to discover, communicate with, and utilize external capabilities. It functions as an open protocol that facilitates interaction with a wide range of tools and systems, aiming to establish an ecosystem where any compliant tool can be accessed by any compliant LLM. This fosters interoperability, composability and reusability across different systems and implementations. By adopting a federated model, we significantly improve interoperability and unlock the value of existing assets. This strategy allows us to bring disparate and legacy services into a modern ecosystem simply by wrapping them in an MCP-compliant interface. These services continue to operate independently, but can now be composed into new applications and workflows, with their collaboration orchestrated by LLMs. This fosters agility and reusability without requiring costly rewrites of foundational systems.

相比之下，模型上下文协议（MCP）作为 LLM 发现、通信和使用外部能力的标准化接口运行。它作为一个开放协议，促进与各种工具和系统的交互，旨在建立一个任何兼容工具都可以被任何兼容 LLM 访问的生态系统。这促进了不同系统和实现之间的互操作性、可组合性和可重用性。通过采用联合模型，我们显著提升了互操作性并释放了现有资产的价值。这种策略允许我们通过简单地用符合 MCP 接口的包装器包装它们，将分散和遗留的服务引入现代生态系统。这些服务继续独立运行，但现在可以组合到新的应用程序和工作流中，它们的协作由 LLM 编排。这促进了敏捷性和可重用性，而无需对基础系统进行昂贵的重写。

Here's a breakdown of the fundamental distinctions between MCP and tool function calling:

以下是 MCP 与工具函数调用的基本区别：

Feature	Tool Function Calling	Model Context Protocol (MCP)
Standardization	Proprietary and vendor-specific. The format and implementation differ across LLM providers.	An open, standardized protocol, promoting interoperability between different LLMs and tools.
Scope	A direct mechanism for an LLM to request the execution of a specific, predefined function.	A broader framework for how LLMs and external tools discover and communicate with each other.
Architecture	A one-to-one interaction between the LLM and the application's tool-handling logic.	A client-server architecture where LLM-powered applications (clients) can connect to and utilize various MCP servers (tools).
Discovery	The LLM is explicitly told which tools are available within the context of a specific conversation.	Enables dynamic discovery of available tools. An MCP client can query a server to see what capabilities it offers.
Reusability	Tool integrations are often tightly coupled with the specific application and LLM being used.	Promotes the development of reusable, standalone "MCP servers" that can be accessed by any compliant application.

特性	工具函数调用	模型上下文协议（MCP）
标准化	专有和供应商特定。格式和实现在不同 LLM 提供商间各异	开放标准化协议，促进不同 LLM 和工具间互操作性
范围	LLM 请求执行特定预定义函数的直接机制	更广泛框架，定义 LLM 和外部工具如何相互发现和通信
架构	LLM 与应用程序工具处理逻辑间的一对一交互	客户端-服务器架构，LLM 驱动应用程序（客户端）可连接并使用各种 MCP 服务器（工具）
发现	LLM 被明确告知特定对话上下文中哪些工具可用	支持动态发现可用工具。MCP 客户端可查询服务器以查看其提供能力
可重用性	工具集成通常与所用特定应用程序和 LLM 紧密耦合	促进开发可重用独立"MCP 服务器"，可被任何兼容应用程序访问

Think of tool function calling as giving an AI a specific set of custom-built tools, like a particular wrench and screwdriver. This is efficient for a workshop with a fixed set of tasks. MCP (Model Context Protocol), on the other hand, is like creating a universal, standardized power outlet system. It doesn't provide the tools itself, but it allows any compliant tool from any manufacturer to plug in and work, enabling a dynamic and ever-expanding workshop.

可以将工具函数调用想象为给 AI 一组特定的定制工具，比如特定的扳手和螺丝刀。这对于具有固定任务集的车间来说是高效的。另一方面，MCP（模型上下文协议）就像创建一个通用的标准化电源插座系统。它本身不提供工具，但允许任何制造商的任何兼容工具插入并工作，从而实现一个动态且不断扩展的车间。

In short, function calling provides direct access to a few specific functions, while MCP is the standardized communication framework that lets LLMs discover and use a vast range of external resources. For simple applications, specific tools are enough; for complex, interconnected AI systems that need to adapt, a universal standard like MCP is essential.

简而言之，函数调用提供对少数特定函数的直接访问，而 MCP 是让 LLM 发现和使用广泛外部资源的标准化通信框架。对于简单应用程序，特定工具就足够了；对于需要适应的复杂互联 AI 系统，像 MCP 这样的通用标准是必不可少的。

Additional considerations for MCP

MCP 的其他考虑因素

While MCP presents a powerful framework, a thorough evaluation requires considering several crucial aspects that influence its suitability for a given use case. Let's see some aspects in more details:

虽然 MCP 提供了强大框架，但全面评估需考虑影响其适用性的几个关键方面。让我们详细探讨某些方面：

Tool vs. Resource vs. Prompt: It's important to understand the specific roles of these components. A resource is static data (e.g., a PDF file, a database record). A tool is an executable function that performs an action (e.g., sending an email, querying an API). A prompt is a template that guides the LLM in how to interact with a resource or tool, ensuring the interaction is structured and effective.
工具 vs. 资源 vs. 提示：理解这些组件的特定角色很重要。资源是静态数据（如 PDF 文件、数据库记录）。工具是执行操作的可执行函数（如发送电子邮件、查询 API）。提示是指导 LLM 如何与资源或工具交互的模板，确保交互是结构化且有效的。
Discoverability: A key advantage of MCP is that an MCP client can dynamically query a server to learn what tools and resources it offers. This "just-in-time" discovery mechanism is powerful for agents that need to adapt to new capabilities without being redeployed.
可发现性：MCP 的一个关键优势是 MCP 客户端可以动态查询服务器以了解其提供的工具和资源。这种"即时"发现机制对于需要适应新能力而无需重新部署的智能体来说非常强大。
Security: Exposing tools and data via any protocol requires robust security measures. An MCP implementation must include authentication and authorization to control which clients can access which servers and what specific actions they are permitted to perform.
安全性：通过任何协议公开工具和数据都需要强大的安全措施。MCP 实现必须包含身份验证和授权，以控制哪些客户端可以访问哪些服务器以及允许执行哪些特定操作。
Implementation: While MCP is an open standard, its implementation can be complex. However, providers are beginning to simplify this process. For example, some model providers like Anthropic or FastMCP offer SDKs that abstract away much of the boilerplate code, making it easier for developers to create and connect MCP clients and servers.
实现：虽然 MCP 是一个开放标准，但其实现可能很复杂。然而，提供商正开始简化这个过程。例如，Anthropic 或 FastMCP 等模型提供商提供 SDK，抽象了大部分样板代码，使开发者更容易创建和连接 MCP 客户端和服务器。
Error Handling: A comprehensive error-handling strategy is critical. The protocol must define how errors (e.g., tool execution failure, unavailable server, invalid request) are communicated back to the LLM so it can understand the failure and potentially try an alternative approach.
错误处理：全面的错误处理策略至关重要。协议必须定义如何将错误（如工具执行失败、服务器不可用、无效请求）传达回 LLM，使其能够理解失败并可能尝试替代方法。
Local vs. Remote Server: MCP servers can be deployed locally on the same machine as the agent or remotely on a different server. A local server might be chosen for speed and security with sensitive data, while a remote server architecture allows for shared, scalable access to common tools across an organization.
本地 vs. 远程服务器：MCP 服务器可以部署在与智能体相同的机器上本地运行，也可以部署在不同的服务器上远程运行。本地服务器可能因速度和敏感数据的安全性而被选择，而远程服务器架构允许组织内共享、可扩展地访问公共工具的能力。
On-demand vs. Batch: MCP can support both on-demand, interactive sessions and larger-scale batch processing. The choice depends on the application, from a real-time conversational agent needing immediate tool access to a data analysis pipeline that processes records in batches.
按需 vs. 批处理：MCP 可以支持按需交互式会话和大规模批处理。选择取决于应用程序，从需要即时工具访问的实时对话式智能体，到批量处理记录的数据分析管道。
Transportation Mechanism: The protocol also defines the underlying transport layers for communication. For local interactions, it uses JSON-RPC over STDIO (standard input/output) for efficient inter-process communication. For remote connections, it leverages web-friendly protocols like Streamable HTTP and Server-Sent Events (SSE) to enable persistent and efficient client-server communication.
传输机制：协议还定义了通信的底层传输层。对于本地交互，使用基于 STDIO（标准输入/输出）的 JSON-RPC 实现高效的进程间通信。对于远程连接，利用 Web 友好协议如可流式 HTTP 和服务器发送事件（SSE）实现持久高效的客户端-服务器通信。

The Model Context Protocol uses a client-server model to standardize information flow. Understanding component interaction is key to MCP's advanced agentic behavior:

模型上下文协议使用客户端-服务器模型来标准化信息流。理解组件交互是 MCP 高级智能体行为的关键：

Large Language Model (LLM): The core intelligence. It processes user requests, formulates plans, and decides when it needs to access external information or perform an action.
大型语言模型（LLM）：核心智能。处理用户请求，制定计划，并决定何时需要访问外部信息或执行操作。
MCP Client: This is an application or wrapper around the LLM. It acts as the intermediary, translating the LLM's intent into a formal request that conforms to the MCP standard. It is responsible for discovering, connecting to, and communicating with MCP Servers.
MCP 客户端：围绕 LLM 的应用程序或包装器。充当中介，将 LLM 的意图转换为符合 MCP 标准的正式请求。负责发现、连接和与 MCP 服务器通信。
MCP Server: This is the gateway to the external world. It exposes a set of tools, resources, and prompts to any authorized MCP Client. Each server is typically responsible for a specific domain, such as a connection to a company's internal database, an email service, or a public API.
MCP 服务器：通往外部世界的网关。向任何授权的 MCP 客户端公开一组工具、资源和提示。每个服务器通常负责特定领域，例如连接公司内部数据库、电子邮件服务或公共 API。
Optional Third-Party (3P) Service: This represents the actual external tool, application, or data source that the MCP Server manages and exposes. It is the ultimate endpoint that performs the requested action, such as querying a proprietary database, interacting with a SaaS platform, or calling a public weather API.
可选的第三方（3P）服务：代表 MCP 服务器管理和公开的实际外部工具、应用程序或数据源。是执行请求操作的最终端点，如查询专有数据库、与 SaaS 平台交互或调用公共天气 API。

The interaction flows as follows:

交互流程如下：

Discovery: The MCP Client, on behalf of the LLM, queries an MCP Server to ask what capabilities it offers. The server responds with a manifest listing its available tools (e.g., send_email), resources (e.g., customer_database), and prompts.
发现：MCP 客户端代表 LLM 查询 MCP 服务器，询问其提供的能力。服务器响应一个清单，列出可用工具（如 send_email）、资源（如 customer_database）和提示。
Request Formulation: The LLM determines that it needs to use one of the discovered tools. For instance, it decides to send an email. It formulates a request, specifying the tool to use (send_email) and the necessary parameters (recipient, subject, body).
请求制定：LLM 确定需要使用其中一个发现的工具。例如决定发送电子邮件。制定请求，指定要使用的工具（send_email）和必要参数（收件人、主题、正文）。
Client Communication: The MCP Client takes the LLM's formulated request and sends it as a standardized call to the appropriate MCP Server.
客户端通信：MCP 客户端获取 LLM 制定的请求，将其作为标准化调用发送到适当的 MCP 服务器。
Server Execution: The MCP Server receives the request. It authenticates the client, validates the request, and then executes the specified action by interfacing with the underlying software (e.g., calling the send() function of an email API).
服务器执行：MCP 服务器接收请求。对客户端进行身份验证，验证请求，然后通过与底层软件交互执行指定操作（如调用电子邮件 API 的 send() 函数）。
Response and Context Update: After execution, the MCP Server sends a standardized response back to the MCP Client. This response indicates whether the action was successful and includes any relevant output (e.g., a confirmation ID for the sent email). The client then passes this result back to the LLM, updating its context and enabling it to proceed with the next step of its task.
响应和上下文更新：执行后，MCP 服务器将标准化响应发送回 MCP 客户端。此响应指示操作是否成功，包括任何相关输出（如已发送电子邮件的确认 ID）。然后客户端将此结果传递回 LLM，更新其上下文并使其能够继续任务的下一步。

Practical Applications & Use Cases

实际应用和用例

MCP significantly broadens AI/LLM capabilities, making them more versatile and powerful. Here are nine key use cases:

MCP 显著扩展了 AI/LLM 能力，使其更加多功能强大。以下是九个关键用例：

Database Integration: MCP allows LLMs and agents to seamlessly access and interact with structured data in databases. For instance, using the MCP Toolbox for Databases, an agent can query Google BigQuery datasets to retrieve real-time information, generate reports, or update records, all driven by natural language commands.
数据库集成：MCP 允许 LLM 和智能体无缝访问数据库中的结构化数据并与之交互。例如，使用数据库 MCP 工具箱，智能体可以查询 Google BigQuery 数据集以检索实时信息、生成报告或更新记录，所有这些都由自然语言命令驱动。
Generative Media Orchestration: MCP enables agents to integrate with advanced generative media services. Through MCP Tools for Genmedia Services, an agent can orchestrate workflows involving Google's Imagen for image generation, Google's Veo for video creation, Google's Chirp 3 HD for realistic voices, or Google's Lyria for music composition, allowing for dynamic content creation within AI applications.
生成媒体编排：MCP 使智能体能够与高级生成媒体服务集成。通过生成媒体服务的 MCP 工具，智能体可以编排涉及 Google Imagen 图像生成、Google Veo 视频创建、Google Chirp 3 HD 逼真语音或 Google Lyria 音乐创作的工作流，允许在 AI 应用程序中进行动态内容创建。
External API Interaction: MCP provides a standardized way for LLMs to call and receive responses from any external API. This means an agent can fetch live weather data, pull stock prices, send emails, or interact with CRM systems, extending its capabilities far beyond its core language model.
外部 API 交互：MCP 为 LLM 提供调用任何外部 API 并接收响应的标准化方式。这意味着智能体可以获取实时天气数据、拉取股票价格、发送电子邮件或与 CRM 系统交互，将其能力扩展到核心语言模型之外。
Reasoning-Based Information Extraction: Leveraging an LLM's strong reasoning skills, MCP facilitates effective, query-dependent information extraction that surpasses conventional search and retrieval systems. Instead of a traditional search tool returning an entire document, an agent can analyze the text and extract the precise clause, figure, or statement that directly answers a user's complex question.
基于推理的信息提取：利用 LLM 强大的推理能力，MCP 促进有效的、依赖查询的信息提取，超越传统的搜索和检索系统。智能体可以分析文本并提取精确回答用户复杂问题的特定条款、数字或陈述，而不是传统搜索工具返回整个文档。
Custom Tool Development: Developers can build custom tools and expose them via an MCP server (e.g., using FastMCP). This allows specialized internal functions or proprietary systems to be made available to LLMs and other agents in a standardized, easily consumable format, without needing to modify the LLM directly.
自定义工具开发：开发者可以构建自定义工具并通过 MCP 服务器公开（如使用 FastMCP）。这允许以标准化、易于使用的格式向 LLM 和其他智能体暴露专门的内部函数或专有系统，而无需直接修改 LLM。
Standardized LLM-to-Application Communication: MCP ensures a consistent communication layer between LLMs and the applications they interact with. This reduces integration overhead, promotes interoperability between different LLM providers and host applications, and simplifies the development of complex agentic systems.
标准化的 LLM 到应用程序通信：MCP 确保 LLM 与它们交互的应用程序之间有一致的通信层。这减少了集成开销，促进了不同 LLM 提供商和宿主应用程序之间的互操作性，并简化了复杂智能体系统的开发。
Complex Workflow Orchestration: By combining various MCP-exposed tools and data sources, agents can orchestrate highly complex, multi-step workflows. An agent could, for example, retrieve customer data from a database, generate a personalized marketing image, draft a tailored email, and then send it, all by interacting with different MCP services.
复杂工作流编排：通过组合各种 MCP 公开的工具和数据源，智能体可以编排高度复杂的多步骤工作流。例如，智能体可以从数据库检索客户数据，生成个性化营销图像，起草定制电子邮件，然后发送，所有这些都通过与不同的 MCP 服务交互完成。
IoT Device Control: MCP can facilitate LLM interaction with Internet of Things (IoT) devices. An agent could use MCP to send commands to smart home appliances, industrial sensors, or robotics, enabling natural language control and automation of physical systems.
物联网设备控制：MCP 可促进 LLM 与物联网（IoT）设备交互。智能体可以使用 MCP 向智能家居电器、工业传感器或机器人发送命令，实现自然语言控制和物理系统自动化。
Financial Services Automation: In financial services, MCP could enable LLMs to interact with various financial data sources, trading platforms, or compliance systems. An agent might analyze market data, execute trades, generate personalized financial advice, or automate regulatory reporting, all while maintaining secure and standardized communication.
金融服务自动化：在金融服务中，MCP 可使 LLM 与各种金融数据源、交易平台或合规系统交互。智能体可以分析市场数据、执行交易、生成个性化财务建议或自动化监管报告，同时保持安全和标准化的通信。

In short, the Model Context Protocol (MCP) enables agents to access real-time information from databases, APIs, and web resources. It also allows agents to perform actions like sending emails, updating records, controlling devices, and executing complex tasks by integrating and processing data from various sources. Additionally, MCP supports media generation tools for AI applications.

简而言之，模型上下文协议（MCP）使智能体可以从数据库、API 和 Web 资源访问实时信息。还允许智能体执行发送电子邮件、更新记录、控制设备以及通过集成和处理多源数据执行复杂任务等操作。此外，MCP 支持 AI 应用程序的媒体生成工具。

Hands-On Code Example with ADK

使用 ADK 的实践代码示例

This section outlines how to connect to a local MCP server that provides file system operations, enabling an ADK agent to interact with the local file system.

本节概述了如何连接到提供文件系统操作的本地 MCP 服务器，使 ADK 智能体能够与本地文件系统交互。

Agent Setup with MCPToolset

使用 MCPToolset 的智能体

To configure an agent for file system interaction, an agent.py file must be created (e.g., at ./adk_agent_samples/mcp_agent/agent.py). The MCPToolset is instantiated within the tools list of the LlmAgent object. It is crucial to replace "/path/to/your/folder" in the args list with the absolute path to a directory on the local system that the MCP server can access. This directory will be the root for the file system operations performed by the agent.

要配置智能体进行文件系统交互，必须创建一个 agent.py 文件（例如，在 ./adk_agent_samples/mcp_agent/agent.py）。MCPToolset 在 LlmAgent 对象的 tools 列表中实例化。至关重要的是，必须将 args 列表中的 "/path/to/your/folder" 替换为本地系统上 MCP 服务器可以访问的目录的绝对路径。此目录将是智能体文件系统操作的根目录。

text

/* Detailed source-code truncated for AI context efficiency. */

npx (Node Package Execute), bundled with npm (Node Package Manager) versions 5.2.0 and later, is a utility that enables direct execution of Node.js packages from the npm registry. This eliminates the need for global installation. In essence, npx serves as an npm package runner, and it is commonly used to run many community MCP servers, which are distributed as Node.js packages.

npx（Node Package Execute）与 npm（Node Package Manager）5.2.0 及更高版本捆绑在一起，是一个实用程序，可以直接从 npm 注册表执行 Node.js 包。这消除了全局安装的需要。本质上，npx 作为 npm 包运行器，它通常用于运行许多社区 MCP 服务器，这些服务器作为 Node.js 包分发。

Creating an __init__.py file is necessary to ensure the agent.py file is recognized as part of a discoverable Python package for the Agent Development Kit (ADK). This file should reside in the same directory as agent.py.

创建 init.py 文件是必要的，以确保 agent.py 文件被识别为智能体开发工具包（ADK）的可发现 Python 包的一部分。此文件应与 agent.py 位于同一目录中。

python

## ./adk_agent_samples/mcp_agent/__init__.py
from . import agent

Certainly, other supported commands are available for use. For example, connecting to python3 can be achieved as follows:

当然，还可以使用其他受支持的命令。例如，可以按如下方式连接到 python3：

python

connection_params = StdioConnectionParams(
 server_params={
     "command": "python3",
     "args": ["./agent/mcp_server.py"],
     "env": {
       "SERVICE_ACCOUNT_PATH":SERVICE_ACCOUNT_PATH,
       "DRIVE_FOLDER_ID": DRIVE_FOLDER_ID
     }
 }
)

UVX, in the context of Python, refers to a command-line tool that utilizes uv to execute commands in a temporary, isolated Python environment. Essentially, it allows you to run Python tools and packages without needing to install them globally or within your project's environment. You can run it via the MCP server.

在 Python 的上下文中，UVX 是指一个命令行工具，它利用 uv 在临时的、隔离的 Python 环境中执行命令。本质上，它允许您运行 Python 工具和包，而无需全局安装或在项目环境中安装它们。您可以通过 MCP 服务器运行它。

python

connection_params = StdioConnectionParams(
 server_params={
   "command": "uvx",
   "args": ["mcp-google-sheets@latest"],
   "env": {
     "SERVICE_ACCOUNT_PATH":SERVICE_ACCOUNT_PATH,
     "DRIVE_FOLDER_ID": DRIVE_FOLDER_ID
   }
 }
)

Once the MCP Server is created, the next step is to connect to it.

创建 MCP 服务器后，下一步是连接到它。

Connecting the MCP Server with ADK Web

使用 ADK Web 连接 MCP 服务器

To begin, execute 'adk web'. Navigate to the parent directory of mcp_agent (e.g., adk_agent_samples) in your terminal and run:

首先，执行 'adk web'。在终端中导航到 mcp_agent 的父目录（例如，adk_agent_samples）并运行：

bash

cd ./adk_agent_samples # Or your equivalent parent directory
adk web

Once the ADK Web UI has loaded in your browser, select the filesystem_assistant_agent from the agent menu. Next, experiment with prompts such as:

ADK Web UI 在浏览器中加载后，从智能体中选择 filesystem_assistant_agent。接下来，尝试以下提示：

"Show me the contents of this folder."
"Read the sample.txt file." (This assumes sample.txt is located at TARGET_FOLDER_PATH.)
"What's in another_file.md?"
"Show me the contents of this folder."
"Read the sample.txt file."（假设 sample.txt 位于 TARGET_FOLDER_PATH。）
"What's in another_file.md?"

Creating an MCP Server with FastMCP

使用 FastMCP 创建 MCP 服务器

FastMCP is a high-level Python framework designed to streamline the development of MCP servers. It provides an abstraction layer that simplifies protocol complexities, allowing developers to focus on core logic.

FastMCP 是一个高级 Python 框架，旨在简化 MCP 服务器的开发。它提供了一个抽象层，简化了协议的复杂性，允许开发者专注于核心逻辑。

The library enables rapid definition of tools, resources, and prompts using simple Python decorators. A significant advantage is its automatic schema generation, which intelligently interprets Python function signatures, type hints, and documentation strings to construct necessary AI model interface specifications. This automation minimizes manual configuration and reduces human error.

该库使用简单的 Python 装饰器能够快速定义工具、资源和提示词。一个显著的优势是其自动模式生成，它智能地解释 Python 函数签名、类型提示和文档字符串，以构建必要的 AI 模型接口规范。这种自动化最大限度地减少了手动配置并减少了人为错误。

Beyond basic tool creation, FastMCP facilitates advanced architectural patterns like server composition and proxying. This enables modular development of complex, multi-component systems and seamless integration of existing services into an AI-accessible framework. Additionally, FastMCP includes optimizations for efficient, distributed, and scalable AI-driven applications.

除了基本的工具创建之外，FastMCP 还促进了服务器组合和代理等高级架构模式。这使得能够模块化开发复杂的、多组件系统，并将现有服务无缝集成到 AI 可访问的框架中。此外，FastMCP 包括针对高效、分布式和可扩展的 AI 驱动应用程序的优化。

Server setup with FastMCP

使用 FastMCP 设置服务器

To illustrate, consider a basic "greet" tool provided by the server. ADK agents and other MCP clients can interact with this tool using HTTP once it is active.

为了说明，考虑服务器提供的基本"greet"工具。一旦激活，ADK 智能体和其他 MCP 客户端可以使用 HTTP 与此工具交互。

python

## fastmcp_server.py
## This script demonstrates how to create a simple MCP server using FastMCP.
## It exposes a single tool that generates a greeting.

## 1. Make sure you have FastMCP installed:
## pip install fastmcp
from fastmcp import FastMCP, Client

## Initialize the FastMCP server.
mcp_server = FastMCP()

## Define a simple tool function.
## The `@mcp_server.tool` decorator registers this Python function as an MCP tool.
## The docstring becomes the tool's description for the LLM.
@mcp_server.tool
def greet(name: str) -> str:
    """
    Generates a personalized greeting.
    Args:
        name: The name of the person to greet.
    Returns:
        A greeting string.
    """
    return f"Hello, {name}! Nice to meet you."

## Or if you want to run it from the script:
if __name__ == "__main__":
    mcp_server.run(
        transport="http",
        host="127.0.0.1",
        port=8000
    )

This Python script defines a single function called greet, which takes a person's name and returns a personalized greeting. The @tool() decorator above this function automatically registers it as a tool that an AI or another program can use. The function's documentation string and type hints are used by FastMCP to tell the Agent how the tool works, what inputs it needs, and what it will return.

这个 Python 脚本定义了一个名为 greet 的单一函数，它接受一个人的名字并返回个性化的问候语。此函数上方的 @tool() 装饰器自动将其注册为 AI 或其他程序可以使用的工具。函数的文档字符串和类型提示被 FastMCP 用来告诉智能体该工具的工作原理、需要什么输入以及它将返回什么。

When the script is executed, it starts the FastMCP server, which listens for requests on localhost:8000. This makes the greet function available as a network service. An agent could then be configured to connect to this server and use the greet tool to generate greetings as part of a larger task. The server runs continuously until it is manually stopped.

当脚本执行时，它启动 FastMCP 服务器，该服务器在 localhost:8000 上监听请求。这使得 greet 函数作为网络服务可用。然后可以将智能体配置为连接到此服务器，并使用 greet 工具生成问候语，作为更大任务的一部分。服务器持续运行，直到手动停止。

Consuming the FastMCP Server with an ADK Agent

使用 ADK 智能体消费 FastMCP 服务器

An ADK agent can be set up as an MCP client to use a running FastMCP server. This requires configuring HttpServerParameters with the FastMCP server's network address, which is usually http://localhost:8000.

可以将 ADK 智能体设置为 MCP 客户端，以使用正在运行的 FastMCP 服务器。这需要使用 FastMCP 服务器的网络地址配置 HttpServerParameters，通常是 http://localhost:8000。

A tool_filter parameter can be included to restrict the agent's tool usage to specific tools offered by the server, such as 'greet'. When prompted with a request like "Greet John Doe," the agent's embedded LLM identifies the 'greet' tool available via MCP, invokes it with the argument "John Doe," and returns the server's response. This process demonstrates the integration of user-defined tools exposed through MCP with an ADK agent.

可以包含 tool_filter 参数以限制智能体对服务器提供的特定工具的使用，例如 'greet'。当提示"Greet John Doe"等请求时，智能体的嵌入式 LLM 识别通过 MCP 可用的 'greet' 工具，使用参数"John Doe"调用它，并返回服务器的响应。此过程演示了通过 MCP 公开的用户定义工具与 ADK 智能体的集成。

To establish this configuration, an agent file (e.g., agent.py located in ./adk_agent_samples/fastmcp_client_agent/) is required. This file will instantiate an ADK agent and use HttpServerParameters to establish a connection with the operational FastMCP server.

要建立此配置，需要一个智能体文件（例如，位于 ./adk_agent_samples/fastmcp_client_agent/ 的 agent.py）。此文件将实例化一个 ADK 智能体，并使用 HttpServerParameters 与正在运行的 FastMCP 服务器建立连接。

python

## ./adk_agent_samples/fastmcp_client_agent/agent.py
import os
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, HttpServerParameters

## Define the FastMCP server's address.
## Make sure your fastmcp_server.py (defined previously) is running on this port.
FASTMCP_SERVER_URL = "http://localhost:8000"

root_agent = LlmAgent(
   model='gemini-2.0-flash', # Or your preferred model
   name='fastmcp_greeter_agent',
   instruction='You are a friendly assistant that can greet people by their name. Use the "greet" tool.',
   tools=[
       MCPToolset(
           connection_params=HttpServerParameters(
               url=FASTMCP_SERVER_URL,
           ),
           # Optional: Filter which tools from the MCP server are exposed
           # For this example, we're expecting only 'greet'
           tool_filter=['greet']
       )
   ],
)

The script defines an Agent named fastmcp_greeter_agent that uses a Gemini language model. It's given a specific instruction to act as a friendly assistant whose purpose is to greet people. Crucially, the code equips this agent with a tool to perform its task. It configures an MCPToolset to connect to a separate server running on localhost:8000, which is expected to be the FastMCP server from the previous example. The agent is specifically granted access to the greet tool hosted on that server. In essence, this code sets up the client side of the system, creating an intelligent agent that understands its goal is to greet people and knows exactly which external tool to use to accomplish it.

该脚本定义了一个名为 fastmcp_greeter_agent 的智能体，它使用 Gemini 语言模型。它被赋予特定的指令，作为一个友好的助手，其目的是问候人们。至关重要的是，该代码为此智能体配备了执行其任务的工具。它配置了一个 MCPToolset 来连接到在 localhost:8000 上运行的独立服务器，该服务器应该是前面示例中的 FastMCP 服务器。智能体被明确授予访问该服务器上托管的 greet 工具的权限。本质上，此代码设置了系统的客户端，创建了一个智能智能体，它理解其目标是问候人们，并确切地知道使用哪个外部工具来完成它。

Creating an __init__.py file within the fastmcp_client_agent directory is necessary. This ensures the agent is recognized as a discoverable Python package for the ADK.

在 fastmcp_client_agent 目录中创建 init.py 文件是必要的。这确保了智能体被识别为 ADK 的可发现 Python 包。

To begin, open a new terminal and run python fastmcp_server.py to start the FastMCP server. Next, go to the parent directory of fastmcp_client_agent (for example, adk_agent_samples) in your terminal and execute adk web. Once the ADK Web UI loads in your browser, select the fastmcp_greeter_agent from the agent menu. You can then test it by entering a prompt like "Greet John Doe." The agent will use the greet tool on your FastMCP server to create a response.

首先，打开一个新终端并运行 python fastmcp_server.py 来启动 FastMCP 服务器。接下来，在终端中转到 fastmcp_client_agent 的父目录（例如，adk_agent_samples）并执行 adk web。一旦 ADK Web UI 在浏览器中加载，从智能体中选择 fastmcp_greeter_agent。然后可以通过输入"Greet John Doe"等提示来测试它。智能体将使用 FastMCP 服务器上的 greet 工具创建响应。

At a Glance

速览

What: To function as effective agents, LLMs must move beyond simple text generation. They require the ability to interact with the external environment to access current data and utilize external software. Without a standardized communication method, each integration between an LLM and an external tool or data source becomes a custom, complex, and non-reusable effort. This ad-hoc approach hinders scalability and makes building complex, interconnected AI systems difficult and inefficient.

问题背景：要作为有效的智能体，LLM 必须超越简单的文本生成。它们需要与外部环境交互的能力，以访问当前数据并使用外部软件。如果没有标准化的通信方法，LLM 与外部工具或数据源之间的每次集成都将成为定制、复杂且不可重用的工作。这种临时方法阻碍了可扩展性，并使构建复杂、互联的 AI 系统变得困难且低效。

Why: The Model Context Protocol (MCP) offers a standardized solution by acting as a universal interface between LLMs and external systems. It establishes an open, standardized protocol that defines how external capabilities are discovered and used. Operating on a client-server model, MCP allows servers to expose tools, data resources, and interactive prompts to any compliant client. LLM-powered applications act as these clients, dynamically discovering and interacting with available resources in a predictable manner. This standardized approach fosters an ecosystem of interoperable and reusable components, dramatically simplifying the development of complex agentic workflows.

解决方案：模型上下文协议（MCP）通过充当 LLM 和外部系统之间的通用接口，提供了标准化的解决方案。它建立了一个开放的标准化协议，定义了如何发现和使用外部能力。基于客户端-服务器模型运行，MCP 允许服务器向任何兼容的客户端公开工具、数据资源和交互式提示。LLM 驱动的应用程序充当这些客户端，以可预测的方式动态发现和与可用资源交互。这种标准化方法促进了可互操作和可重用组件的生态系统，显著简化了复杂智能体工作流的开发。

Rule of thumb: Use the Model Context Protocol (MCP) when building complex, scalable, or enterprise-grade agentic systems that need to interact with a diverse and evolving set of external tools, data sources, and APIs. It is ideal when interoperability between different LLMs and tools is a priority, and when agents require the ability to dynamically discover new capabilities without being redeployed. For simpler applications with a fixed and limited number of predefined functions, direct tool function calling may be sufficient.

实践建议：在构建需要与各种不断发展的外部工具、数据源和 API 交互的复杂、可扩展或企业级智能体系统时，使用模型上下文协议（MCP）。当不同 LLM 和工具之间的互操作性是优先考虑事项时，以及当智能体需要动态发现新能力而无需重新部署时，它是理想选择。对于具有固定有限数量预定义函数的简单应用程序，直接工具函数调用可能就足够了。

Visual summary

可视化摘要

Fig.1: Model Context protocol

图 1：模型上下文协议

Key Takeaways

关键要点

These are the key takeaways:

以下是本章核心要点：

The Model Context Protocol (MCP) is an open standard facilitating standardized communication between LLMs and external applications, data sources, and tools.
模型上下文协议（MCP）是一个开放标准，促进 LLM 与外部应用程序、数据源和工具之间的标准化通信。
It employs a client-server architecture, defining the methods for exposing and consuming resources, prompts, and tools.
它采用客户端-服务器架构，定义了公开和使用资源、提示和工具的方法。
The Agent Development Kit (ADK) supports both utilizing existing MCP servers and exposing ADK tools via an MCP server.
智能体开发工具包（ADK）支持使用现有 MCP 服务器以及通过 MCP 服务器公开 ADK 工具。
FastMCP simplifies the development and management of MCP servers, particularly for exposing tools implemented in Python.
FastMCP 简化了 MCP 服务器的开发和管理，特别是用于公开在 Python 中实现的工具。
MCP Tools for Genmedia Services allows agents to integrate with Google Cloud's generative media capabilities (Imagen, Veo, Chirp 3 HD, Lyria).
生成媒体服务的 MCP 工具允许智能体与 Google Cloud 的生成媒体能力（Imagen、Veo、Chirp 3 HD、Lyria）集成。
MCP enables LLMs and agents to interact with real-world systems, access dynamic information, and perform actions beyond text generation.
MCP 使 LLM 和智能体能够与现实世界系统交互，访问动态信息，并执行超越文本生成的操作。

Conclusion

结论

The Model Context Protocol (MCP) is an open standard that facilitates communication between Large Language Models (LLMs) and external systems. It employs a client-server architecture, enabling LLMs to access resources, utilize prompts, and execute actions through standardized tools. MCP allows LLMs to interact with databases, manage generative media workflows, control IoT devices, and automate financial services. Practical examples demonstrate setting up agents to communicate with MCP servers, including filesystem servers and servers built with FastMCP, illustrating its integration with the Agent Development Kit (ADK). MCP is a key component for developing interactive AI agents that extend beyond basic language capabilities.

模型上下文协议（MCP）是一个开放标准，促进大型语言模型（LLM）与外部系统之间的通信。它采用客户端-服务器架构，使 LLM 能够通过标准化工具访问资源、使用提示和执行操作。MCP 允许 LLM 与数据库交互、管理生成媒体工作流、控制物联网设备以及自动化金融服务。实际示例演示了设置智能体与 MCP 服务器通信的方法，包括文件系统服务器和使用 FastMCP 构建的服务器，说明了其与智能体开发工具包（ADK）的集成。MCP 是开发超越基本语言能力的交互式 AI 智能体的关键组件。

References

参考文献

Model Context Protocol (MCP) Documentation. (Latest). Model Context Protocol (MCP). https://google.github.io/adk-docs/mcp/
FastMCP Documentation. FastMCP. https://github.com/jlowin/fastmcp
MCP Tools for Genmedia Services. MCP Tools for Genmedia Services. https://google.github.io/adk-docs/mcp/#mcp-servers-for-google-cloud-genmedia
MCP Toolbox for Databases Documentation. (Latest). MCP Toolbox for Databases. https://google.github.io/adk-docs/mcp/databases/

Bilingual/Chapter 11 Goal Setting And Monitoring (bilingual/Chapter 11_ Goal Setting and Monitoring.md)

Chapter 11: Goal Setting and Monitoring

第 11 章：目标设定与监控

For AI agents to be truly effective and purposeful, they need more than just the ability to process information or use tools; they need a clear sense of direction and a way to know if they're actually succeeding. This is where the Goal Setting and Monitoring pattern comes into play. It's about giving agents specific objectives to work towards and equipping them with the means to track their progress and determine if those objectives have been met.

要使 AI 智能体真正有效且有目的性，它们不仅需要处理信息或使用工具的能力，还需要明确的方向感和判断自身是否真正成功的方法。这就是目标设定与监控模式发挥作用的地方。该模式的核心是为智能体设定具体的工作目标，并为其配备跟踪进度和确定这些目标是否已实现的手段。

Goal Setting and Monitoring Pattern Overview

目标设定与监控速览

Think about planning a trip. You don't just spontaneously appear at your destination. You decide where you want to go (the goal state), figure out where you are starting from (the initial state), consider available options (transportation, routes, budget), and then map out a sequence of steps: book tickets, pack bags, travel to the airport/station, board the transport, arrive, find accommodation, etc. This step-by-step process, often considering dependencies and constraints, is fundamentally what we mean by planning in agentic systems.

设想规划一次旅行。你不会凭空出现在目的地。你需要决定想去哪里（目标状态），弄清楚从哪里出发（初始状态），考虑可用选项（交通工具、路线、预算），然后制定一系列步骤：订票、打包行李、前往机场/车站、登机/上车、抵达、找住宿等。这个逐步的过程，通常会考虑依赖关系和约束条件，本质上就是我们在智能体系统中所说的规划。

In the context of AI agents, planning typically involves an agent taking a high-level objective and autonomously, or semi-autonomously, generating a series of intermediate steps or sub-goals. These steps can then be executed sequentially or in a more complex flow, potentially involving other patterns like tool use, routing, or multi-agent collaboration. The planning mechanism might involve sophisticated search algorithms, logical reasoning, or increasingly, leveraging the capabilities of large language models (LLMs) to generate plausible and effective plans based on their training data and understanding of tasks.

在 AI 智能体的背景下，规划通常涉及智能体接受高层目标，并自主或半自主地生成一系列中间步骤或子目标。这些步骤可以按顺序执行，或以更复杂的流程执行，可能涉及其他模式，如工具使用、路由或多智能体协作。规划机制可能涉及复杂的搜索算法、逻辑推理，或者越来越多地利用大型语言模型（LLM）的能力，根据其训练数据和对任务的理解生成合理且有效的计划。

A good planning capability allows agents to tackle problems that aren't simple, single-step queries. It enables them to handle multi-faceted requests, adapt to changing circumstances by replanning, and orchestrate complex workflows. It's a foundational pattern that underpins many advanced agentic behaviors, turning a simple reactive system into one that can proactively work towards a defined objective.

良好的规划能力使智能体能够处理非简单的单步查询问题。它使智能体能够处理多方面的请求，通过重新规划适应不断变化的情况，并编排复杂的工作流。这是支撑许多高级智能体行为的基础模式，将简单的反应系统转变为能够主动朝着既定目标工作的系统。

Practical Applications & Use Cases

实际应用和用例

The Goal Setting and Monitoring pattern is essential for building agents that can operate autonomously and reliably in complex, real-world scenarios. Here are some practical applications:

目标设定与监控模式对于构建能够在复杂的现实场景中自主可靠运行的智能体至关重要。以下是一些实际应用：

Customer Support Automation: An agent's goal might be to "resolve customer's billing inquiry." It monitors the conversation, checks database entries, and uses tools to adjust billing. Success is monitored by confirming the billing change and receiving positive customer feedback. If the issue isn't resolved, it escalates.
Personalized Learning Systems: A learning agent might have the goal to "improve students' understanding of algebra." It monitors the student's progress on exercises, adapts teaching materials, and tracks performance metrics like accuracy and completion time, adjusting its approach if the student struggles.
Project Management Assistants: An agent could be tasked with "ensuring project milestone X is completed by Y date." It monitors task statuses, team communications, and resource availability, flagging delays and suggesting corrective actions if the goal is at risk.
Automated Trading Bots: A trading agent's goal might be to "maximize portfolio gains while staying within risk tolerance." It continuously monitors market data, its current portfolio value, and risk indicators, executing trades when conditions align with its goals and adjusting strategy if risk thresholds are breached.
Robotics and Autonomous Vehicles: An autonomous vehicle's primary goal is "safely transport passengers from A to B." It constantly monitors its environment (other vehicles, pedestrians, traffic signals), its own state (speed, fuel), and its progress along the planned route, adapting its driving behavior to achieve the goal safely and efficiently.
Content Moderation: An agent's goal could be to "identify and remove harmful content from platform X." It monitors incoming content, applies classification models, and tracks metrics like false positives/negatives, adjusting its filtering criteria or escalating ambiguous cases to human reviewers.
客户支持自动化：智能体的目标可能是"解决客户的账单查询"。它监控对话，检查数据库条目，并使用工具调整账单。通过确认账单更改并收到客户的积极反馈来监控成功。如果问题未解决，它会升级处理。
个性化学习系统：学习智能体有"提高学生对代数的理解"的目标。它监控学生在练习中的进度，调整教学材料，并跟踪准确性和完成时间等性能指标，如果学生遇到困难则调整其方法。
项目管理助手：可以为智能体分配"确保项目里程碑 X 在 Y 日期前完成"的任务。它监控任务状态、团队沟通和资源可用性，如果目标面临风险则标记延迟并建议纠正措施。
自动交易机器人：交易智能体的目标可能是"在保持风险承受范围内最大化投资组合收益"。它持续监控市场数据、当前投资组合价值和风险指标，在条件符合其目标时执行交易，并在突破风险阈值时调整策略。
机器人和自动驾驶车辆：自动驾驶车辆的主要目标是"安全地将乘客从 A 点运送到 B 点"。它不断监控其环境（其他车辆、行人、交通信号）、自身状态（速度、燃料）以及沿规划路线的进度，调整其驾驶行为以安全高效地实现目标。
内容审核：智能体的目标可能是"识别并从平台 X 中删除有害内容"。它监控传入的内容，应用分类模型，并跟踪误报/漏报等指标，调整其过滤标准或将模糊案例升级给人工审查员。

This pattern is fundamental for agents that need to operate reliably, achieve specific outcomes, and adapt to dynamic conditions, providing the necessary framework for intelligent self-management.

此模式对于需要可靠运行、实现特定成果并适应动态条件的智能体至关重要，为智能自我管理提供了必要的框架。

Hands-On Code Example

实践代码示例

To illustrate the Goal Setting and Monitoring pattern, we have an example using LangChain and OpenAI APIs. This Python script outlines an autonomous AI agent engineered to generate and refine Python code. Its core function is to produce solutions for specified problems, ensuring adherence to user-defined quality benchmarks.

为了说明目标设定与监控模式，我们有一个使用 LangChain 和 OpenAI API 的示例。这个 Python 脚本概述了一个旨在生成和完善 Python 代码的自主 AI 智能体。其核心功能是为指定的问题生成解决方案，确保符合用户定义的质量基准。

It employs a "goal-setting and monitoring" pattern where it doesn't just generate code once, but enters into an iterative cycle of creation, self-evaluation, and improvement. The agent's success is measured by its own AI-driven judgment on whether the generated code successfully meets the initial objectives. The ultimate output is a polished, commented, and ready-to-use Python file that represents the culmination of this refinement process.

它采用"目标设定与监控"模式，不仅仅生成一次代码，而是进入创建、自我评估和改进的迭代循环。智能体的成功通过其自己的 AI 驱动的判断来衡量，判断生成的代码是否成功满足初始目标。最终输出是一个经过打磨、注释完善且可以立即使用的 Python 文件，代表了这个完善过程的成果。

Dependencies:

依赖项：

bash

pip install langchain_openai openai python-dotenv
# .env file needs to contain OPENAI_API_KEY

You can best understand this script by imagining it as an autonomous AI programmer assigned to a project (see Fig. 1). The process begins when you hand the AI a detailed project brief, which is the specific coding problem it needs to solve.

你可以通过将此脚本想象为分配给项目的自主 AI 程序员来最好地理解它（见图 1）。该过程从你向 AI 提供详细的项目简报开始，这是它需要解决的特定编码问题。

text

/* Detailed source-code truncated for AI context efficiency. */
```"):
        lines = lines[1:]
    if lines and lines[-1].strip() == "```
/* Detailed source-code truncated for AI context efficiency. */

Along with this brief, you provide a strict quality checklist, which represents the objectives the final code must meet—criteria like "the solution must be simple," "it must be functionally correct," or "it needs to handle unexpected edge cases."

除了这份简报，你还提供了一份严格的质量检查清单，它代表了最终代码必须满足的目标——诸如"解决方案必须简单"、"功能必须正确"或"需要处理意外的边缘情况"等标准。

Fig.1: Goal Setting and Monitor example
图 1：目标设定与监控示例

With this assignment in hand, the AI programmer gets to work and produces its first draft of the code. However, instead of immediately submitting this initial version, it pauses to perform a crucial step: a rigorous self-review. It meticulously compares its own creation against every item on the quality checklist you provided, acting as its own quality assurance inspector. After this inspection, it renders a simple, unbiased verdict on its own progress: "True" if the work meets all standards, or "False" if it falls short.

有了这项任务，AI 程序员开始工作并生成第一版代码草稿。然而，它没有立即提交这个初始版本，而是暂停执行一个关键步骤：严格的自我审查。它仔细地将自己的创作与你提供的质量检查清单上的每一项进行比较，充当自己的质量保证检查员。在这次检查之后，它对自己的进度做出一个简单、无偏见的判断：如果工作满足所有标准则为"True"，如果不足则为"False"。

If the verdict is "False," the AI doesn't give up. It enters a thoughtful revision phase, using the insights from its self-critique to pinpoint the weaknesses and intelligently rewrite the code. This cycle of drafting, self-reviewing, and refining continues, with each iteration aiming to get closer to the goals. This process repeats until the AI finally achieves a "True" status by satisfying every requirement, or until it reaches a predefined limit of attempts, much like a developer working against a deadline. Once the code passes this final inspection, the script packages the polished solution, adding helpful comments and saving it to a clean, new Python file, ready for use.

如果判断是"False"，AI 不会放弃。它进入深思熟虑的修订阶段，利用自我批评的见解来确定弱点并智能地重写代码。这个起草、自我审查和完善的循环继续进行，每次迭代都旨在更接近目标。这个过程重复进行，直到 AI 最终通过满足每个要求而达到"True"状态，或者直到它达到预定义的尝试次数限制，就像开发人员在截止日期前工作一样。一旦代码通过了这次最终检查，脚本就会打包打磨好的解决方案，添加有用的注释并将其保存到一个干净的新 Python 文件中，准备使用。

Caveats and Considerations: It is important to note that this is an exemplary illustration and not production-ready code. For real-world applications, several factors must be taken into account. An LLM may not fully grasp the intended meaning of a goal and might incorrectly assess its performance as successful. Even if the goal is well understood, the model may hallucinate. When the same LLM is responsible for both writing the code and judging its quality, it may have a harder time discovering it is going in the wrong direction.

注意事项和考虑因素：需要注意的是，这是一个示例性的说明，而不是生产就绪的代码。对于实际应用，必须考虑几个因素。LLM 可能无法完全理解目标的预期含义，并可能错误地将其性能评估为成功。即使目标被很好地理解，模型也可能产生幻觉。当同一个 LLM 既负责编写代码又负责判断其质量时，它可能更难发现自己正朝着错误的方向前进。

Ultimately, LLMs do not produce flawless code by magic; you still need to run and test the produced code. Furthermore, the "monitoring" in the simple example is basic and creates a potential risk of the process running forever.

text

Act as an expert code reviewer with a deep commitment to producing clear, correct, and simple code. Your core mission is to eliminate code "hallucinations" by ensuring every recommendation is grounded in reality and best practices. When I provide you with a code snippet, I expect you to:

-- Identify and correct errors: Point out any logical flaws, mistakes, or potential runtime errors.
-- Simplify and refactor: Suggest changes that make the code more readable, efficient, and maintainable, without sacrificing correctness.
-- Provide clear explanations: For each suggested change, explain why it's an improvement, referencing principles of clean code, performance, or security.
-- Provide corrected code: Show "before" and "after" for suggested changes so improvements are clear.

Your feedback should be direct, constructive, and always aimed at improving code quality.

最终，LLMs 不会魔法般地产生完美的代码；你仍然需要运行和测试生成的代码。此外，简单示例中的"监控"是基础的，并造成了进程可能永远运行的潜在风险。

A more robust approach involves separating these concerns by giving specific roles to a crew of agents. For instance, I have built a personal crew of AI agents using Gemini where each has a specific role:

更健壮的方法涉及通过为智能体团队分配特定角色来分离这些关注点。例如，我使用 Gemini 构建了一个个人 AI 智能体团队，其中每个智能体都有特定的角色：

The Peer Programmer: Helps write and brainstorm code.
The Code Reviewer: Catches errors and suggests improvements.
The Documenter: Generates clear and concise documentation.
The Test Writer: Creates comprehensive unit tests.
The Prompt Refiner: Optimizes interactions with the AI.
同伴程序员：帮助编写和头脑风暴代码。
代码审查员：捕获错误并建议改进。
文档编写员：生成清晰简洁的文档。
测试编写员：创建全面的单元测试。
提示词优化器：优化与 AI 的交互。

In this multi-agent system, the Code Reviewer, acting as a separate entity from the programmer agent, has a prompt similar to the judge in the example, which significantly improves objective evaluation. This structure naturally leads to better practices, as the Test Writer agent can fulfill the need to write unit tests for the code produced by the Peer Programmer.

在这个多智能体系统中，作为独立实体的代码审查员与程序员智能体分开，拥有与示例中的判断者类似的提示词，这显著提高了客观评估。这种结构自然带来更好的实践，因为测试编写员智能体可以满足为同伴程序员产生的代码编写单元测试的需求。

I leave to the interested reader the task of adding these more sophisticated controls and making the code closer to production-ready.

我留给感兴趣的读者添加这些更复杂的控制并使代码更接近生产就绪的任务。

At a Glance

速览

What: AI agents often lack a clear direction, preventing them from acting with purpose beyond simple, reactive tasks. Without defined objectives, they cannot independently tackle complex, multi-step problems or orchestrate sophisticated workflows. Furthermore, there is no inherent mechanism for them to determine if their actions are leading to a successful outcome. This limits their autonomy and prevents them from being truly effective in dynamic, real-world scenarios where mere task execution is insufficient.

问题背景：AI 智能体通常缺乏明确的方向，阻碍了它们在简单反应性任务之外采取有目的的行动。如果没有定义的目标，它们无法独立处理复杂的多步骤问题或编排复杂的工作流。此外，它们没有内在的机制来确定其行动是否导致成功的结果。这限制了它们的自主性，并阻止它们在仅执行任务不足的动态现实世界场景中真正有效。

Why: The Goal Setting and Monitoring pattern provides a standardized solution by embedding a sense of purpose and self-assessment into agentic systems. It involves explicitly defining clear, measurable objectives for the agent to achieve. Concurrently, it establishes a monitoring mechanism that continuously tracks the agent's progress and the state of its environment against these goals. This creates a crucial feedback loop, enabling the agent to assess its performance, correct its course, and adapt its plan if it deviates from the path to success. By implementing this pattern, developers can transform simple reactive agents into proactive, goal-oriented systems capable of autonomous and reliable operation.

解决方案：目标设定与监控模式通过将目的感和自我评估嵌入智能体系统来提供标准化的解决方案。它涉及为智能体明确定义清晰、可衡量的目标。同时，它建立了一个监控机制，持续跟踪智能体的进度和环境状态，并与这些目标进行对比。这创建了一个关键的反馈循环，使智能体能够评估其表现、纠正其路线，并在偏离成功之路时调整其计划。通过实施此模式，开发人员可以将简单的反应智能体转变为能够自主可靠运行的主动的、以目标为导向的系统。

Rule of thumb: Use this pattern when an AI agent must autonomously execute a multi-step task, adapt to dynamic conditions, and reliably achieve a specific, high-level objective without constant human intervention.

实践建议：当 AI 智能体需要自主执行多步骤任务、适应动态条件并在没有持续人工干预的情况下可靠地实现特定的高级目标时，使用此模式。

Visual summary:
可视化摘要：

Fig.2: Goal design patterns
图 2：目标设计模式

Key takeaways

关键要点

Key takeaways include:
关键要点包括：

Goal Setting and Monitoring equips agents with purpose and mechanisms to track progress.
Goals should be specific, measurable, achievable, relevant, and time-bound (SMART).
Clearly defining metrics and success criteria is essential for effective monitoring.
Monitoring involves observing agent actions, environmental states, and tool outputs.
Feedback loops from monitoring allow agents to adapt, revise plans, or escalate issues.
In Google's ADK, goals are often conveyed through agent instructions, with monitoring accomplished through state management and tool interactions.
目标设定与监控为智能体配备了目的感和跟踪进度的机制。
目标应该是具体的、可衡量的、可实现的、相关的和有时限的（SMART）。
清楚地定义指标和成功标准对于有效监控至关重要。
监控涉及观察智能体的行动、环境状态和工具输出。
来自监控的反馈循环允许智能体适应、修订计划或升级问题。
在 Google 的 ADK 中，目标通常通过智能体指令传达，监控通过状态管理和工具交互完成。

Conclusion

总结

This chapter focused on the crucial paradigm of Goal Setting and Monitoring. I highlighted how this concept transforms AI agents from merely reactive systems into proactive, goal-driven entities. The text emphasized the importance of defining clear, measurable objectives and establishing rigorous monitoring procedures to track progress. Practical applications demonstrated how this paradigm supports reliable autonomous operation across various domains, including customer service and robotics. A conceptual coding example illustrates the implementation of these principles within a structured framework, using agent directives and state management to guide and evaluate an agent's achievement of its specified goals. Ultimately, equipping agents with the ability to formulate and oversee goals is a fundamental step toward building truly intelligent and accountable AI systems.

本章重点介绍了目标设定与监控的关键范式。我们强调了这个概念如何将 AI 智能体从仅是反应系统转变为主动的、以目标为驱动的实体。文本强调了定义清晰、可衡量的目标以及建立严格的监控程序来跟踪进度的重要性。实际应用展示了这个范式如何支持在各个领域（包括客户服务和机器人）的可靠自主运行。一个概念性的编码示例说明了这些原则在结构化框架内的实现，使用智能体指令和状态管理来指导和评估智能体对指定目标的实现。最终，为智能体配备制定和监督目标的能力是构建真正智能和负责任的 AI 系统的基本步骤。

References

参考文献

SMART Goals Framework. https://en.wikipedia.org/wiki/SMART_criteria

Bilingual/Chapter 12 Exception Handling And Recovery (bilingual/Chapter 12_ Exception Handling and Recovery.md)

Chapter 12: Exception Handling and Recovery

第 12 章：异常处理和恢复

For AI agents to operate reliably in diverse real-world environments, they must be able to manage unforeseen situations, errors, and malfunctions. Just as humans adapt to unexpected obstacles, intelligent agents need robust systems to detect problems, initiate recovery procedures, or at least ensure controlled failure. This essential requirement forms the basis of the Exception Handling and Recovery pattern.

要使 AI 智能体在各种现实世界环境中可靠运行，它们必须能够管理不可预见的情况、错误和故障。正如人类能够适应意外障碍一样，智能体也需要强大的系统来检测问题、启动恢复程序，或至少确保受控失败。这一基本需求构成了异常处理和恢复模式的基础。

This pattern focuses on developing exceptionally durable and resilient agents that can maintain uninterrupted functionality and operational integrity despite various difficulties and anomalies. It emphasizes the importance of both proactive preparation and reactive strategies to ensure continuous operation, even when facing challenges. This adaptability is critical for agents to function successfully in complex and unpredictable settings, ultimately boosting their overall effectiveness and trustworthiness.

此模式专注于开发极其耐用且有弹性的智能体，即使面临各种困难和异常情况，也能保持不间断的功能和操作完整性。它强调主动准备和响应策略的重要性，以确保在面临挑战时也能持续运行。这种适应性对于智能体在复杂和不可预测的环境中成功运作至关重要，最终提升其整体有效性和可信度。

The capacity to handle unexpected events ensures these AI systems are not only intelligent but also stable and reliable, which fosters greater confidence in their deployment and performance. Integrating comprehensive monitoring and diagnostic tools further strengthens an agent's ability to quickly identify and address issues, preventing potential disruptions and ensuring smoother operation in evolving conditions. These advanced systems are crucial for maintaining the integrity and efficiency of AI operations, reinforcing their ability to manage complexity and unpredictability.

处理意外事件的能力确保这些 AI 系统不仅智能，而且稳定可靠，从而增强对其部署和性能的信心。集成全面的监控和诊断工具进一步强化了智能体快速识别和解决问题的能力，防止潜在中断并确保在不断变化的条件下更顺畅地运行。这些先进系统对于维护 AI 操作的完整性和效率至关重要，增强了其管理复杂性和不可预测性的能力。

This pattern may sometimes be used with reflection. For example, if an initial attempt fails and raises an exception, a reflective process can analyze the failure and reattempt the task with a refined approach, such as an improved prompt, to resolve the error.

此模式有时可能与反思模式结合使用。例如，如果初始尝试失败并引发异常，反思过程可以分析失败原因，并使用改进的方法（如优化提示词）重新尝试任务，以解决错误。

Exception Handling and Recovery Pattern Overview

异常处理和恢复模式速览

The Exception Handling and Recovery pattern addresses the need for AI agents to manage operational failures. This pattern involves anticipating potential issues, such as tool errors or service unavailability, and developing strategies to mitigate them. These strategies may include error logging, retries, fallbacks, graceful degradation, and notifications. Additionally, the pattern emphasizes recovery mechanisms like state rollback, diagnosis, self-correction, and escalation, to restore agents to stable operation. Implementing this pattern enhances the reliability and robustness of AI agents, allowing them to function in unpredictable environments. Examples of practical applications include chatbots managing database errors, trading bots handling financial errors, and smart home agents addressing device malfunctions. The pattern ensures that agents can continue to operate effectively despite encountering complexities and failures.

异常处理和恢复模式解决了 AI 智能体应对操作失败的需求。此模式涉及预测潜在问题，例如工具错误或服务不可用，并制定相应的缓解策略。这些策略可能包括错误日志记录、重试机制、回退方案、优雅降级和通知机制。此外，该模式强调恢复机制，如状态回滚、诊断分析、自我纠正和问题升级，以将智能体恢复到稳定运行状态。实施此模式增强了 AI 智能体的可靠性和鲁棒性，使它们能够在不可预测的环境中有效运作。实际应用示例包括管理数据库错误的聊天机器人、处理金融错误的交易机器人以及解决设备故障的智能家居智能体。该模式确保智能体在遇到失败时能够继续有效运行。

Fig.1: Key components of exception handling and recovery for AI agents

图 1：AI 智能体异常处理和恢复的关键组件

Error Detection: This involves meticulously identifying operational issues as they arise. This could manifest as invalid or malformed tool outputs, specific API errors such as 404 (Not Found) or 500 (Internal Server Error) codes, unusually long response times from services or APIs, or incoherent and nonsensical responses that deviate from expected formats. Additionally, monitoring by other agents or specialized monitoring systems might be implemented for more proactive anomaly detection, enabling the system to catch potential issues before they escalate.

错误检测：这涉及仔细识别出现的操作问题。这可能表现为无效或格式错误的工具输出、特定的 API 错误（如 404（未找到）或 500（内部服务器错误）代码）、来自服务或 API 的异常长响应时间，或偏离预期格式的不连贯和无意义响应。此外，可以实施其他智能体或专门监控系统的监控，以实现更主动的异常检测，使系统能够在潜在问题升级之前捕获它们。

Error Handling: Once an error is detected, a carefully thought-out response plan is essential. This includes recording error details meticulously in logs for later debugging and analysis (logging). Retrying the action or request, sometimes with slightly adjusted parameters, may be a viable strategy, especially for transient errors (retries). Utilizing alternative strategies or methods (fallbacks) can ensure that some functionality is maintained. Where complete recovery is not immediately possible, the agent can maintain partial functionality to provide at least some value (graceful degradation). Finally, alerting human operators or other agents might be crucial for situations that require human intervention or collaboration (notification).

错误处理：一旦检测到错误，就需要一个经过深思熟虑的响应计划。这包括在日志中仔细记录错误详细信息，以便后续调试和分析（日志记录）。重试操作或请求（有时使用略微调整的参数）可能是一种可行的策略，特别是对于瞬态错误（重试）。使用替代策略或方法（回退）可以确保维持某些功能。在无法立即完全恢复的情况下，智能体可以维持部分功能以至少提供一些价值（优雅降级）。最后，向人类操作员或其他智能体发送警报可能对需要人工干预或协作的情况至关重要（通知）。

Recovery: This stage is about restoring the agent or system to a stable and operational state after an error. It could involve reversing recent changes or transactions to undo the effects of the error (state rollback). A thorough investigation into the cause of the error is vital for preventing recurrence. Adjusting the agent's plan, logic, or parameters through a self-correction mechanism or replanning process may be needed to avoid the same error in the future. In complex or severe cases, delegating the issue to a human operator or a higher-level system (escalation) might be the best course of action.

恢复：这个阶段是关于在错误后将智能体或系统恢复到稳定和可操作的状态。它可能涉及撤销最近的更改或事务以撤消错误的影响（状态回滚）。对错误原因进行彻底调查对于防止复发至关重要。通过自我纠正机制或重新规划过程调整智能体的计划、逻辑或参数可能需要避免将来出现相同的错误。在复杂或严重的情况下，将问题委托给人类操作员或更高级别的系统（升级）可能是最佳行动方案。

Implementation of this robust exception handling and recovery pattern can transform AI agents from fragile and unreliable systems into robust, dependable components capable of operating effectively and resiliently in challenging and highly unpredictable environments. This ensures that the agents maintain functionality, minimize downtime, and provide a seamless and reliable experience even when faced with unexpected issues.

实施这种强大的异常处理和恢复模式可以将 AI 智能体从脆弱和不可靠的系统转变为能够在具有挑战性和高度不可预测的环境中有效且有弹性运行的强大、可靠组件。这确保了智能体保持功能、最小化停机时间，并在面临意外问题时提供无缝和可靠的体验。

Practical Applications & Use Cases

实际应用和用例

Exception Handling and Recovery is critical for any agent deployed in a real-world scenario where perfect conditions cannot be guaranteed.

异常处理和恢复对于在无法保证完美条件的现实场景中部署的任何智能体都至关重要。

Customer Service Chatbots: If a chatbot tries to access a customer database and the database is temporarily down, it shouldn't crash. Instead, it should detect the API error, inform the user about the temporary issue, perhaps suggest trying again later, or escalate the query to a human agent.
客户服务聊天机器人：如果聊天机器人尝试访问客户数据库而数据库暂时停机，它不应该崩溃。相反，它应该检测 API 错误，通知用户临时问题，可能建议稍后再试，或将查询升级给人类智能体。
Automated Financial Trading: A trading bot attempting to execute a trade might encounter an "insufficient funds" error or a "market closed" error. It needs to handle these exceptions by logging the error, not repeatedly trying the same invalid trade, and potentially notifying the user or adjusting its strategy.
自动金融交易：尝试执行交易的交易机器人可能会遇到"资金不足"错误或"市场关闭"错误。它需要通过记录错误、避免重复尝试相同的无效交易以及可能通知用户或调整策略来处理这些异常。
Smart Home Automation: An agent controlling smart lights might fail to turn on a light due to a network issue or a device malfunction. It should detect this failure, perhaps retry, and if still unsuccessful, notify the user that the light could not be turned on and suggest manual intervention.
智能家居自动化：控制智能灯的智能体由于网络问题或设备故障而无法打开灯。它应该检测到这个失败，可能重试，如果仍然不成功，通知用户无法打开灯并建议手动干预。
Data Processing Agents: An agent tasked with processing a batch of documents might encounter a corrupted file. It should skip the corrupted file, log the error, continue processing other files, and report the skipped files at the end rather than halting the entire process.
数据处理智能体：负责处理一批文档的智能体会遇到损坏的文件。它应该跳过损坏的文件，记录错误，继续处理其他文件，并在结束时报告跳过的文件，而不是停止整个过程。
Web Scraping Agents: When a web scraping agent encounters a CAPTCHA, a changed website structure, or a server error (e.g., 404 Not Found, 503 Service Unavailable), it needs to handle these gracefully. This could involve pausing, using a proxy, or reporting the specific URL that failed.
网络爬虫智能体：当网络爬虫智能体验证码、网站结构更改或服务器错误（例如，404 未找到、503 服务不可用）时，它需要优雅地处理这些问题。这可能涉及暂停、使用代理或报告失败的特定 URL。
Robotics and Manufacturing: A robotic arm performing an assembly task might fail to pick up a component due to misalignment. It needs to detect this failure (e.g., via sensor feedback), attempt to readjust, retry the pickup, and if persistent, alert a human operator or switch to a different component.
机器人和制造：执行装配任务的机器人手臂可能由于未对齐而无法拾取组件。它需要检测到这个失败（例如，通过传感器反馈），尝试重新调整，重试拾取，如果持续存在，则警告人类操作员或切换到不同的组件。

In short, this pattern is fundamental for building agents that are not only intelligent but also reliable, resilient, and user-friendly in the face of real-world complexities.

简而言之，此模式对于构建不仅智能而且在面对现实世界复杂性时可靠、有弹性且用户友好的智能体非常重要。

Hands-On Code Example (ADK)

实践代码示例（ADK）

Exception handling and recovery are vital for system robustness and reliability. Consider, for instance, an agent's response to a failed tool call. Such failures can stem from incorrect tool input or issues with an external service that the tool depends on.

异常处理和恢复对于系统的鲁棒性和可靠性至关重要。例如，考虑智能体对失败的工具调用的响应。这种失败可能源于不正确的工具输入或工具所依赖的外部服务的问题。

text

/* Detailed source-code truncated for AI context efficiency. */

This code defines a robust location retrieval system using a ADK's SequentialAgent with three sub-agents. The primary_handler is the first agent, attempting to get precise location information using the get_precise_location_info tool. The fallback_handler acts as a backup, checking if the primary lookup failed by inspecting a state variable. If the primary lookup failed, the fallback agent extracts the city from the user's query and uses the get_general_area_info tool. The response_agent is the final agent in the sequence. It reviews the location information stored in the state. This agent is designed to present the final result to the user. If no location information was found, it apologizes. The SequentialAgent ensures that these three agents execute in a predefined order. This structure allows for a layered approach to location information retrieval.

此代码使用 ADK 的 SequentialAgent 和三个子智能体定义了一个强大的位置检索系统。primary_handler 是第一个智能体，尝试使用 get_precise_location_info 工具获取精确的位置信息。fallback_handler 充当备份，通过检查状态变量来检查主要查找是否失败。如果主要查找失败，回退智能体从用户的查询中提取城市并使用 get_general_area_info 工具。response_agent 是序列中的最终智能体。它查看存储在状态中的位置信息。此智能体旨在向用户呈现最终结果。如果没有找到位置信息，它会道歉。SequentialAgent 确保这三个智能体按预定义的顺序执行。这种结构允许采用分层方法进行位置信息检索。

At a Glance

速览

What: AI agents operating in real-world environments inevitably encounter unforeseen situations, errors, and system malfunctions. These disruptions can range from tool failures and network issues to invalid data, threatening the agent's ability to complete its tasks. Without a structured way to manage these problems, agents can be fragile, unreliable, and prone to complete failure when faced with unexpected hurdles. This unreliability makes it difficult to deploy them in critical or complex applications where consistent performance is essential.

问题背景：在现实世界环境中运行的 AI 智能体不可避免地会遇到不可预见的情况、错误和系统故障。这些中断可能从工具故障、网络问题到无效数据不等，威胁着智能体完成任务的能力。如果没有结构化的方法来管理这些问题，智能体可能会变得脆弱、不可靠，并且在面对意外障碍时容易完全失败。这种不可靠性使得难以在一致性能至关重要的关键或复杂应用程序中部署它们。

Why: The Exception Handling and Recovery pattern provides a standardized solution for building robust and resilient AI agents. It equips them with the agentic capability to anticipate, manage, and recover from operational failures. The pattern involves proactive error detection, such as monitoring tool outputs and API responses, and reactive handling strategies like logging for diagnostics, retrying transient failures, or using fallback mechanisms. For more severe issues, it defines recovery protocols, including reverting to a stable state, self-correction by adjusting its plan, or escalating the problem to a human operator. This systematic approach ensures agents can maintain operational integrity, learn from failures, and function dependably in unpredictable settings.

解决方案：异常处理和恢复模式为构建强大和有弹性的 AI 智能体提供了标准化的解决方案。它为它们配备了预测、管理和从操作失败中恢复的智能体能力。此模式涉及主动错误检测，例如监控工具输出和 API 响应，以及响应处理策略，如用于诊断的日志记录、重试瞬态故障或使用回退机制。对于更严重的问题，它定义了恢复协议，包括恢复到稳定状态、通过调整其计划进行自我纠正或将问题升级给人类操作员。这种系统方法确保智能体保持操作完整性，从失败中学习，并在不可预测的环境中可靠地运作。

Rule of thumb: Use this pattern for any AI agent deployed in a dynamic, real-world environment where system failures, tool errors, network issues, or unpredictable inputs are possible and operational reliability is a key requirement.

实践建议：对于在动态的现实世界环境中部署的任何 AI 智能体，当系统故障、工具错误、网络问题或不可预测的输入可能发生且操作可靠性是关键要求时，使用此模式。

Visual summary

可视化摘要

Fig.2: Exception handling pattern

图 2：异常处理模式

Key Takeaways

关键要点

Essential points to remember:

需要记住的要点：

Exception Handling and Recovery is essential for building robust and reliable Agents.
异常处理和恢复对于构建强大和可靠的智能体非常重要。
This pattern involves detecting errors, handling them gracefully, and implementing strategies to recover.
此模式涉及检测错误、优雅地处理错误以及实施恢复策略。
Error detection can involve validating tool outputs, checking API error codes, and using timeouts.
错误检测可能涉及验证工具输出、检查 API 错误代码以及使用超时。
Handling strategies include logging, retries, fallbacks, graceful degradation, and notifications.
处理策略包括日志记录、重试、回退、优雅降级和通知。
Recovery focuses on restoring stable operation through diagnosis, self-correction, or escalation.
恢复侧重于通过诊断、自我纠正或升级恢复稳定运行。
This pattern ensures agents can operate effectively even in unpredictable real-world environments.
此模式确保智能体在不可预测的现实世界环境中也能有效运行。

Conclusion

结论

This chapter explores the Exception Handling and Recovery pattern, which is essential for developing robust and dependable AI agents. This pattern addresses how AI agents can identify and manage unexpected issues, implement appropriate responses, and recover to a stable operational state. The chapter discusses various aspects of this pattern, including the detection of errors, the handling of these errors through mechanisms such as logging, retries, and fallbacks, and the strategies used to restore the agent or system to proper function. Practical applications of the Exception Handling and Recovery pattern are illustrated across several domains to demonstrate its relevance in handling real-world complexities and potential failures. These applications show how equipping AI agents with exception handling capabilities contributes to their reliability and adaptability in dynamic environments.

本章探讨了异常处理和恢复模式，这对于开发强大和可靠的 AI 智能体非常重要。此模式解决了 AI 智能体如何识别和管理意外问题、实施适当的响应以及恢复到稳定操作状态的需求。本章讨论了此模式的各个方面，包括错误的检测、通过日志记录、重试和回退等机制处理这些错误，以及用于将智能体或系统恢复到正常功能的策略。异常处理和恢复模式的实际应用在多个领域中得到说明，展示了其在处理现实世界复杂性和潜在失败方面的相关性。这些应用展示了为 AI 智能体配备异常处理能力如何有助于它们在动态环境中的可靠性和适应性。

References

参考文献

McConnell, S. (2004). Code Complete (2nd ed.). Microsoft Press.
Shi, Y., Pei, H., Feng, L., Zhang, Y., & Yao, D. (2024). Towards Fault Tolerance in Multi-Agent Reinforcement Learning. arXiv preprint arXiv:2412.00534.
O'Neill, V. (2022). Improving Fault Tolerance and Reliability of Heterogeneous Multi-Agent IoT Systems Using Intelligence Transfer. Electronics, 11(17), 2724.

Bilingual/Chapter 13 Human In The Loop (bilingual/Chapter 13_ Human-in-the-Loop.md)

Chapter 13: Human-in-the-Loop

第 13 章：人机协同

The Human-in-the-Loop (HITL) pattern represents a pivotal strategy in the development and deployment of Agents. It deliberately interweaves the unique strengths of human cognition—such as judgment, creativity, and nuanced understanding—with the computational power and efficiency of AI. This strategic integration is not merely an option but often a necessity, especially as AI systems become increasingly embedded in critical decision-making processes.

人机协同（Human-in-the-Loop，HITL）模式是智能体开发和部署中的关键策略。它有意识地将人类认知的独特优势——如判断力、创造力和对细微差别的理解——与 AI 的计算能力和效率相结合。这种战略性整合不仅是一种选择，在许多情况下更是一种必然，尤其是随着 AI 系统越来越深入地嵌入关键决策流程中。

The core principle of HITL is to ensure that AI operates within ethical boundaries, adheres to safety protocols, and achieves its objectives with optimal effectiveness. These concerns are particularly acute in domains characterized by complexity, ambiguity, or significant risk, where the implications of AI errors or misinterpretations can be substantial. In such scenarios, full autonomy—where AI systems function independently without any human intervention—may prove to be imprudent. HITL acknowledges this reality and emphasizes that even with rapidly advancing AI technologies, human oversight, strategic input, and collaborative interactions remain indispensable.

HITL 的核心原则是确保 AI 在道德边界内运行，遵守安全协议，并以最佳效率实现其目标。在具有复杂性、模糊性或重大风险的领域中，这些担忧尤为突出，因为 AI 错误或误解的后果可能非常严重。在这种情况下，完全自主——即 AI 系统在没有任何人工干预的情况下独立运行——可能是不明智的。HITL 承认这一现实，并强调即使 AI 技术飞速发展，人类监督、战略投入和协作互动仍然不可或缺。

The HITL approach fundamentally revolves around the idea of synergy between artificial and human intelligence. Rather than viewing AI as a replacement for human workers, HITL positions AI as a tool that augments and enhances human capabilities. This augmentation can take various forms, from automating routine tasks to providing data-driven insights that inform human decisions. The end goal is to create a collaborative ecosystem where both humans and AI Agents can leverage their distinct strengths to achieve outcomes that neither could accomplish alone.

HITL 方法从根本上围绕人工智能与人类智能之间的协同理念展开。HITL 不是将 AI 视为人类工作者的替代品，而是将 AI 定位为增强和提升人类能力的工具。这种增强可以采取多种形式，从自动化常规任务到提供数据驱动的见解来为人类决策提供信息。最终目标是创建一个协作生态系统，让人类和 AI 智能体都能利用各自的独特优势，实现任何一方都无法单独完成的成果。

In practice, HITL can be implemented in diverse ways. One common approach involves humans acting as validators or reviewers, examining AI outputs to ensure accuracy and identify potential errors. Another implementation involves humans actively guiding AI behavior, providing feedback or making corrections in real-time. In more complex setups, humans may collaborate with AI as partners, jointly solving problems or making decisions through interactive dialog or shared interfaces. Regardless of the specific implementation, the HITL pattern underscores the importance of maintaining human control and oversight, ensuring that AI systems remain aligned with human ethics, values, goals, and societal expectations.

在实践中，HITL 可以通过多种方式实施。一种常见的方法是让人类充当验证者或审查者，检查 AI 输出以确保准确性并识别潜在错误。另一种实施方式是让人类主动引导 AI 行为，实时提供反馈或进行纠正。在更复杂的设置中，人类可能与 AI 作为合作伙伴协作，通过交互式对话或共享界面共同解决问题或做出决策。无论具体实施方式如何，HITL 模式都强调保持人类控制和监督的重要性，确保 AI 系统始终与人类道德、价值观、目标和社会期望保持一致。

Human-in-the-Loop Pattern Overview

人机协同速览

The Human-in-the-Loop (HITL) pattern integrates artificial intelligence with human input to enhance Agent capabilities. This approach acknowledges that optimal AI performance frequently requires a combination of automated processing and human insight, especially in scenarios with high complexity or ethical considerations. Rather than replacing human input, HITL aims to augment human abilities by ensuring that critical judgments and decisions are informed by human understanding.

人机协同（HITL）模式将人工智能与人类输入相结合，以增强智能体能力。这种方法承认，最佳的 AI 性能通常需要自动化处理和人类洞察的结合，特别是在高度复杂或涉及道德考量的场景中。HITL 的目标不是取代人类输入，而是通过确保关键判断和决策基于人类理解来增强人类能力。

HITL encompasses several key aspects: Human Oversight, which involves monitoring AI agent performance and output (e.g., via log reviews or real-time dashboards) to ensure adherence to guidelines and prevent undesirable outcomes. Intervention and Correction occurs when an AI agent encounters errors or ambiguous scenarios and may request human intervention; human operators can rectify errors, supply missing data, or guide the agent, which also informs future agent improvements. Human Feedback for Learning is collected and used to refine AI models, prominently in methodologies like reinforcement learning with human feedback, where human preferences directly influence the agent's learning trajectory. Decision Augmentation is where an AI agent provides analyses and recommendations to a human, who then makes the final decision, enhancing human decision-making through AI-generated insights rather than full autonomy. Human-Agent Collaboration is a cooperative interaction where humans and AI agents contribute their respective strengths; routine data processing may be handled by the agent, while creative problem-solving or complex negotiations are managed by the human. Finally, Escalation Policies are established protocols that dictate when and how an agent should escalate tasks to human operators, preventing errors in situations beyond the agent's capability.

HITL 包含几个关键方面：人类监督涉及监控 AI 智能体性能和输出（例如通过日志审查或实时仪表板），以确保遵循指南并防止不良结果。干预和纠正发生在 AI 智能体遇到错误或模糊场景并可能请求人工干预时；人类操作员可以纠正错误、提供缺失数据或指导智能体，这也有助于未来智能体的改进。用于学习的人类反馈被收集并用于完善 AI 模型，在带有人类反馈的强化学习等方法中尤为突出，其中人类偏好直接影响智能体的学习轨迹。决策增强是指 AI 智能体向人类提供分析和建议，由人类做出最终决定，通过 AI 生成的见解而非完全自主来增强人类决策。人机协作是一种合作互动，人类和 AI 智能体贡献各自的优势；常规数据处理可能由智能体处理，而创造性问题解决或复杂谈判则由人类管理。最后，升级策略是建立的协议，规定智能体何时以及如何将任务升级给人类操作员，以防止在超出智能体能力范围的情况下出现错误。

Implementing HITL patterns enables the use of Agents in sensitive sectors where full autonomy is not feasible or permitted. It also provides a mechanism for ongoing improvement through feedback loops. For example, in finance, the final approval of a large corporate loan requires a human loan officer to assess qualitative factors like leadership character. Similarly, in the legal field, core principles of justice and accountability demand that a human judge retain final authority over critical decisions like sentencing, which involve complex moral reasoning.

实施 HITL 模式使得在完全自主不可行或不被允许的敏感行业中使用智能体成为可能。它还通过反馈循环提供了持续改进的机制。例如在金融领域，大型企业贷款的最终批准需要人类贷款官员评估诸如领导层品格等定性因素。同样在法律领域，正义和问责制的核心原则要求人类法官保留对关键决定（如量刑）的最终权威，这些决定涉及复杂的道德推理。

Caveats: Despite its benefits, the HITL pattern has significant caveats, chief among them being a lack of scalability. While human oversight provides high accuracy, operators cannot manage millions of tasks, creating a fundamental trade-off that often requires a hybrid approach combining automation for scale and HITL for accuracy. Furthermore, the effectiveness of this pattern is heavily dependent on the expertise of the human operators; for example, while an AI can generate software code, only a skilled developer can accurately identify subtle errors and provide the correct guidance to fix them. This need for expertise also applies when using HITL to generate training data, as human annotators may require special training to learn how to correct an AI in a way that produces high-quality data. Lastly, implementing HITL raises significant privacy concerns, as sensitive information must often be rigorously anonymized before it can be exposed to a human operator, adding another layer of process complexity.

注意事项：尽管 HITL 模式具有诸多优势，但也存在重要的注意事项，其中最主要的是可扩展性不足。虽然人类监督提供了高精度，但操作员无法管理数百万个任务，这造成了基本权衡，通常需要采用混合方法，结合自动化实现规模化和 HITL 实现准确性。此外，此模式的有效性在很大程度上依赖于人类操作员的专业知识；例如虽然 AI 可以生成软件代码，但只有熟练的开发人员才能准确识别细微错误并提供正确的修复指导。这种对专业知识的需求同样适用于使用 HITL 生成训练数据时，因为人类标注员可能需要特殊培训才能学会如何以产生高质量数据的方式纠正 AI。最后，实施 HITL 会引发重大隐私问题，因为敏感信息在暴露给人类操作员之前通常必须严格匿名化，这增加了另一层流程复杂性。

Practical Applications & Use Cases

实际应用和用例

The Human-in-the-Loop pattern is vital across a wide range of industries and applications, particularly where accuracy, safety, ethics, or nuanced understanding are paramount.

人机协同模式在广泛的行业和应用中至关重要，特别是在准确性、安全性、道德考量或细微理解至关重要的领域。

Content Moderation: AI agents can rapidly filter vast amounts of online content for violations (e.g., hate speech, spam). However, ambiguous cases or borderline content are escalated to human moderators for review and final decision, ensuring nuanced judgment and adherence to complex policies.
内容审核：AI 智能体可以快速过滤大量在线内容以查找违规内容（如仇恨言论、垃圾邮件）。然而，模糊案例或边界内容会升级给人类审核员进行审查和最终决定，确保细致入微的判断并遵循复杂政策。
Autonomous Driving: While self-driving cars handle most driving tasks autonomously, they are designed to hand over control to a human driver in complex, unpredictable, or dangerous situations that the AI cannot confidently navigate (e.g., extreme weather, unusual road conditions).
自动驾驶：虽然自动驾驶汽车自主处理大多数驾驶任务，但它们被设计为在 AI 无法自信导航的复杂、不可预测或危险情况下（如极端天气、异常道路条件）将控制权交还给人类驾驶员。
Financial Fraud Detection: AI systems can flag suspicious transactions based on patterns. However, high-risk or ambiguous alerts are often sent to human analysts who investigate further, contact customers, and make the final determination on whether a transaction is fraudulent.
金融欺诈检测：AI 系统可以根据模式标记可疑交易。然而，高风险或模糊的警报通常会发送给人类分析师，他们进一步调查、联系客户，并对交易是否欺诈做出最终决定。
Legal Document Review: AI can quickly scan and categorize thousands of legal documents to identify relevant clauses or evidence. Human legal professionals then review the AI's findings for accuracy, context, and legal implications, especially for critical cases.
法律文件审查：AI 可快速扫描和分类数千份法律文件以识别相关条款或证据。然后，人类法律专业人员审查 AI 的发现以确保准确性、上下文和法律含义，特别是对于关键案例。
Customer Support (Complex Queries): A chatbot might handle routine customer inquiries. If the user's problem is too complex, emotionally charged, or requires empathy that the AI cannot provide, the conversation is seamlessly handed over to a human support agent.
客户支持（复杂查询）：聊天机器人可能处理常规客户查询。如果用户问题过于复杂、情绪激动或需要 AI 无法提供的同理心，对话将无缝交接给人类支持人员。
Data Labeling and Annotation: AI models often require large datasets of labeled data for training. Humans are put in the loop to accurately label images, text, or audio, providing the ground truth that the AI learns from. This is a continuous process as models evolve.
数据标注和注释：AI 模型通常需要大量标注数据集进行训练。人类被纳入循环以准确标注图像、文本或音频，为 AI 学习提供基本事实。随着模型发展，这是一个持续过程。
Generative AI Refinement: When an LLM generates creative content (e.g., marketing copy, design ideas), human editors or designers review and refine the output, ensuring it meets brand guidelines, resonates with the target audience, and maintains quality.
生成 AI 完善：当 LLM 生成创意内容（如营销文案、设计理念）时，人类编辑或设计师审查和完善输出，确保其符合品牌指南、与目标受众产生共鸣并保持质量。
Autonomous Networks: AI systems are capable of analyzing alerts and forecasting network issues and traffic anomalies by leveraging key performance indicators (KPIs) and identified patterns. Nevertheless, crucial decisions—such as addressing high-risk alerts—are frequently escalated to human analysts. These analysts conduct further investigation and make the ultimate determination regarding the approval of network changes.
自主网络：AI 系统能够通过利用关键性能指标（KPI）和识别模式来分析警报并预测网络问题和流量异常。然而，关键决策——如处理高风险警报——经常升级给人类分析师。这些分析师进行进一步调查，并对网络更改的批准做出最终决定。

This pattern exemplifies a practical method for AI implementation. It harnesses AI for enhanced scalability and efficiency, while maintaining human oversight to ensure quality, safety, and ethical compliance.

此模式体现了 AI 实施的实用方法。它利用 AI 实现增强的可扩展性和效率，同时保持人类监督以确保质量、安全性和道德合规性。

"Human-on-the-loop" is a variation of this pattern where human experts define the overarching policy, and the AI then handles immediate actions to ensure compliance. Let's consider two examples:

"人在循环外"（Human-on-the-loop）是此模式的一个变体，其中人类专家定义总体策略，然后 AI 处理即时操作以确保合规性。让我们考虑两个例子：

Automated financial trading system: In this scenario, a human financial expert sets the overarching investment strategy and rules. For instance, the human might define the policy as: "Maintain a portfolio of 70% tech stocks and 30% bonds, do not invest more than 5% in any single company, and automatically sell any stock that falls 10% below its purchase price." The AI then monitors the stock market in real-time, executing trades instantly when these predefined conditions are met. The AI is handling the immediate, high-speed actions based on the slower, more strategic policy set by the human operator.
自动金融交易系统：在此场景中，人类金融专家设定总体投资策略和规则。例如，人类可能将策略定义为："维持 70% 科技股和 30% 债券的投资组合，不要在任何单一公司投资超过 5%，并自动出售任何跌幅低于购买价格 10% 的股票。"然后，AI 实时监控股票市场，在满足这些预定义条件时立即执行交易。AI 正在根据人类操作员设定的较慢、更具战略性的策略处理即时、高速的操作。
Modern call center: In this setup, a human manager establishes high-level policies for customer interactions. For instance, the manager might set rules such as "any call mentioning 'service outage' should be immediately routed to a technical support specialist," or "if a customer's tone of voice indicates high frustration, the system should offer to connect them directly to a human agent." The AI system then handles the initial customer interactions, listening to and interpreting their needs in real-time. It autonomously executes the manager's policies by instantly routing the calls or offering escalations without needing human intervention for each individual case. This allows the AI to manage the high volume of immediate actions according to the slower, strategic guidance provided by the human operator.
现代呼叫中心：在此设置中，人类经理为客户互动建立高级策略。例如，经理可能设置规则，如"任何提到'服务中断'的呼叫应立即转接给技术支持专家"，或"如果客户的语调表明高度沮丧，系统应提供直接连接到人类支持人员"。然后，AI 系统处理初始客户互动，实时倾听和解释他们的需求。它通过立即转接呼叫或提供升级来自主执行经理的策略，无需对每个单独案例进行人工干预。这允许 AI 根据人类操作员提供的较慢、战略性的指导管理大量即时操作。

Hands-On Code Example

实践代码示例

To demonstrate the Human-in-the-Loop pattern, an ADK agent can identify scenarios requiring human review and initiate an escalation process . This allows for human intervention in situations where the agent's autonomous decision-making capabilities are limited or when complex judgments are required. This is not an isolated feature; other popular frameworks have adopted similar capabilities. LangChain, for instance, also provides tools to implement these types of interactions.

为演示人机协同模式，ADK 智能体可识别需要人工审查的场景并启动升级过程。这允许在智能体的自主决策能力有限或需要复杂判断时进行人工干预。此功能并非孤立存在；其他流行框架也采用了类似能力。例如，LangChain 同样提供了实现此类交互的工具。

text

/* Detailed source-code truncated for AI context efficiency. */

This code offers a blueprint for creating a technical support agent using Google's ADK, designed around a HITL framework. The agent acts as an intelligent first line of support, configured with specific instructions and equipped with tools like troubleshoot_issue, create_ticket, and escalate_to_human to manage a complete support workflow. The escalation tool is a core part of the HITL design, ensuring complex or sensitive cases are passed to human specialists.

此代码提供了使用 Google ADK 创建技术支持智能体的蓝图，围绕 HITL 框架设计。智能体充当智能第一线支持，配置了特定指令，并配备了 troubleshoot_issue、create_ticket 和 escalate_to_human 等工具来管理完整的支持工作流。升级工具是 HITL 设计的核心部分，确保复杂或敏感案例传递给人类专家。

A key feature of this architecture is its capacity for deep personalization, achieved through a dedicated callback function. Before contacting the LLM, this function dynamically retrieves customer-specific data—such as their name, tier, and purchase history—from the agent's state. This context is then injected into the prompt as a system message, enabling the agent to provide highly tailored and informed responses that reference the user's history. By combining a structured workflow with essential human oversight and dynamic personalization, this code serves as a practical example of how the ADK facilitates the development of sophisticated and robust AI support solutions.

此架构的一个关键特性是其深度个性化能力，通过专用回调函数实现。在联系 LLM 之前，此函数从智能体状态中动态检索客户特定数据——如姓名、等级和购买历史。然后将此上下文作为系统消息注入提示词中，使智能体能够提供高度定制和知情的响应，引用用户历史记录。通过将结构化工作流与基本人类监督和动态个性化相结合，此代码展示了 ADK 如何促进开发复杂且强大的 AI 支持解决方案。

At a Glance

速览

What: AI systems, including advanced LLMs, often struggle with tasks that require nuanced judgment, ethical reasoning, or a deep understanding of complex, ambiguous contexts. Deploying fully autonomous AI in high-stakes environments carries significant risks, as errors can lead to severe safety, financial, or ethical consequences. These systems lack the inherent creativity and common-sense reasoning that humans possess. Consequently, relying solely on automation in critical decision-making processes is often imprudent and can undermine the system's overall effectiveness and trustworthiness.

问题背景： AI 系统（包括高级 LLM）通常在需要细致入微判断、道德推理或对复杂模糊上下文深刻理解的任务中表现不佳。在高风险环境中部署完全自主的 AI 具有重大风险，因为错误可能导致严重的安全、财务或道德后果。这些系统缺乏人类固有的创造力和常识推理能力。因此，在关键决策过程中仅依赖自动化通常是不明智的，并可能损害系统的整体有效性和可信度。

Why: The Human-in-the-Loop (HITL) pattern provides a standardized solution by strategically integrating human oversight into AI workflows. This agentic approach creates a symbiotic partnership where AI handles computational heavy-lifting and data processing, while humans provide critical validation, feedback, and intervention. By doing so, HITL ensures that AI actions align with human values and safety protocols. This collaborative framework not only mitigates the risks of full automation but also enhances the system's capabilities through continuous learning from human input. Ultimately, this leads to more robust, accurate, and ethical outcomes that neither human nor AI could achieve alone.

解决方案： 人机协同（HITL）模式通过战略性地将人类监督整合到 AI 工作流中提供了标准化解决方案。这种智能体方法创建了共生伙伴关系，AI 处理计算繁重工作和数据处理，而人类提供关键验证、反馈和干预。通过这样做，HITL 确保 AI 行动与人类价值观和安全协议保持一致。这种协作框架不仅降低了完全自动化的风险，还通过从人类输入中持续学习来增强系统能力。最终，这带来了更强大、准确和道德的结果，这些结果是人类或 AI 单独无法实现的。

Rule of thumb: Use this pattern when deploying AI in domains where errors have significant safety, ethical, or financial consequences, such as in healthcare, finance, or autonomous systems. It is essential for tasks involving ambiguity and nuance that LLMs cannot reliably handle, like content moderation or complex customer support escalations. Employ HITL when the goal is to continuously improve an AI model with high-quality, human-labeled data or to refine generative AI outputs to meet specific quality standards.

实践建议： 在部署 AI 到错误会产生重大安全、道德或财务后果的领域时使用此模式，例如医疗保健、金融或自主系统。对于涉及 LLM 无法可靠处理的模糊性和细微差别的任务（如内容审核或复杂客户支持升级），它至关重要。当目标是使用高质量人类标注数据持续改进 AI 模型或完善生成 AI 输出以满足特定质量标准时，采用 HITL。

Visual summary:

可视化摘要：

Fig.1: Human in the loop design pattern

图 1：人机协同设计模式

Key Takeaways

关键要点

Key takeaways include:

关键要点包括：

Human-in-the-Loop (HITL) integrates human intelligence and judgment into AI workflows.
人机协同（HITL）将人类智能和判断整合到 AI 工作流中。
It's crucial for safety, ethics, and effectiveness in complex or high-stakes scenarios.
它在复杂或高风险场景中对安全性、道德和有效性至关重要。
Key aspects include human oversight, intervention, feedback for learning, and decision augmentation.
关键方面包括人类监督、干预、学习反馈和决策增强。
Escalation policies are essential for agents to know when to hand off to a human.
升级策略对于智能体何时交接给人类至关重要。
HITL allows for responsible AI deployment and continuous improvement.
HITL 允许负责任的 AI 部署和持续改进。
The primary drawbacks of Human-in-the-Loop are its inherent lack of scalability, creating a trade-off between accuracy and volume, and its dependence on highly skilled domain experts for effective intervention.
人机协同的主要缺点是其固有的可扩展性不足，在准确性和数量之间造成权衡，以及对高技能领域专家进行有效干预的依赖性。
Its implementation presents operational challenges, including the need to train human operators for data generation and to address privacy concerns by anonymizing sensitive information.
其实施带来了操作挑战，包括需要培训人类操作员进行数据生成，以及通过匿名化敏感信息来解决隐私问题。

Conclusion

结论

This chapter explored the vital Human-in-the-Loop (HITL) pattern, emphasizing its role in creating robust, safe, and ethical AI systems. We discussed how integrating human oversight, intervention, and feedback into agent workflows can significantly enhance their performance and trustworthiness, especially in complex and sensitive domains. The practical applications demonstrated HITL's widespread utility, from content moderation and medical diagnosis to autonomous driving and customer support. The conceptual code example provided a glimpse into how ADK can facilitate these human-agent interactions through escalation mechanisms. As AI capabilities continue to advance, HITL remains a cornerstone for responsible AI development, ensuring that human values and expertise remain central to intelligent system design.

本章探讨了至关重要的人机协同（HITL）模式，强调了其在创建强大、安全和道德的 AI 系统中的作用。我们讨论了如何将人类监督、干预和反馈整合到智能体工作流中可以显著增强其性能和可信度，特别是在复杂和敏感的领域中。实际应用展示了 HITL 的广泛实用性，从内容审核和医疗诊断到自动驾驶和客户支持。概念性代码示例提供了 ADK 如何通过升级机制促进这些人机交互的一瞥。随着 AI 能力不断进步，HITL 仍然是负责任的 AI 开发的基石，确保人类价值观和专业知识在智能系统设计中保持核心地位。

References

参考文献

A Survey of Human-in-the-loop for Machine Learning, Xingjiao Wu, Luwei Xiao, Yixuan Sun, Junhang Zhang, Tianlong Ma, Liang He, https://arxiv.org/abs/2108.00941

Bilingual/Chapter 14 Knowledge Retrieval (RAG) (bilingual/Chapter 14_ Knowledge Retrieval (RAG).md)

Chapter 14: Knowledge Retrieval (RAG)

第 14 章：知识检索（RAG）

LLMs exhibit substantial capabilities in generating human-like text. However, their knowledge base is typically confined to the data on which they were trained, limiting their access to real-time information, specific company data, or highly specialized details. Knowledge Retrieval (RAG, or Retrieval Augmented Generation), addresses this limitation. RAG enables LLMs to access and integrate external, current, and context-specific information, thereby enhancing the accuracy, relevance, and factual basis of their outputs.

LLM 在生成类人文本方面展现出了强大的能力。然而，它们的知识库通常局限于训练时使用的数据，这限制了它们对实时信息、特定公司数据或高度专业化细节的访问。知识检索（RAG，即检索增强生成）技术正是为了解决这一局限性而设计的。RAG 使 LLM 能够访问和整合外部信息、实时数据和特定上下文内容，从而显著提高其输出的准确性、相关性和事实基础。

For AI agents, this is crucial as it allows them to ground their actions and responses in real-time, verifiable data beyond their static training. This capability enables them to perform complex tasks accurately, such as accessing the latest company policies to answer a specific question or checking current inventory before placing an order. By integrating external knowledge, RAG transforms agents from simple conversationalists into effective, data-driven tools capable of executing meaningful work.

对于 AI 智能体来说，这一能力尤为关键——它让智能体能够基于实时、可验证的数据来采取行动和作出回应，而不仅仅依赖于静态的训练数据。这种能力使得智能体能够准确地执行复杂任务，例如查询最新的公司政策来回答特定问题，或在下订单前检查当前库存状况。通过整合外部知识，RAG 将智能体从简单的对话者转变为能够执行有意义工作的有效、数据驱动的工具。

Knowledge Retrieval (RAG) Pattern Overview

知识检索（RAG）模式概述

The Knowledge Retrieval (RAG) pattern significantly enhances the capabilities of LLMs by granting them access to external knowledge bases before generating a response. Instead of relying solely on their internal, pre-trained knowledge, RAG allows LLMs to "look up" information, much like a human might consult a book or search the internet. This process empowers LLMs to provide more accurate, up-to-date, and verifiable answers.

知识检索（RAG）模式通过在生成响应之前赋予 LLM 访问外部知识库的权限，显著增强了它们的能力。与仅依赖内部预训练知识不同，RAG 允许 LLM "查找"信息，就像人类查阅书籍或搜索互联网一样。这一过程使 LLM 能够提供更准确、更新及时且可验证的答案。

When a user poses a question or gives a prompt to an AI system using RAG, the query isn't sent directly to the LLM. Instead, the system first scours a vast external knowledge base—a highly organized library of documents, databases, or web pages—for relevant information. This search is not a simple keyword match; it's a "semantic search" that understands the user's intent and the meaning behind their words. This initial search pulls out the most pertinent snippets or "chunks" of information. These extracted pieces are then "augmented," or added, to the original prompt, creating a richer, more informed query. Finally, this enhanced prompt is sent to the LLM. With this additional context, the LLM can generate a response that is not only fluent and natural but also factually grounded in the retrieved data.

当用户向使用 RAG 的 AI 系统提出问题或发出指令时，查询不会直接发送给 LLM。相反，系统首先在一个庞大的外部知识库（高度组织化的文档、数据库或网页集合）中搜索相关信息。这种搜索不是简单的关键字匹配，而是一种能够理解用户意图和词语背后含义的"语义搜索"。初始搜索会提取出最相关的信息片段或"块"。然后，这些提取的片段被"增强"到原始提示中，形成一个更丰富、信息量更大的查询。最后，这个增强的提示被发送给 LLM。借助这些额外的上下文信息，LLM 能够生成不仅流畅自然，而且在事实上基于检索数据的响应。

The RAG framework provides several significant benefits. It allows LLMs to access up-to-date information, thereby overcoming the constraints of their static training data. This approach also reduces the risk of "hallucination"—the generation of false information—by grounding responses in verifiable data. Moreover, LLMs can utilize specialized knowledge found in internal company documents or wikis. A vital advantage of this process is the capability to offer "citations," which pinpoint the exact source of information, thereby enhancing the trustworthiness and verifiability of the AI's responses.

RAG 框架提供了几个重要优势。它允许 LLM 访问最新信息，从而克服了静态训练数据的局限性。这种方法还通过将响应建立在可验证的数据上，减少了"幻觉"（生成虚假信息）的风险。此外，LLM 可以利用内部公司文档或维基中的专业知识。这一过程的另一个重要优势是能够提供"引用"，即明确指出信息的来源，从而增强 AI 响应的可信度和可验证性。

To fully appreciate how RAG functions, it's essential to understand a few core concepts (see Fig.1):

要充分理解 RAG 的工作原理，需要掌握几个核心概念（见图 1）：

Embeddings: In the context of LLMs, embeddings are numerical representations of text, such as words, phrases, or entire documents. These representations are in the form of a vector, which is a list of numbers. The key idea is to capture the semantic meaning and the relationships between different pieces of text in a mathematical space. Words or phrases with similar meanings will have embeddings that are closer to each other in this vector space. For instance, imagine a simple 2D graph. The word "cat" might be represented by the coordinates (2, 3), while "kitten" would be very close at (2.1, 3.1). In contrast, the word "car" would have a distant coordinate like (8, 1), reflecting its different meaning. In reality, these embeddings are in a much higher-dimensional space with hundreds or even thousands of dimensions, allowing for a very nuanced understanding of language.

嵌入（Embeddings）：在 LLM 的语境中，嵌入是文本的数值表示形式，可以是单词、短语或整个文档。这些表示以向量的形式存在，即一系列数字。其核心思想是在数学空间中捕捉不同文本片段的语义含义和关系。具有相似含义的单词或短语在向量空间中会彼此靠近。例如，想象一个简单的二维坐标系，"cat"这个词可能位于坐标 (2, 3)，而"kitten"则非常接近，位于 (2.1, 3.1)。相比之下，"car"这个词的位置则较远，比如 (8, 1)，反映出其不同的含义。实际上，这些嵌入存在于具有数百甚至数千个维度的高维空间中，从而能够对语言进行非常细致的理解。

Text Similarity: Text similarity refers to the measure of how alike two pieces of text are. This can be at a surface level, looking at the overlap of words (lexical similarity), or at a deeper, meaning-based level. In the context of RAG, text similarity is crucial for finding the most relevant information in the knowledge base that corresponds to a user's query. For instance, consider the sentences: "What is the capital of France?" and "Which city is the capital of France?". While the wording is different, they are asking the same question. A good text similarity model would recognize this and assign a high similarity score to these two sentences, even though they only share a few words. This is often calculated using the embeddings of the texts.

文本相似度：文本相似度指的是衡量两段文本相似程度的指标。这可以是表面层次的，主要关注词汇的重叠（词汇相似度），也可以是更深层次的，基于文本的含义。在 RAG 的语境中，文本相似度对于在知识库中查找与用户查询最相关的信息至关重要。例如，考虑这两个句子："What is the capital of France?"和"Which city is the capital of France?"。虽然措辞不同，但它们询问的是同一个问题。一个好的文本相似度模型能够识别这一点，并为这两个句子分配较高的相似度分数，即使它们只共享少数几个单词。这通常通过计算文本的嵌入来实现。

Semantic Similarity and Distance: Semantic similarity is a more advanced form of text similarity that focuses purely on the meaning and context of the text, rather than just the words used. It aims to understand if two pieces of text convey the same concept or idea. Semantic distance is the inverse of this; a high semantic similarity implies a low semantic distance, and vice versa. In RAG, semantic search relies on finding documents with the smallest semantic distance to the user's query. For instance, the phrases "a furry feline companion" and "a domestic cat" have no words in common besides "a". However, a model that understands semantic similarity would recognize that they refer to the same thing and would consider them to be highly similar. This is because their embeddings would be very close in the vector space, indicating a small semantic distance. This is the "smart search" that allows RAG to find relevant information even when the user's wording doesn't exactly match the text in the knowledge base.

语义相似度和距离：语义相似度是文本相似度的一种更高级形式，它纯粹关注文本的含义和上下文，而不仅仅是使用的单词。其目标是理解两段文本是否传达相同的概念或想法。语义距离则是语义相似度的反义词；高语义相似度意味着低语义距离，反之亦然。在 RAG 中，语义搜索依赖于查找与用户查询语义距离最小的文档。例如，短语"a furry feline companion"和"a domestic cat"除了冠词"a"外没有共同的单词。然而，能够理解语义相似度的模型会识别出它们指的是同一事物，并认为它们高度相似。这是因为它们的嵌入在向量空间中非常接近，表明语义距离很小。这就是 RAG 能够找到相关信息的"智能搜索"机制——即使用户的措辞与知识库中的文本不完全匹配。

Fig.1: RAG Core Concepts: Chunking, Embeddings, and Vector Database

图 1：RAG 核心概念：分块、嵌入和向量数据库

Chunking of Documents: Chunking is the process of breaking down large documents into smaller, more manageable pieces, or "chunks." For a RAG system to work efficiently, it cannot feed entire large documents into the LLM. Instead, it processes these smaller chunks. The way documents are chunked is important for preserving the context and meaning of the information. For instance, instead of treating a 50-page user manual as a single block of text, a chunking strategy might break it down into sections, paragraphs, or even sentences. For instance, a section on "Troubleshooting" would be a separate chunk from the "Installation Guide." When a user asks a question about a specific problem, the RAG system can then retrieve the most relevant troubleshooting chunk, rather than the entire manual. This makes the retrieval process faster and the information provided to the LLM more focused and relevant to the user's immediate need.

文档分块：分块是将大型文档分解为更小、更易于管理的片段或"块"的过程。为了使 RAG 系统高效工作，它不能将整个大型文档直接输入 LLM，而是处理这些更小的块。文档分块的方式对于保持信息的上下文和含义至关重要。例如，与其将 50 页的用户手册视为单个文本块，分块策略可能会将其分解为章节、段落甚至句子。这样，"故障排除"部分就可以与"安装指南"分开作为独立的块。当用户询问特定问题时，RAG 系统可以检索最相关的故障排除块，而不是整个手册。这使得检索过程更快，提供给 LLM 的信息更加集中，更符合用户的直接需求。

Once documents are chunked, the RAG system must employ a retrieval technique to find the most relevant pieces for a given query. The primary method is vector search, which uses embeddings and semantic distance to find chunks that are conceptually similar to the user's question. An older, but still valuable, technique is BM25, a keyword-based algorithm that ranks chunks based on term frequency without understanding semantic meaning. To get the best of both worlds, hybrid search approaches are often used, combining the keyword precision of BM25 with the contextual understanding of semantic search. This fusion allows for more robust and accurate retrieval, capturing both literal matches and conceptual relevance.

文档分块完成后，RAG 系统必须使用检索技术来找到给定查询的最相关片段。主要方法是向量搜索，它利用嵌入和语义距离来查找概念上与用户问题相似的块。另一种较旧但仍然有价值的技术是 BM25，这是一种基于关键字的算法，根据词频对块进行排名，但不理解语义含义。为了获得两全其美的效果，通常使用混合搜索方法，将 BM25 的关键字精度与语义搜索的上下文理解相结合。这种融合实现了更强大和准确的检索，能够捕获字面匹配和概念相关性。

Vector databases: A vector database is a specialized type of database designed to store and query embeddings efficiently. After documents are chunked and converted into embeddings, these high-dimensional vectors are stored in a vector database. Traditional retrieval techniques, like keyword-based search, are excellent at finding documents containing exact words from a query but lack a deep understanding of language. They wouldn't recognize that "furry feline companion" means "cat." This is where vector databases excel. They are built specifically for semantic search. By storing text as numerical vectors, they can find results based on conceptual meaning, not just keyword overlap. When a user's query is also converted into a vector, the database uses highly optimized algorithms (like HNSW - Hierarchical Navigable Small World) to rapidly search through millions of vectors and find the ones that are "closest" in meaning. This approach is far superior for RAG because it uncovers relevant context even if the user's phrasing is completely different from the source documents. In essence, while other techniques search for words, vector databases search for meaning. This technology is implemented in various forms, from managed databases like Pinecone and Weaviate to open-source solutions such as Chroma DB, Milvus, and Qdrant. Even existing databases can be augmented with vector search capabilities, as seen with Redis, Elasticsearch, and Postgres (using the pgvector extension). The core retrieval mechanisms are often powered by libraries like Meta AI's FAISS or Google Research's ScaNN, which are fundamental to the efficiency of these systems.

向量数据库：向量数据库是一种专门设计用于高效存储和查询嵌入的专用数据库类型。在文档被分块并转换为嵌入后，这些高维向量被存储在向量数据库中。传统的检索技术（如基于关键字的搜索）非常擅长查找包含查询中确切单词的文档，但缺乏对语言的深入理解。它们无法识别"furry feline companion"意味着"cat"。这就是向量数据库的优势所在——它们专门为语义搜索而构建。通过将文本存储为数值向量，它们可以基于概念含义而不仅仅是关键字重叠来查找结果。当用户的查询也被转换为向量时，数据库使用高度优化的算法（如 HNSW——分层可导航小世界）快速搜索数百万个向量，并找到在含义上"最接近"的向量。这种方法对于 RAG 来说要优越得多，因为即使用户的措辞与源文档完全不同，它也能发现相关上下文。本质上，虽然其他技术搜索单词，向量数据库搜索含义。这项技术以各种形式实现，从托管数据库如 Pinecone 和 Weaviate，到开源解决方案如 Chroma DB、Milvus 和 Qdrant。甚至现有数据库也可以增强向量搜索功能，如 Redis、Elasticsearch 和 Postgres（使用 pgvector 扩展）。核心检索机制通常由 Meta AI 的 FAISS 或 Google Research 的 ScaNN 等库提供支持，这些库对这些系统的效率至关重要。

RAG's Challenges: Despite its power, the RAG pattern is not without its challenges. A primary issue arises when the information needed to answer a query is not confined to a single chunk but is spread across multiple parts of a document or even several documents. In such cases, the retriever might fail to gather all the necessary context, leading to an incomplete or inaccurate answer. The system's effectiveness is also highly dependent on the quality of the chunking and retrieval process; if irrelevant chunks are retrieved, it can introduce noise and confuse the LLM. Furthermore, effectively synthesizing information from potentially contradictory sources remains a significant hurdle for these systems. Besides that, another challenge is that RAG requires the entire knowledge base to be pre-processed and stored in specialized databases, such as vector or graph databases, which is a considerable undertaking. Consequently, this knowledge requires periodic reconciliation to remain up-to-date, a crucial task when dealing with evolving sources like company wikis. This entire process can have a noticeable impact on performance, increasing latency, operational costs, and the number of tokens used in the final prompt.

RAG 的挑战：尽管功能强大，RAG 模式并非没有挑战。一个主要问题出现在回答查询所需的信息不局限于单个块，而是分散在文档的多个部分甚至多个文档中时。在这种情况下，检索器可能无法收集所有必要的上下文，导致答案不完整或不准确。系统的有效性还高度依赖于分块和检索过程的质量；如果检索到不相关的块，可能会引入噪声并混淆 LLM。此外，有效综合来自潜在矛盾来源的信息仍然是这些系统的一个重大障碍。除此之外，另一个挑战是 RAG 需要将整个知识库预处理并存储在专门的数据库中（如向量或图数据库），这是一项相当大的工作。因此，这些知识需要定期更新以保持最新，这在处理不断演变的来源（如公司维基）时是一项关键任务。整个过程可能对性能产生明显影响，增加延迟、运营成本和最终提示中使用的 token 数量。

In summary, the Retrieval-Augmented Generation (RAG) pattern represents a significant leap forward in making AI more knowledgeable and reliable. By seamlessly integrating an external knowledge retrieval step into the generation process, RAG addresses some of the core limitations of standalone LLMs. The foundational concepts of embeddings and semantic similarity, combined with retrieval techniques like keyword and hybrid search, allow the system to intelligently find relevant information, which is made manageable through strategic chunking. This entire retrieval process is powered by specialized vector databases designed to store and efficiently query millions of embeddings at scale. While challenges in retrieving fragmented or contradictory information persist, RAG empowers LLMs to produce answers that are not only contextually appropriate but also anchored in verifiable facts, fostering greater trust and utility in AI.

总之，检索增强生成（RAG）模式代表了使 AI 更加知识渊博和可靠的重大飞跃。通过将外部知识检索步骤无缝集成到生成过程中，RAG 解决了独立 LLM 的一些核心局限。嵌入和语义相似度的基础概念，结合关键字和混合搜索等检索技术，允许系统智能地找到相关信息，通过战略性分块使其可管理。这整个检索过程由专门的向量数据库提供支持，这些数据库旨在大规模存储和高效查询数百万个嵌入。虽然检索碎片化或矛盾信息的挑战仍然存在，RAG 使 LLM 能够产生不仅在上下文上适当而且建立在可验证事实基础上的答案，从而在 AI 中培养更大的信任和实用性。

Graph RAG: GraphRAG is an advanced form of Retrieval-Augmented Generation that utilizes a knowledge graph instead of a simple vector database for information retrieval. It answers complex queries by navigating the explicit relationships (edges) between data entities (nodes) within this structured knowledge base. A key advantage is its ability to synthesize answers from information fragmented across multiple documents, a common failing of traditional RAG. By understanding these connections, GraphRAG provides more contextually accurate and nuanced responses.

图 RAG（Graph RAG）：GraphRAG 是检索增强生成的一种高级形式，它利用知识图谱而不是简单的向量数据库进行信息检索。它通过在这个结构化知识库中导航数据实体（节点）之间的明确关系（边）来回答复杂查询。一个关键优势是它能够综合来自多个文档的碎片化信息来生成答案，这是传统 RAG 的常见失败之处。通过理解这些连接，GraphRAG 提供了更多上下文准确和细致的响应。

Use cases include complex financial analysis, connecting companies to market events, and scientific research for discovering relationships between genes and diseases. The primary drawback, however, is the significant complexity, cost, and expertise required to build and maintain a high-quality knowledge graph. This setup is also less flexible and can introduce higher latency compared to simpler vector search systems. The system's effectiveness is entirely dependent on the quality and completeness of the underlying graph structure. Consequently, GraphRAG offers superior contextual reasoning for intricate questions but at a much higher implementation and maintenance cost. In summary, it excels where deep, interconnected insights are more critical than the speed and simplicity of standard RAG.

用例包括复杂的金融分析（将公司与市场事件联系起来）以及用于发现基因和疾病之间关系的科学研究。然而，主要缺点是构建和维护高质量知识图谱所需的显著复杂性、成本和专业知识。与更简单的向量搜索系统相比，这种设置也不太灵活，并且可能引入更高的延迟。系统的有效性完全取决于底层图结构的质量和完整性。因此，GraphRAG 为复杂问题提供了卓越的上下文推理，但实施和维护成本要高得多。总之，在深度、互联的洞察比标准 RAG 的速度和简单性更重要的情况下，它表现出色。

Agentic RAG: An evolution of this pattern, known as Agentic RAG (see Fig.2), introduces a reasoning and decision-making layer to significantly enhance the reliability of information extraction. Instead of just retrieving and augmenting, an "agent"—a specialized AI component—acts as a critical gatekeeper and refiner of knowledge. Rather than passively accepting the initially retrieved data, this agent actively interrogates its quality, relevance, and completeness, as illustrated by the following scenarios.

Agentic RAG：这种模式的演进被称为 Agentic RAG（见图 2），它引入了一个推理和决策层，以显著增强信息提取的可靠性。Agentic RAG 不仅仅是检索和增强，一个"智能体"——一个专门的 AI 组件——充当知识的关键守门人和精炼者。这个智能体不是被动地接受最初检索的数据，而是主动质疑其质量、相关性和完整性，如以下场景所示。

First, an agent excels at reflection and source validation. If a user asks, "What is our company's policy on remote work?" a standard RAG might pull up a 2020 blog post alongside the official 2025 policy document. The agent, however, would analyze the documents' metadata, recognize the 2025 policy as the most current and authoritative source, and discard the outdated blog post before sending the correct context to the LLM for a precise answer.

首先，智能体擅长反思和源验证。如果用户问："我们公司的远程工作政策是什么？"标准 RAG 可能会提取 2020 年的博客文章和官方的 2025 年政策文档。然而，智能体会分析文档的元数据，识别 2025 年政策为最新和最权威的来源，并在将正确的上下文发送到 LLM 以获得精确答案之前丢弃过时的博客文章。

Fig.2: Agentic RAG introduces a reasoning agent that actively evaluates, reconciles, and refines retrieved information to ensure a more accurate and trustworthy final response.

图 2：Agentic RAG 引入了一个推理智能体，它主动评估、协调和精炼检索的信息，以确保更准确和可信的最终响应。

Second, an agent is adept at reconciling knowledge conflicts. Imagine a financial analyst asks, "What was Project Alpha's Q1 budget?" The system retrieves two documents: an initial proposal stating a €50,000 budget and a finalized financial report listing it as €65,000. An Agentic RAG would identify this contradiction, prioritize the financial report as the more reliable source, and provide the LLM with the verified figure, ensuring the final answer is based on the most accurate data.

其次，智能体擅长协调知识冲突。想象一位金融分析师问："Alpha 项目的第一季度预算是多少？"系统检索到两个文档：一个初始提案说明预算为 50,000 欧元，一个最终的财务报告列出为 65,000 欧元。Agentic RAG 会识别这种矛盾，将财务报告优先作为更可靠的来源，并向 LLM 提供经过验证的数字，确保最终答案基于最准确的数据。

Third, an agent can perform multi-step reasoning to synthesize complex answers. If a user asks, "How do our product's features and pricing compare to Competitor X's?" the agent would decompose this into separate sub-queries. It would initiate distinct searches for its own product's features, its pricing, Competitor X's features, and Competitor X's pricing. After gathering these individual pieces of information, the agent would synthesize them into a structured, comparative context before feeding it to the LLM, enabling a comprehensive response that a simple retrieval could not have produced.

第三，智能体可以执行多步推理来综合复杂答案。如果用户问："我们产品的功能和定价与竞争对手 X 相比如何？"智能体会将此分解为单独的子查询。它会为自己产品的功能、定价、竞争对手 X 的功能和竞争对手 X 的定价启动不同的搜索。在收集这些单独的信息片段后，智能体会将它们综合成结构化的比较上下文，然后再将其提供给 LLM，从而实现简单检索无法产生的全面响应。

Fourth, an agent can identify knowledge gaps and use external tools. Suppose a user asks, "What was the market's immediate reaction to our new product launched yesterday?" The agent searches the internal knowledge base, which is updated weekly, and finds no relevant information. Recognizing this gap, it can then activate a tool—such as a live web-search API—to find recent news articles and social media sentiment. The agent then uses this freshly gathered external information to provide an up-to-the-minute answer, overcoming the limitations of its static internal database.

第四，智能体可以识别知识差距并使用外部工具。假设用户问："市场对我们昨天推出的新产品的即时反应如何？"智能体搜索每周更新的内部知识库，没有找到相关信息。识别到这个差距，它可以激活一个工具——例如实时网络搜索 API——来查找最近的新闻文章和社交媒体情绪。然后智能体使用这些新收集的外部信息来提供最新的答案，克服其静态内部数据库的限制。

Challenges of Agentic RAG: While powerful, the agentic layer introduces its own set of challenges. The primary drawback is a significant increase in complexity and cost. Designing, implementing, and maintaining the agent's decision-making logic and tool integrations requires substantial engineering effort and adds to computational expenses. This complexity can also lead to increased latency, as the agent's cycles of reflection, tool use, and multi-step reasoning take more time than a standard, direct retrieval process. Furthermore, the agent itself can become a new source of error; a flawed reasoning process could cause it to get stuck in useless loops, misinterpret a task, or improperly discard relevant information, ultimately degrading the quality of the final response.

Agentic RAG 的挑战：虽然功能强大，但智能体层引入了其自身的一系列挑战。主要缺点是复杂性和成本的显著增加。设计、实施和维护智能体的决策逻辑和工具集成需要大量的工程工作，并增加了计算费用。这种复杂性也可能导致延迟增加，因为智能体的反思、工具使用和多步推理循环比标准的直接检索过程需要更多时间。此外，智能体本身可能成为新的错误来源；有缺陷的推理过程可能导致它陷入无用的循环，误解任务，或不当丢弃相关信息，最终降低最终响应的质量。

In summary: Agentic RAG represents a sophisticated evolution of the standard retrieval pattern, transforming it from a passive data pipeline into an active, problem-solving framework. By embedding a reasoning layer that can evaluate sources, reconcile conflicts, decompose complex questions, and use external tools, agents dramatically improve the reliability and depth of the generated answers. This advancement makes the AI more trustworthy and capable, though it comes with important trade-offs in system complexity, latency, and cost that must be carefully managed.

总结： Agentic RAG 代表了标准检索模式的复杂演进，将其从被动的数据管道转变为主动的、解决问题的框架。通过嵌入一个可以评估来源、协调冲突、分解复杂问题和使用外部工具的推理层，智能体显著提高了生成答案的可靠性和深度。这一进步使 AI 更加可信和有能力，尽管它带来了必须仔细管理的系统复杂性、延迟和成本方面的重要权衡。

Practical Applications & Use Cases

实际应用和用例

Knowledge Retrieval (RAG) is changing how Large Language Models (LLMs) are utilized across various industries, enhancing their ability to provide more accurate and contextually relevant responses.

知识检索（RAG）正在改变 LLM 在各个行业中的使用方式，显著增强了它们提供更准确和上下文相关响应的能力。

Applications include:

主要应用包括：

Enterprise Search and Q&A: Organizations can develop internal chatbots that respond to employee inquiries using internal documentation such as HR policies, technical manuals, and product specifications. The RAG system extracts relevant sections from these documents to inform the LLM's response.
企业搜索和问答：组织可以开发内部聊天机器人，利用内部文档（如 HR 政策、技术手册和产品规格）来响应员工查询。RAG 系统从这些文档中提取相关部分，为 LLM 的响应提供信息支持。
Customer Support and Helpdesks: RAG-based systems can offer precise and consistent responses to customer queries by accessing information from product manuals, frequently asked questions (FAQs), and support tickets. This can reduce the need for direct human intervention for routine issues.
客户支持和帮助台：基于 RAG 的系统可以通过访问产品手册、常见问题解答（FAQ）和支持工单中的信息，为客户查询提供精确和一致的响应。这可以减少对常规问题的直接人工干预需求，提高服务效率。
Personalized Content Recommendation: Instead of basic keyword matching, RAG can identify and retrieve content (articles, products) that is semantically related to a user's preferences or previous interactions, leading to more relevant recommendations.
个性化内容推荐：与基本的关键字匹配不同，RAG 能够识别和检索与用户偏好或先前交互在语义上相关的内容（如文章、产品），从而提供更加精准和个性化的推荐。
News and Current Events Summarization: LLMs can be integrated with real-time news feeds. When prompted about a current event, the RAG system retrieves recent articles, allowing the LLM to produce an up-to-date summary.
新闻和时事摘要：LLM 可以与实时新闻源集成。当被询问关于时事的问题时，RAG 系统会检索最近的文章，使 LLM 能够生成基于最新信息的摘要。

By incorporating external knowledge, RAG extends the capabilities of LLMs beyond simple communication to function as knowledge processing systems.

通过整合外部知识，RAG 将 LLM 的能力从简单的通信工具扩展到作为知识处理系统发挥作用，大大提升了其实用价值。

Hands-On Code Example (ADK)

实践代码示例（ADK）

To illustrate the Knowledge Retrieval (RAG) pattern, let's see three examples.

为了说明知识检索（RAG）模式，我们来看三个示例。

First, is how to use Google Search to do RAG and ground LLMs to search results. Since RAG involves accessing external information, the Google Search tool is a direct example of a built-in retrieval mechanism that can augment an LLM's knowledge.

首先，是如何使用 Google Search 实现 RAG 并让 LLM 基于搜索结果生成响应。由于 RAG 涉及访问外部信息，Google Search 工具就是内置检索机制的一个直接示例，可以增强 LLM 的知识。

python

from google.adk.tools import google_search
from google.adk.agents import Agent

search_agent = Agent(
    name="research_assistant",
    model="gemini-2.0-flash-exp",
    instruction="You help users research topics. When asked, use the Google Search tool",
    tools=[google_search]
)

Second, this section explains how to utilize Vertex AI RAG capabilities within the Google ADK. The code provided demonstrates the initialization of VertexAiRagMemoryService from the ADK. This allows for establishing a connection to a Google Cloud Vertex AI RAG Corpus. The service is configured by specifying the corpus resource name and optional parameters such as SIMILARITY_TOP_K and VECTOR_DISTANCE_THRESHOLD. These parameters influence the retrieval process. SIMILARITY_TOP_K defines the number of top similar results to be retrieved. VECTOR_DISTANCE_THRESHOLD sets a limit on the semantic distance for the retrieved results. This setup enables agents to perform scalable and persistent semantic knowledge retrieval from the designated RAG Corpus. The process effectively integrates Google Cloud's RAG functionalities into an ADK agent, thereby supporting the development of responses grounded in factual data.

其次，本节介绍如何在 Google ADK 中利用 Vertex AI RAG 功能。提供的代码演示了如何从 ADK 初始化 VertexAiRagMemoryService，从而建立与 Google Cloud Vertex AI RAG Corpus 的连接。该服务通过指定 corpus 资源名称和可选参数（如 SIMILARITY_TOP_K 和 VECTOR_DISTANCE_THRESHOLD）进行配置，这些参数会影响检索过程。SIMILARITY_TOP_K 定义要检索的最相似结果数量，VECTOR_DISTANCE_THRESHOLD 设置检索结果的语义距离限制。这种设置使智能体能够从指定的 RAG Corpus 执行可扩展和持久的语义知识检索，有效地将 Google Cloud 的 RAG 功能集成到 ADK 智能体中，从而支持开发基于事实数据的响应。

python

## Import the necessary VertexAiRagMemoryService class from the google.adk.memory module.
from google.adk.memory

---

Config.Yml (_config.yml) Copy Section

Jekyll 配置文件

网站基本信息

网站设置

主题设置

或者使用其他主题：

theme: just-the-docs

remote_theme: pmarsceill/just-the-docs

Markdown 设置

插件

相对链接配置

包含和排除文件

默认值

导航设置（用于某些主题）

代码高亮主题

启用相对路径

AGENTS (AGENTS.md) Copy Section

Agentic Design Patterns - 智能体操作指南

1. 项目概述 Copy Chapter

2. 构建/检查/运行命令 Copy Chapter

环境要求 Copy Section

依赖安装 Copy Section

构建与本地运行 Copy Section

代码检查与质量校验 Copy Section

测试要求 Copy Section

3. 代码与内容风格规范 Copy Chapter

Markdown格式规范 Copy Section

翻译标准 Copy Section

准确性优先

术语一致性

语言风格

命名规范 Copy Section

错误处理 Copy Section

代码与技术内容规则 Copy Section

4. 工作流规范 Copy Chapter

修改前检查 Copy Section

提交要求 Copy Section

禁止操作 Copy Section

5. 双语版本指南 Copy Chapter

5.1 双语版本概述 Copy Section

5.2 双语文件结构 Copy Section

5.3 双语内容格式规范 Copy Section

基础格式规则

段落交替规范

代码块处理规范

特殊元素处理

5.4 网页版双语支持 Copy Section

5.5 PDF/EPUB 生成 Copy Section

5.6 更新双语版本的流程 Copy Section

完整更新流程

双语文件同步检查清单

5.7 双语文件生成工具（如适用） Copy Section

7. 双语版本维护规范 Copy Chapter

7.1 双语文件质量标准 Copy Section

7.2 禁止操作 Copy Section

8. 核心资源 Copy Chapter

OPTIMIZE README (OPTIMIZE_README.md) Copy Section

翻译优化脚本使用说明

脚本对比 Copy Chapter

推荐使用: Python 版本 Copy Chapter

快速开始 Copy Section

功能特点 Copy Section

配置修改 Copy Section

跳过的文件 Copy Section

Bash 版本 (备选) Copy Chapter

依赖安装 Copy Section

运行 Copy Section

使用流程 Copy Chapter

注意事项 Copy Chapter

单独处理某个章节 Copy Chapter

Progress (progress.md) Copy Section

翻译进度追踪

总体进度 Copy Chapter

主要内容 Copy Chapter

章节详情 Copy Chapter

附录详情 Copy Chapter

状态说明 Copy Chapter

更新方式 Copy Chapter

文件位置 Copy Chapter

审校重点 Copy Chapter

Config.Yml (_config.yml)

AGENTS (AGENTS.md)

1. 项目概述

2. 构建/检查/运行命令

环境要求

依赖安装

构建与本地运行

代码检查与质量校验

测试要求

3. 代码与内容风格规范

Markdown格式规范

翻译标准

命名规范

错误处理

代码与技术内容规则

4. 工作流规范

修改前检查

提交要求

禁止操作

5. 双语版本指南

5.1 双语版本概述

5.2 双语文件结构

5.3 双语内容格式规范

5.4 网页版双语支持

5.5 PDF/EPUB 生成

5.6 更新双语版本的流程

5.7 双语文件生成工具（如适用）

7. 双语版本维护规范

7.1 双语文件质量标准

7.2 禁止操作

8. 核心资源

OPTIMIZE README (OPTIMIZE_README.md)

脚本对比

推荐使用: Python 版本

快速开始

功能特点

配置修改

跳过的文件

Bash 版本 (备选)

依赖安装

运行

使用流程

注意事项

单独处理某个章节

Progress (progress.md)

总体进度

主要内容

章节详情

附录详情

状态说明

更新方式

文件位置

审校重点

SUMMARY (SUMMARY.md)

Translation Guide (translation-guide.md)

翻译原则

1. 准确性第一

2. 中文表达习惯

3. 专业术语统一

格式规范

Markdown 格式

代码处理

图片引用

常用术语对照表

翻译流程

第一遍：粗译

第二遍：精修

第三遍：校对

质量检查清单

注意事项

Bilingual/Agentic Design Patterns (bilingual/Agentic Design Patterns.md)

layout: bilingual lang: bilingual

第一部分：核心模式（103 页）

第二部分：认知机制（61 页）

第三部分：容错与扩展（34 页）

第四部分：高级架构（114 页）

附录（74 页）

Bilingual/Appendix B AI Agentic Interactions From GUI To Real World Environment (bilingual/Appendix B - AI Agentic Interactions_ From GUI to Real world environment.md)

Interaction: Agents with Computers

交互：智能体与计算机