从零理解如何构建 AI Agent

Appearance

这页解决什么问题 ​

实践篇的目标是帮助你把 AI Agent 的核心模式真正跑通，但在开始之前有一件事必须先说清楚：

  • 当前仓库首先是一个 VitePress 文档站点
  • 实践篇页面中的 bun run pxx-*.ts 更接近推荐的示例入口命名
  • 当前仓库已经提供 P1-P23 的根目录示例文件；实践篇当前章节都可以直接按推荐命令运行

如果你只是阅读原理，这一页可以快速浏览。

如果你打算边读边敲代码，这一页建议完整看完。

你会用到什么 ​

开始实践篇之前，建议至少准备好下面这些基础条件：

项建议值用途
Node.js20+兼容现代 ESM、VitePress、常见 Agent SDK
Bun1.1+文中运行命令默认使用 bun run / bun add
包管理器bun安装文档站点依赖，后续也可用于示例工程
OpenAI API Key必需涉及 openai 的章节都要用到
API Base URL可选当你使用代理、兼容网关或本地模型时需要配置
模型名建议预先确认避免本地运行时直接填错
一个终端必需绝大多数示例都以命令行方式运行

本地运行模式 ​

跟着每一章把代码真正敲出来、修改、调试和扩展，本地运行是实践篇的标准路径。

建议先准备示例运行环境，再进入各章节的 bun run pxx-*.ts 主线。

最小依赖通常包括：

bash
bun add openai

部分章节还会额外需要其他依赖。例如：

  • P14：MCP 协议接入 需要 @modelcontextprotocol/sdk
  • 涉及 HTTP 服务、Schema 校验、向量检索或文件处理的章节，可能还需要额外包

建议做法是：先读每章“前置准备”或“依赖安装”部分，再安装该章特有依赖，不要一开始把所有可能用到的库一次性全装上。

按当前仓库内已提供的 P1-P23 示例脚本，第三方依赖可以先这样分组：

分组覆盖章节说明
基础组P1-P23全部章节默认都要 openai
MCP 扩展组P14额外需要 @modelcontextprotocol/sdk

也就是说，如果你不打算先做 P14，当前只装 openai 就足够开始大部分实践章节。

如果你当前只是想本地阅读文档站点，不急着跑示例代码：

bash
bun install
bun dev

然后访问本地 VitePress 页面即可。

这个模式下，你不需要立刻安装 openai，也不需要配置 OPENAI_API_KEY。

运行参数配置 ​

只要代码里出现下面这种写法：

ts
import OpenAI from 'openai'

const client = new OpenAI()

就意味着运行时至少要拿到 API Key，而多数实践示例还支持额外传入 baseURL 与 model。

推荐你先统一理解这 3 个参数：

参数作用常见示例
OPENAI_API_KEY鉴权sk-...、代理平台密钥、本地模型占位值
OPENAI_BASE_URLAPI 入口地址https://api.openai.com/v1、代理网关、http://localhost:11434/v1
OPENAI_MODEL当前运行模型gpt-4o、gpt-4o-mini、llama3

本地运行时的推荐配置 ​

推荐在本地 shell 中先配置最小必需项：

bash
export OPENAI_API_KEY="你的真实 Key"

如果你不是直接使用官方 OpenAI，再补充：

bash
export OPENAI_BASE_URL="你的接口地址"
export OPENAI_MODEL="你的模型名"

如果你使用 zsh，可以把这行写入 ~/.zshrc 后重新加载：

bash
source ~/.zshrc

建议你先验证环境变量是否生效：

bash
echo $OPENAI_API_KEY

如果你还配置了其他参数，也建议一起确认：

bash
echo $OPENAI_BASE_URL
echo $OPENAI_MODEL

你应该能看到非空输出。不要把真实 Key 提交到仓库，也不要直接硬编码进示例源码。

当前仓库状态说明 ​

