如何构建 2026 年的 AI Agents（完整课程）

以下是 AI 构建者没人告诉你的真相。

他们中的大多数都在构建演示产品

你真正需要构建的是

一个生产级别的 AI Agent

太长不看版：如果你不想读全文，把这个链接给你的 Agent，让它来回答你的问题：➡️https://github.com/codejunkie99/agentic-harness

这是一切的起点——那条推文

问题是，大多数 AI 工程师在决定认真对待 Agent 时，并不清楚到底要构建什么。

有些人选择了 LangChain，因为 YouTube 上的多 Agent 演示看起来很酷，结果接下来两周都在跟 Python 互操作和异步运行时不匹配作斗争，最后整个项目废弃。

有些人试图从零构建一个自定义编排层：一个循环、一个会话存储、一个上下文组装器，结果基础设施吃掉了所有时间，真正的 Agent 根本没完成。

还有些人复制了 hello-world 的 webhook 示例，得到一个 JSON 响应，就以为自己理解了整个系统，然后发布的东西在第一次会话运行超过十分钟、远程沙箱中途宕机、或者上下文窗口没有配置压缩就填满时立刻崩溃。

结果通常都一样：大量的管道代码，没有生产级 Agent，也没有对生产级 Agent 运行时到底是什么样的心智模型。

如果你的目标是在 2026 年构建并交付真正的 Agent，你不需要学习六个框架。

你只需要深入理解一个运行时，足以从处理器到部署完全掌控一个生产级 Agent。

这意味着你需要学会：

• 连接三层架构，让你的处理器逻辑在更换提供商和目标时无需修改 Agent 代码
• 正确使用会话和任务，让长时间运行的任务不会污染自己的上下文
• 编写角色和技能，在不重新编译的情况下塑造模型行为
• 配置压缩，让运行两小时的会话不会在第一小时就开始产生幻觉
• 将 HttpSessionEnv 指向远程沙箱，让二进制文件在本地运行，而执行在 Linux 上完成
• 选择正确的构建目标：native、node 或 Cloudflare，无需在它们之间重写任何 Agent 逻辑
• 生成连接器而不是手写适配器，并理解这种区别在实际负载下的重要性

本指南是一个完整的技术实战教程，基于实际的 agentic-harness 代码库、六周使用它构建和破坏真实 Agent 的经验，以及那些最耗费时间调试的失败模式。

全文超过 4000 字，直接引用仓库和文档——不是二手摘要或演示级别的例子。

但它的真正价值在于：每个章节都包含可运行的代码片段、清晰的决策原因说明，以及如果你跳过它就会遇到的确切失败模式。

这样，当你读完时，就能端到端地掌控一个生产级 Agent——从第一个处理器到沙箱，再到无人值守运行的 CI 任务。

建立这种理解花了超过 6 周的时间每天与代码库打交道，其中大部分时间都在调试那些看起来正确但在真实条件下崩溃的东西。

现在开始吧。⬇️

项目的结构

两个 crate。一个二进制文件。每个执行目标都是一个配置选择，而不是重写。

• SDK 是一个你可以引入任何 Rust 项目的库。CLI 包装了它。你的 Agent 是一个以 use agentic_harness::prelude::*; 开头的 Rust 二进制文件。
• cargo build 就是整个流水线。没有打包器，没有转译步骤，目标机器上不需要语言运行时。一个自包含的可执行文件加上一个 manifest.json。

驱动所有设计决策的约束是：同一个 Agent 二进制文件应该能在你的笔记本上以交互模式运行，在 GitHub Actions 任务中克隆一个新仓库，通过 HTTP 连接到远程 E2B 沙箱，以及在 Cloudflare Worker 边界上运行——而不需要修改一行 Agent 逻辑。

这个代码库中的每一个决策都是为了满足这个约束而存在的。

三层架构以及每一层存在的原因

心智模型是三个同心环。知道每个边界在哪里，将比本指南中的任何其他内容节省你更多的调试时间。

你的 Rust 代码是外环。

• 你编写处理器。处理器接收 AgentContext。它们调用会话。会话调用模型、读取文件、写入文件、运行 shell 命令、生成任务、连接到 MCP 服务器。
• 你从不直接接触 HTTP 客户端。你从不直接解析模型响应。SDK 处理这两者。

Harness 是中环。

• 它管理 Agent 注册表、通过 URL 路径路由身份、跨调用持久化会话、在会话增长时压缩上下文、发现角色和技能、模型选择优先级，以及提供者无关的 ModelClient trait。
• 这让你可以在不接触处理器代码的情况下，将 Anthropic 换成 OpenAI 或本地 Ollama 实例。
• Harness 让你的 Agent 逻辑在多个提供者和目标之间可复用。
• 它也是所有在生产中会出问题的地方——会话状态、上下文溢出、提供者故障、并发请求排序——的处理中心。

执行目标是内环。

• 本地文件系统、CI checkout、指向 Daytona 或 E2B 的 HttpSessionEnv、Cloudflare Worker 边界。
• Harness 不关心你用的是哪一个。你的处理器也不关心。它们调用 session.shell() 和 session.write()，Harness 将这些翻译成底层目标所需的内容。
• 这种分离就是全部意义所在。当 E2B 发布新 API 版本时，你更新连接器，而不是你的 Agent 逻辑。
• 当 Anthropic 发布 claude-opus-4-7 时，你更新 runtime.json，而不是你的处理器。外环保持干净，因为中环吸收了所有变动。

运行时配置：控制模型层的文件

在编写第一个处理器之前，你需要在工作区中放置 runtime.json。

将其放在 .agentic-harness/config.json 或工作区根目录下的 agentic-harness.json。load_workspace_context() 会自动拾取它。

运行时的模型选择遵循以下优先级：

1. PromptOptions::model(...)：每次调用的覆盖
2. 所选角色的 model 元数据：每个角色的默认值
3. runtime config 中的 defaultModel：工作区默认值

需要理解的是：模型 ID 必须先注册才能使用。openaiCompatibleModels 是 Harness 用来连接内置聊天补全客户端的列表。如果你的模型不在该列表中，你会在启动时得到一个清晰的错误，而不是在会话中途出现令人困惑的失败。

对于 OpenAI 兼容的网关，配置看起来是一样的。将 baseUrl 指向你的网关：

• 永远不要将字面 API 密钥写入 runtime.json。使用 apiKeyEnv，将实际密钥保留在你的环境中。
• Harness 在请求时读取环境变量，而不是在启动时——这意味着你可以在不重启服务器的情况下轮换密钥。

Agent 身份是一个 URL 路径，而不是注册表查找

这是第一个让我惊讶的设计决策。现在我认为它是正确的。

没有 Agent ID 系统。没有注册表键。没有你自己生成的 UUID。你的 Agent 的身份是 POST /agents/<name>/<id>。

• Harness 处理该 URL 后面的所有会话状态簿记。
• 这样做的原因：每个系统中的每个调用者都已经知道如何从上下文中构建一个有意义的 ID。一个 PR 编号。一个运行 ID。一个结合了任务名称的时间戳。一个用户句柄。
• 你不需要一个会话创建端点。你不需要单独存储会话 ID。URL 就是会话。

Rust 端的 Agent 处理器调用 ctx.id() 来获取调用者提供的任何 ID：

会话：有状态的执行上下文

会话不仅仅是一个对话线程。它是 Agent 调用的完整执行上下文。

它包含：

• 与模型的消息历史
• 工作区文件访问（读取、写入、编辑、grep、glob、stat、readdir）
• 带有 cwd 和 env 控制的 shell 执行
• 工具注册（MCP 服务器、自定义工具）
• 分配的角色及其系统提示覆盖
• 压缩预算和历史水位线

你通过调用 ctx.session_with_id() 并传入任何有意义的 ID 来获取会话：

• 当你使用相同的 ID 时，会话会在 HTTP 调用之间持久化。用相同的会话 ID 调用同一个 Agent 端点三次，模型会将所有三次交换视为一个连续的对话。
• 历史记录会自动累积。你不需要管理它。
• 这就是无需自己管理状态即可实现多步骤工作流的原因。你只需不断调用 session.prompt()，Harness 会处理其余一切。

当你需要将大量上下文与提示一起传递时，读取文件并内联格式化：

会话会管理 token 计数，这样你就不会在对话中途意外溢出上下文窗口。当接近预算时，压缩会触发。稍后会有更多相关内容。