为了避免预期错位，这里明确说明当前实践篇的运行边界：

  1. 实践文章里的代码片段已经覆盖主要实现逻辑，且当前 P1-P23 都已经落成仓库内可运行示例文件。
  2. 当前仓库已经提供 P1-P23 对应的根目录示例文件，其中 P14 包含 p14-mcp.ts 和 p14-mcp-server.ts 两个脚本。
  3. 如果你本地执行 bun run pxx-*.ts 时提示找不到文件，通常意味着分支版本较旧或当前工作区没有同步到最新内容，而不是文档仍要求你手动创建。
  4. RunCommand 组件会显示“是否已在仓库提供”的提示，但不会主动校验你的本地环境和 API Key 是否已经满足运行条件。

换句话说：当前实践篇已经覆盖 P1-P23 的现成可执行 demo。

推荐目录组织 ​

当前仓库为了让文档中的 bun run pxx-*.ts 命令可直接对齐，示例文件统一放在 practice/ 目录。

如果你准备在自己的项目里持续扩展这些示例，建议统一放在一个明确的目录里，不要和 VitePress 主题文件混在一起。

例如：

text
.
├── docs/
├── .vitepress/
├── examples/
│   ├── p01-minimal-agent.ts
│   ├── p02-multi-turn.ts
│   ├── p03-streaming.ts
│   └── ...
└── package.json

这样做有三个好处：

  • 文档代码和可执行示例分层清晰
  • 后续补测试、补 README、补样例输入更容易
  • 不会误把站点构建依赖和示例运行依赖混在一起

推荐运行流程 ​

建议你按下面顺序开始，而不是直接跳进后面的高级章节：

  1. 先读 P1，跑通最小示例，确认 API Key / baseURL / model 组合可用。
  2. 再进入 P2 到 P4，确认多轮、流式和错误处理都正常。
  3. 等 P1-P4 都稳定后，再进入 RAG、多 Agent、生产化章节。

这条路线的目的不是“保守”，而是避免你在 P14、P22 这类高复杂度章节里同时排查协议、环境、依赖和业务逻辑四类问题。

每章开始前的检查清单 ​

建议在每一章动手前，先过一遍下面这份清单：

检查项为什么要查
这章对应的示例文件是否已经在当前分支存在防止命令名与本地文件状态不一致
这章是否新增依赖防止 Cannot find package
这章是否需要额外资源例如图片、文档样本、diff 样本、测试输入
这章是否依赖前一章产物防止跳章导致上下文断裂
这章的预期输出是什么便于判断“没报错”是否真的等于“成功”

常见报错与排查 ​

1. Cannot find package 'openai' ​

说明依赖还没安装。

bash
bun add openai

2. OPENAI_API_KEY 未配置 ​

说明环境变量没有生效。先重新执行：

bash
export OPENAI_API_KEY="你的真实 Key"

然后用 echo $OPENAI_API_KEY 检查是否为空。

3. baseURL 或 model 配错了 ​

常见现象包括：

  • 可以连上接口，但提示模型不存在
  • Key 看起来有效，但始终返回 404 / 400
  • 同一份代码在别的平台能跑，在当前平台跑不通

优先检查：

  • baseURL 是否已经带上正确的 /v1
  • model 填的是模型名，而不是平台名或部署名别称
  • 代理平台是否要求使用它自己的模型标识

4. bun run pxx-*.ts 找不到文件 ​

说明当前工作区缺少对应示例文件，优先检查当前分支是否同步到最新版本，或确认命令中的文件名是否与章节一致。

5. 章节代码能读懂，但拼起来跑不起来 ​

这通常不是模型问题，而是你遗漏了某一步：

  • 少了 import
  • 漏了类型定义
  • 漏了某一段辅助函数
  • 漏了环境变量或样本输入

建议做法：不要一次性复制整篇，按文章里的步骤一段一段组装，并在每一步完成后先跑通再继续。

推荐下一步 ​

准备完成后，建议按这个顺序进入实践篇：

如果你只是想快速复制某一章的运行命令，也可以直接查看 实践篇首页的运行索引。

如果你已经具备 Agent 开发经验，也可以直接从你关心的主题切入，但仍然建议先确认这页里的环境准备项已经满足。