任务：保持父会话干净的聚焦子会话

• 这是我希望能从第一天就理解的原始概念。它是让 Agent 在长时间任务中保持连贯与中途开始产生幻觉之间的区别。
• 任务是一次性的子会话。全新的历史记录。共享的工作区。向父会话返回一个结果。父会话永远不会看到任务的任何中间推理。

• 研究任务在隔离中运行。它的整个推理链。
• 模型对代码做出的每一个中间观察，每一个“等等，让我也检查一下这个文件”，都留在任务内部。
• 父会话只得到一个干净的摘要。这就是它看到的一切。为什么这在实践中很重要：当你直接在长时间运行的会话中运行探索性分析时，历史记录会充满中间工具调用、部分答案以及模型关于不再相关的事情的推理。
• 模型会在不应该的时候锚定在这些噪声上。压缩最终会触发，并丢失你实际需要的上下文。任务就是外科手术式的修复。

规则：如果子问题有一个明确的交付物，并且不需要父会话的对话历史来完成，就把它做成一个任务。“做成任务”的门槛比你想象的要低。

对于跨代码库的并行分析：制图模式，将任务分派出去并收集结果：

每个任务都是干净的。每个任务都专注于一个目录。父会话收集结果并写入最终文档。

如果你有 12 个模块，你就运行 12 个聚焦的任务，每个任务从零开始，没有其他任务的包袱。

角色和技能：无需重新编译即可塑造行为

1. 角色位于 .agentic-harness/roles/。技能位于 .agents/skills/。两者在 Harness 启动时自动发现。
2. 角色是作用域到一次调用的系统提示覆盖。在调用时应用，之后丢弃。它们不会持久化到消息历史中。它们不会在调用之间累积。

优先级链：调用角色 > 会话角色 > Agent 角色 > 无角色。

• 模型 frontmatter 是可选的但很有用。它让你将特定角色路由到特定模型。
• 你的解释器角色在 claude-sonnet-4-6 上运行，以获得速度和成本效益。你的安全审计员在 claude-opus-4-7 上运行，以获得深度。你只需在角色文件中配置一次，之后就再也不用操心了。
• 技能是模型在会话开始时读取的行为描述文件。
• 它们是 .agents/skills/ 中的 Markdown 文件。Harness 会自动找到它们。你不需要在任何地方注册它们。

实际用途：一个与代码库并存的技能库描述了你的工作方式。提交消息格式、首选库、迁移命名约定、API 设计模式、测试要求。

模型在每次会话前读取这些内容。你编辑 Markdown。行为在下次运行时更新。无需重新编译。

模型读取这个。它编写的提交符合你的约定。你不需要每次会话都提醒它。你维护一个文件。

编码 Agent 循环的完整细节

编码 Agent 循环是 CLI 围绕构建的主要用例。如果你配置不当，它也是最多问题可能发生的地方。

包含所有重要选项的完整命令：

每个标志的作用及其重要性：

1. --workspace . 设置根目录。所有文件操作都被沙箱化在此路径下。Agent 无法读取或写入此路径之外的内容——这在 Harness 级别强制执行，而不是依赖模型自我限制。
2. --llm auto 从运行时配置中的 defaultModel 选择模型。对于需要深度推理的复杂任务使用 --llm anthropic/claude-opus-4-7，对于更快的迭代使用 --llm anthropic/claude-sonnet-4-6。
3. --deny-path 是一个硬性阻止。它匹配前缀风格，所以 --deny-path config/ 覆盖了 config/ 下的所有内容。在第一次运行前审计你的工作区，枚举所有包含密钥或生产配置的路径——不仅仅是 .env。
4. --approve-dependencies 允许修改 Cargo.toml 而无需人工审批步骤。如果你想在添加每个新 crate 之前都审查，就省略这个标志。
5. --commit 自动暂存所有更改，并在成功运行结束时使用你提供的消息提交。没有这个标志，更改会作为未暂存的修改供你审查。
6. --pr 从提交创建一个拉取请求。要求在运行前有一个干净的 git 状态和一个真正的分支，而不是 detached HEAD。

循环本身：检查 → 简报 → LLM + 工具 → 编辑 + 测试 → 提交 · PR。

• 检查：读取工作区结构，加载技能和角色，识别最可能与提示相关的文件。
• 在接触任何代码之前，将其理解写入 coding-brief.md。
• 简报：模型承诺一个计划。你可以在运行中途读取 .agentic-harness/runs/<id>/coding-brief.md 来查看它决定了什么。
• 如果简报看起来不对，终止运行。用更清晰的提示重新启动比让 Agent 执行一个糟糕的计划更便宜。
• LLM + 工具：编辑-测试循环。模型进行更改，运行测试套件，读取输出，进行更多更改。迭代直到测试通过、达到迭代限制或模型认为任务完成。

提交 · PR：暂存、提交、推送、打开带有差异附件的 PR。

每次运行都会向 .agentic-harness/runs/<id>/ 写入六个工件：

1. coding-brief.md：Agent 在编写任何代码之前承诺的计划
2. summary.md：人类可读的关于做了什么、尝试了什么以及为什么的记录
3. run.json：结构化元数据：使用的模型、总持续时间、输入/输出 token 计数、迭代次数、最终退出状态
4. events.jsonl：按顺序排列的每个工具调用及其完整输入和输出，用于调试问题
5. diff.patch：所有文件更改的完整差异
6. checks.json：决定成功或失败的最终测试和 lint 结果

要记住的技巧

• 将这些视为结构化日志，而不是临时输出。对于任何需要能够重现的任务，我将运行工件提交到仓库。
• 仅 run.json（约 2KB）就告诉你模型、token 成本以及是否成功。当你需要调试一个糟糕的运行结果时，events.jsonl 会告诉你 Agent 做了什么以及按什么顺序做的。

对于 CI，模式是：

HttpSessionEnv：本地运行二进制文件，远程执行

• 这是我花了最长时间才完全理解的能力。现在我几乎在每个涉及基础设施的任务中都使用它。
• Agent 二进制文件在你的机器上或 CI 中运行。文件系统和 shell 操作在远程沙箱中执行。
• Agent 不知道也不关心它处于哪个环境中。

使用 agentic_harness::HttpSessionEnv；

有线协议是 JSON over HTTP。每个操作：

1. exec
2. read
3. write
4. edit
5. grep
6. glob
7. stat
8. readdir
9. mkdir
10. rm 都有定义的请求/响应形状。

任何实现此协议的沙箱都可以作为 HttpSessionEnv 目标。

要连接一个命名的沙箱：

内置的连接器处理 Vercel Sandbox、Daytona 和 E2B 的身份验证和生命周期样板代码：

• 我最常使用这个的具体用例：在干净的 Linux 环境中重现 CI 失败。
• Agent 在确切的失败提交哈希处克隆仓库，运行确切的失败测试命令，读取完整输出，诊断失败原因，并写入报告。
• 我阅读报告。我从未接触过我的本地机器。会话结束时沙箱被丢弃。

没有人警告过你的性能问题：每次通过 HttpSessionEnv 的 shell 调用都是一次网络往返。紧密循环：编辑、测试、检查输出、编辑——延迟会迅速累积。

一个 40 次迭代的循环在本地需要 5 秒，如果每次迭代进行三次单独的 shell 调用，在远程沙箱上需要几分钟。

解决方法：将 shell 工作批处理成脚本。

每次迭代一次调用而不是三次。编写一次脚本，重复运行。在 40 次迭代的循环上，延迟差异是真实的。

构建目标：相同的代码库，三种部署形态

native 是默认的。一个二进制文件。一个 manifest。目标机器上不需要其他任何东西。可以在任何能执行原生 Linux 二进制文件的地方运行。

node 适用于需要 Node 入口点的托管平台。构建会生成 server.mjs，它将原生 Rust 二进制文件作为子进程启动，并将 HTTP 代理给它。Agent 逻辑仍然作为 Rust 运行。Node 层是一个 30 行的 HTTP 垫片。

Cloudflare 适用于边缘部署。

• 构建会生成一个 Worker 边界文件，并链接一个 Worker 兼容的应用适配器。
• 处理器通过 WASM JSON ABI 编译为 WASM。
• Durable Object 绑定通过 Cloudflare KV 处理会话持久化。

关于 Cloudflare 的重要约束：Workers 不支持长时间运行的 shell 命令。它们没有真正的文件系统。

它们不支持 cargo 或任何构建工具。--target cloudflare 适用于 webhook 处理、路由元数据、小型控制端点和 Durable Object 路由——而不是编码工作。

对于任何需要运行 cargo test 的事情，委托给原生进程或远程沙箱。

实用的决策矩阵：

• 将 Agent 作为其他服务调用的 API 发布 → native 放在 nginx 或托管平台后面
• 托管在 Railway、Render 或需要 Node 的平台上 → node
• webhook 接收、轻量级路由、Durable Object 状态管理 → cloudflare
• 其他所有情况 → native

模式引导输出：来自模型响应的类型化 Rust 结构体

要求模型返回 JSON 并希望它做到只是解决方案的一半。

让 Harness 提取、验证并将其反序列化为你的 Rust 结构体才是完整的解决方案。

模型可以在同一次响应中返回推理散文以及类型化的负载。Harness 提取 ---RESULT_START--- 和 ---RESULT_END--- 标记之间的结果块。你得到一个 Rust 结构体。从模型输出到你的处理器逻辑实现编译时类型安全。

• 模式做了两件事：它告诉模型要产生什么形状，并为 Harness 在反序列化之前提供验证依据。
• 如果模型返回的内容与模式不匹配，你会得到 PromptError::SchemaValidationFailed，而不是在三个调用点之后访问缺失字段时发生 panic。

MCP 工具：访问沙箱之外

当 Agent 需要超出文件和 shell 的能力时，connect_mcp 是逃生舱口。

Agent 获得 MCP 服务器的完整工具集。无需编写工具定义。描述来自服务器。模型根据这些描述决定何时调用哪个工具。

你可以将多个 MCP 服务器连接到同一个会话：

• 模型根据描述调用工具。一个模糊的描述如“搜索 sentry”会被不一致地调用。
• 一个描述如“在回答任何关于错误、事件或生产问题的问题之前调用此工具”会被可靠地调用。
• 如果你控制 MCP 服务器，编写规定性的描述：告诉模型何时调用，而不仅仅是它返回什么。

连接器：生成适配器而不是手写

与其手写适配器代码来适应不熟悉的 API，不如将连接器配方传递给你的编码 Agent：

• 连接器配方是沙箱 API 及其需要满足的 SessionEnv 契约的结构化描述。
• 编码 Agent 读取它，编写 Rust 适配器模块，处理身份验证，包装提供者生命周期，并将其暴露为 HttpSessionEnv。
• 你审查差异。你合并它。适配器存在于你的项目中。现在它是你的代码了。

我使用这个方法在大约 20 分钟内连接了 Daytona，包括完整的审查周期。Agent 在第一次尝试时就正确获得了 auth 头格式。

如果根据 Daytona 文档从头编写适配器，可能需要大半个下午，并且至少对刷新令牌流程做出两个错误假设。

一旦连接器生成：

自动压缩：处理长时间会话而不丢失上下文

长时间运行的会话会累积历史记录。

最终它们会溢出模型的上下文窗口。

Harness 会自动处理这个问题，但你需要正确配置它，否则你会在最糟糕的时刻丢失上下文。

context_window_tokens 是会话的总预算。

• reserve_tokens 是你为模型响应保留的部分。历史记录的有效限制是 context_window_tokens - reserve_tokens。
• keep_recent_messages 是尾部始终按原样保留的消息数量，无论压缩如何。

当历史记录超出预算时，Harness 要求模型总结系统提示和保留尾部之间的所有内容。

该摘要替换中间部分。尾部消息保持不变。压缩后的会话更小，下一次调用适合预算。

权衡是真实的：摘要会丢失精度。50 条消息前做出的一个具体决定——“我们选择了 authlib，因为它是唯一支持 PKCE 且能与 axum 的中间件模型配合使用的库”——可能在摘要中变成“我们选择了 authlib 用于认证”。

如果该精度对于会话后期的决策至关重要，请显式存储它：

• 将决策写入文件。文件在压缩中幸存。模型可以按需读取它们。如果工作区承担了责任，历史记录就不需要携带所有内容。
• 运行 agentic-harness doctor 查看模型实际报告的上下文窗口。将 context_window_tokens 设置为该值的 80-90%。
• token 计数器在模型端并不完全准确，如果你处于 99% 的水平，单个大文件读取可能会将你推过限制。

需要注意的事项

1. 会话历史污染

• 问题：长时间会话中的探索性分析用探索阶段的噪声污染了后续提示
• 修复：使用任务。任务历史永远不会触及父会话。“做成任务”的门槛比你想象的要低

1. 角色优先级意外

• 问题：调用级别的角色遮蔽了会话角色。模型行为与预期不同，你不知道为什么
• 修复：会话角色设置身份。调用角色缩小焦点。它们分层——调用角色是添加，不应该取消

1. --deny-path 漏洞

• 问题：你拒绝了 .env。但你的密钥也存在于 .env.local 和 config/staging.yaml 中。Agent 读取了其中一个
• 修复：拒绝前缀，而不是文件名。--deny-path config/ 覆盖了它下面的所有内容

1. CI 中的 detached HEAD

• 问题：Agent 编辑，测试通过，提交失败——因为没有分支可以提交
• 修复：在调用 Harness 之前执行 git checkout -b agent-run-$RUN_ID

1. 紧密循环中的 HttpSessionEnv 延迟

• 问题：40 次迭代，每次三次 shell 调用，就是几分钟的纯网络延迟
• 修复：编写 agent-check.sh，在一次调用中完成所有操作。每次迭代一次调用

1. 上下文预算低估

• 问题：压缩在任务中途触发。模型丢失了计划，开始根据摘要即兴发挥
• 修复：运行 agentic-harness doctor 获取实际窗口。将预算设置为该值的 80-90%

1. 处理器注册后加载运行时配置

• 问题：处理程序在 load_workspace_context() 之前运行，没有注册模型。错误看起来完全不像是配置问题。
• 修复：在 app() 中始终先调用 load_workspace_context()，然后再连接任何 Agent。

1. --llm 在不同运行之间自动变化

• 问题：defaultModel 被更新。相隔六个月的两次运行无法比较，第一次的结果无法复现。
• 修复：在 runtime.json 中固定模型，用于任何需要可复现性的任务。

1. 删除运行产物

• 问题：你在 .gitignore 规则中清理了 runs/ 目录。三周后你需要复现一个回归问题，但所有内容都已丢失。
• 修复：对于任何需要复现的任务，提交运行产物。run.json 只有 2 KB，保留它。

我会做得不一样的地方

1. 在接触任何东西之前，先运行 agentic-harness 指南。
2. 在编写处理程序逻辑之前，先编写会话级别的测试。
3. 对于所有有子交付物的任务，使用 tasks。
4. 从第一次正式运行开始就固定模型。
5. 将决策存储在文件中，而不是会话历史中。
6. 从一开始就批量执行 shell 操作（当使用远程沙箱时）。

核心结论

大多数 Agent 框架只是 API 调用的封装。而这是一个运行时。

封装解决的是“让模型响应”的问题。运行时解决的是“将 Agent 部署到生产环境，并在模型变化、沙箱变化、代码库变化、会话运行两小时后上下文窗口溢出时，依然保持其正常工作”的问题。

三层架构：

1. 你的代码
2. harness
3. 执行目标

正是这种架构让这一切成为可能。你编写处理程序，harness 吸收所有运维复杂性，执行目标则是一个配置选项。

不变的东西：处理程序逻辑、会话结构、任务模式、角色定义、技能文件。变化的东西：模型、提供商、沙箱供应商、部署目标。

架构的设计原则是：变化的东西永远不会触及不变的东西。

这就是赌注。而且这是正确的赌注。

希望你喜欢阅读这篇文章，并了解我是如何为 Agent 以及一般情况构建的 ❣️

免责声明

本文由作者研究和撰写，由 Minimax-M2.7 编辑。缩略图来自 Pinterest。

Harrison Chase：“记忆应该是开放的！”——

[https://x.com/hwchase17/status/2046308913939919232Harrison](https://x.com/hwchase17/status/2046308913939919232Harrison)

Chase：“你的 Harness，你的记忆”——

[https://www.langchain.com/blog/your-harness-your-memory](https://www.langchain.com/blog/your-harness-your-memory)

Vivek Trivedi：“Agent Harness 的解剖”——

[https://www.langchain.com/blog/the-anatomy-of-an-agent-harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness)