我们如何构建 LangChain 的付费媒体智能体

• 1像对待知识工作者一样对待智能体。最好的结果来自为智能体提供一个精心设计的工作区：沙箱、软件、业务上下文和清晰的操作说明。系统提示词变成了一张地图，帮助智能体找到所需内容，而不必把所有东西都装进上下文。
• 2用模型做判断，用代码保一致。计算、事实来源规则和防护措施更适合用代码处理。这让智能体更快、更便宜、更可靠，而模型则专注于解读结果并推荐下一步该做什么。
• 3围绕完整工作流设计智能体。智能体需要找到合适的工具，在明确的权限范围内工作，并从分析走向行动。这意味着提出广告系列变更、将变更交由人工审批，并核实变更是否被正确应用。
• 4借助抽象层，专注于智能体本身的工作。Managed Deep Agents 负责托管、沙箱、Slack 集成和定时调度，你可以专注于让智能体真正有用的工具、上下文和决策规则。

在 LangChain 成立后的头三年里，我们的销售管道主要依靠自然增长，驱动力来自开源、内容、YouTube、社区和线下聚会。1 月，我们想启动付费广告计划，去触达那些靠自然增长覆盖不到的潜在客户，例如新地区的客户和企业决策者。

我们希望在短短六个月内，从以自然增长为主的增长引擎扩展到五个付费渠道。这给我们的小型营销团队带来了新挑战：我们要跟踪各渠道新上线的广告系列、各种创意和定向实验，以及不断增长、需要理解并据此行动的效果数据。

为了扩展规模并持续优化，我们必须跨过一些技术障碍。每个广告平台都有自己的数据 schema，很难在各渠道之间核对效果。广告系列的各项参数也无法干净地映射到我们最终关心的结果上，比如销售咨询、注册或内容下载。随着公司产品发布节奏加快、广告系列数量增多，想人工管理清楚什么在投放、什么有效、下一步该试什么，变得越来越难。

于是我们着手构建一个能帮助管理这些复杂性的智能体。它会跟踪新产品发布、起草广告系列、添加关键词、测试不同版本，并把拟议的实验提交给团队审批。随着时间推移，它将作为一个持续的学习闭环运转：分析效果、做出调整、观察结果、记录学到的经验，并把这些洞见应用于未来的广告系列。我们的目标是让营销团队更高效，同时持续提升广告系列的表现。

在这篇文章中，你将了解我们的付费媒体智能体是如何工作的、它如何为营销团队提供支持，以及我们在构建过程中学到的智能体工程经验。

“我们已将付费媒体智能体（Paid Media Agent）开源，你可以用它作为打造自己智能体的起点。你也欢迎参加太平洋时间 9 月 23 日上午 11 点的 GTM Engineering Live：How We Built Our Paid Media Agent。在这场网络研讨会上，我们将演示这个智能体，讲解代码和设计决策，并回答如何把这些模式应用到你自己智能体上的问题。”

• 1六个月内，付费媒体为营销管道带来的贡献从 0 提升到了 20%。
• 2从 6 月到 8 月，单个合格线索成本（CPL）下降了 30%，而月度支出上升了约 60%。在我们最大的社交渠道 LinkedIn 上，CPL 比 1 月时低了 40%。
• 3我们把分析和报告工作收回内部、不再依赖代理公司，每月节省了约 5,000 美元。
• 4我们还优化了智能体本身：把计算移入代码、去掉不必要的模型调用，让早期的报告工作流成本降为约原来的 1/40、速度提升 13 倍，运行时间从 18 分钟降到 85 秒。

付费媒体智能体是一个长期运行、常驻 Slack 的智能体。每周一，它会把广告平台数据与数据仓库中的线索和管道数据结合起来，为每个平台发布一份摘要和一份带有品牌样式的 PDF，说明发生了什么变化、为什么变化，以及团队接下来该做什么。

团队成员可以在某个线程中 @ 它，追问广告系列、花费或管道相关的问题。它还能基于我们的打法手册和编码进去的判断规则，提出新关键词、定向调整、广告文案或新的搜索广告系列建议。

我们围绕一个简单的原则构建这个智能体：编程智能体就是一名知识工作者。

知识型工作通常包括阅读文件、转换信息、运行分析以及把结果记录下来。编程智能体同样借助文件和 shell 完成这些任务。

我们把智能体当作一名新入职的付费媒体分析师来对待：给它一台电脑、完成工作所需的软件、访问我们数据的权限，以及介绍我们业务如何运转的文档。

我们使用 LangChain Deep Agents 作为智能体运行框架（agent harness），从而不必从零构建核心智能体基础设施。就像操作系统一样，Deep Agents 管理着文件访问、代码执行和工作记忆。它为模型提供工具，用于规划工作、把任务委派给子智能体，并在任务变得更复杂时管理上下文。这一层基础就是智能体运行框架。我们在这个基础之上叠加付费媒体工具、技能和业务知识。

每一次运行都默认配有一个 LangSmith Sandbox。它是一台隔离的 microVM，配有 32 GB 磁盘和一个用于执行命令的 shell。沙箱为智能体提供了一个安全、隔离的环境，可以执行代码、处理文件，而不会影响其他运行或底层系统。

我们为它配备了用于分析的 pandas 和 DuckDB、处理电子表格的 openpyxl，以及生成报告的 WeasyPrint 和 Jinja2。与这些软件放在一起的，还有它的工作数据和业务知识，以 Markdown 形式存放在六个技能和一份十九页的 wiki 中。

为了让启动保持快速，我们把软件和业务 wiki 预先打包进一个快照——一种沙箱启动时所依据的保存好的镜像。这将平均启动时间缩短了 10 秒。

“💡 不同的智能体需要不同的电脑。我们的内容生成智能体，其沙箱看起来更像一台视频剪辑工作站：有无头浏览器、ffmpeg、媒体工具和品牌手册。财务智能体可能需要 openpyxl 来处理电子表格、用 DuckDB 做更重的数据处理。任务决定了你该如何设计这台电脑。”

有了电脑之后，下一个挑战是给它提供恰当的上下文。人类分析师需要理解自己的角色、使用的方法、所在的公司、当下正在发生什么，以及必须遵守哪些规则。

最直接的做法是把所有这些内容都塞进系统提示词。但那样会导致提示词过长，每次运行都要为此付出高昂代价，而且很容易过时。

换个更好的角度来思考这个问题：瓶颈往往在上下文窗口，而不是模型。许多表面上的推理失败，实际上是上下文失败——要么是模型缺少正确的信息，要么是太多无关信息在争夺它的注意力。

我们不把提示词当作存放知识的地方，而是把它当作一张地图。知识存放在位置可预测的结构化文件里，智能体只加载当前任务所需的上下文。

“💡 设计智能体的工作区，值得投入和挑选工具同样多的心思。我们发现，智能体只需组合桌面上已有的东西，就能回答那些我们从未为其构建显式工作流的问题：它有打法手册指引调查方向，有广告系列数据可以处理，还有用来分析的库。设计这个工作区，本身就成了设计智能体的一部分。”

我们把上下文拆成五个层次，下面逐层说明（按各层变化快慢排序）：

• 1系统提示词：定义智能体的角色和导航。我们的提示词以一句话描述智能体的角色开头，随后是三个简短部分：如何操作、数字从哪里来、如何呈现结果。其余内容都是给智能体的指引，例如：打法手册在这里，wiki 在那里，先读索引。提示词告诉智能体去哪里找到它需要的东西。
• 2技能（Skills）：六个存放指令的文件夹，在运行时渐进式披露。智能体最初只能看到每个技能的标题和描述。
• 3Wiki：十九页文档，解释我们的漏斗如何运转、每个广告系列的目标是什么、哪个数据源拥有哪个数字，以及团队做过哪些决策、为什么。
• 4实时工具：花费、设置和管道每天都在变化，因此智能体在请求时才去获取。我们有 218 个这样的调用。下文会说明我们如何避免它们把上下文撑得过大。
• 5确定性代码：凡是需要一致且可复现的事情，我们都用代码处理，包括计算、日期窗口、账户匹配和硬性防护措施。例如，防止智能体在管道主力广告系列仅经历一周低迷后就削减它的规则，是在代码中强制执行的，模型无法推翻。最难划的一条线在技能和 wiki 之间。技能说明的是如何做这件事：读数据、算数字、写报告、准备变更，以及套用解读付费媒体表现的打法手册。其中不包含任何我们广告系列特有的内容。

wiki 装的则全是 LangChain 特有的东西：哪个广告系列用于品牌曝光、哪个该推动演示请求、我们 7 月做了什么决定、为什么。

“💡 技能应该“换一家公司也能用”，而 wiki 不应该如此。换句话说，技能沉淀的是可复用的工作方式，而 wiki 存放的是这些技能运转所需的、特定于公司的上下文。”

这沿用了 Karpathy 那篇 LLM wiki 笔记以及我们自己的 Wiki Memory 中的模式。

我们最初构建了两个智能体图（graph），因为两种用户体验看起来不一样：

• 1周报智能体按计划调度，并产出大量制品。它使用 Deep Agent、沙箱、大模型和 PDF 生成。
• 2Slack 需要在几秒内给出回答，因此采用更便宜模型上的轻量循环，配备 Google Ads 和数据仓库工具，没有沙箱，且只有只读权限。

这种拆分只维持了五周。每项新能力都得实现两遍，功能到达 Slack 和报告的时间也不一致。Slack 无法处理附件，因为它没有沙箱；它也无法回答关于周一报告的追问，因为那些 PDF 出自另一个图。

错误在于把它们当成了两个产品。它们其实是通向同一套分析的两个入口，背后是同一套 wiki、技能、工具和事实来源规则。我们的做法是改为按请求隔离状态和能力：每个线程都有自己的沙箱和检查点，每次运行只看到它需要的工具。

现在只有一个图，为每个请求全新实例化：

• 1Slack 提及和周一的 cron 定时任务以不同的运行模式进入。
• 2定时运行只会看到一个工具 task()，它按平台委派给各自的子智能体。
• 3Slack 则获得更丰富的一组读取、数据仓库和广告系列操作工具。

这是同一个运行时，只是配置了不同的能力档案，运行在 LangSmith Deployment 上，由它负责托管、扩缩容和定时运行。由于 Slack 现在共享同样的沙箱架构，智能体还能打开报告 PDF，并在产生该报告的线程里回答追问。

“💡 要点：使用同一个运行时，为每个入口配置不同的能力档案。同一个工厂可以给不同用户不同的技能和权限。”

让智能体真正投入工作，让我们收获了五条经验，涉及如何把数字算对、如何回答未曾预料的问题，以及如何把分析转化为行动。

第一版周分析把所有事情都交给模型：我们把每一行广告系列数据、每个关键词、每条管道记录和每次落地页检查结果都装进上下文，然后让它计算花费和环比变化、为广告系列表现分类，并撰写报告。

它确实能跑通，但效率低下。在我们固定的测试集上，生成一份报告要处理约 390 万输入 token，因为模型必须读完全部原始数据，还得自己反复推导计算。这让每次运行更慢、更贵：耗时 1,112 秒，成本略高于 3 美元。这也让结果更难令人信服，因为底层数字每次都要靠模型重新计算。

我们发现代码更适合做确定性工作。现在由 Python 获取数据、对齐日期窗口、计算总量和对比、应用固定规则，并把一份精简的结果写入沙箱。模型随后专注于需要判断的工作：串联证据、解释可能的原因、对照目标评估广告系列，并推荐下一步行动。

我们有六个平台，它们的 ID、转化定义、归因窗口和广告系列层级各不相同。试图把所有东西规范化成一套完美的 schema，只会增加复杂度，却未必让数据更可信。

相反，我们为每类指标定义了应该信任哪个系统。花费、展示量、点击量等媒体活动以广告平台为事实来源；一旦有人发生转化，线索、商机、管道等下游结果我们就以数据仓库为准。

当一些 Google 视频广告系列无法干净地映射进数据仓库时，我们才体会到这件事为什么重要。我们的仓库用关键词来关联广告系列数据，但视频广告系列不一定有关键词。结果，约 10% 的 Google 花费在仓库里缺失了，尽管 Google 自己有准确的花费数据。Meta 则有相反的局限：它能告诉我们某条广告产生了转化，但要说清这个转化到底是什么——比如是“联系销售”请求还是“注册”——我们的仓库更在行。这些例子进一步印证了：不要指望任何一个系统对所有指标都有最佳答案。

我们把这些事实来源规则编码进智能体：规则写在 wiki 里，同时我们会移除那些可能让智能体针对某个指标去查询错误系统的工具。有了数据来源边界、转化映射和广告系列层级的定义，智能体就能跨平台工作，而不需要一套完美规范化的 schema。

当数据无法可靠关联时，智能体不会试图填补空缺。它会保留这些局限，并在回答中注明相关的数据来源、日期窗口和归因模型，让团队明白每个数字是如何得出的。

“💡 要点：不需要先有一套完美的数据模型，智能体才能跨系统工作。更重要的是为每个指标定义权威来源，把这些规则显式化，并在底层数据无法干净地对齐时保留不确定性。”

要回答“我们的广告花费换来了多少管道？”这类问题，需要访问两个系统：广告平台提供花费和点击量，而我们的 BigQuery 数据仓库把广告系列活动和网站转化关联到合格线索、Salesforce 商机和管道。

我们希望智能体能同时在这两个系统上工作，而无需加载数百个工具定义，也不必为每个问题新写一个工具。

Pipeboard 的 MCP 暴露了 200 多个广告平台工具。早在 6 月，即便是我们较小的只读目录，也要先花 38,000 token 来加载可用工具的名称、描述和参数，之后智能体才读到用户的问题。这些上下文对任何单个请求来说大部分都是无关的。

我们的数据仓库也有类似问题。我们为一些反复出现的问题（如按广告系列统计管道、按广告组统计转化）建了固定查询。但每出现一种新的数据分组方式——比如按单个销售商机统计管道——就需要再写一个专用工具。

我们给智能体提供了一个用于查找所需内容的小接口，一并解决了这两个问题。

Pipeboard 的目录藏在三个工具后面：

1. 1搜索（Search）：根据问题找出最多 8 个工具。
2. 2读取（Read）：只为选定的工具加载完整 schema。
3. 3执行（Run）：通过我们的服务器执行该工具。广告系列的写操作走单独的、需审批把关的路径。

对于数据仓库，我们添加了两个灵活的工具：

1. 1描述可用的表和字段。
2. 2运行分析查询。

智能体可以查看 schema 并为问题组合出所需的查询，而不是为每种可能的分组都依赖一个预建工具。

目录让首轮对话降到了约 12,000 token。在我们的对比测试中，它的成本只有加载全部 schema 的 1/4，同时保持了相同的评估质量。此后目录规模接近原来的三倍，而上下文成本基本保持稳定。

我们在 60 次真实运行中测试了固定仓库工具、查询接口，以及两者结合。固定工具在常规问题上表现良好，但对更深的问题能正确报告为不支持。带查询接口的两种版本则回答了所有分析类问题。

两种方式我们都保留了。固定工具为常见问题提供快速通道，查询接口则处理我们没预料到的问题。

“💡 要点：给智能体一条按需查找和调用能力的途径，而不是把每个工具都预先放进上下文。”

迁移到共享运行时后，我们面临另一个挑战：如何让智能体分析五个平台，而不把每个平台的数据都塞进同一个上下文窗口？

我们在真实数据上测试了三种架构：

1. 1每个平台一次独立运行。
2. 2一个智能体处理所有平台。
3. 3由父智能体按平台委派给各自的子智能体。

独立运行是最简单的架构，但在实际工作流中表现最差：每次运行只看到单个平台，于是系统发出多条 Slack 消息，很难综合跨渠道的表现。

两种集中式方案都能产出单一结果并完成跨平台综合。我们最终选择了父智能体加子智能体的架构，因为它既让父智能体的上下文保持精简，又给每个平台各自的上下文窗口来存放平台特有的数据和注意事项。

但独立的上下文窗口并不会自动带来完全的隔离，我们仍需自行设计。

例如：

• 1一个平台可能意外抑制另一个平台。两个子智能体往同一位置写报告、共享同一个“完成”标志。第一个完成后，第二个可能把那个状态误当成自己的，于是不再产出报告就停止了。我们为每个平台分配了各自的报告位置和完成状态，修复了这个问题。
• 2子智能体可能在验证自身工作时卡住。一个子智能体无法确定自己的 PDF 是否已渲染，就不停检查文件、烧掉大量 token，最后甚至试图从零重建 PDF。现在子智能体只有三个工具：读上下文、计算和渲染。渲染成功，任务即完成。

子智能体给了你一个独立的上下文窗口，其余的隔离设计都要靠你自己：你仍需定义它能用哪些工具、能访问哪些文件和状态、必须返回什么，以及失败时如何处理。

只会分析表现的智能体，终究只是一块更好的仪表盘。我们希望智能体帮助团队基于它的发现采取行动。

它可以直接在 Slack 中提出变更建议，比如添加关键词、更新地理定向或创建新的搜索广告系列。

赋予智能体行动能力的同时，也带来了一项新需求：权限。

付费媒体之外的团队可以用这个智能体询问广告系列表现和管道相关问题，但只有指定的团队成员才能编辑或批准广告系列变更。服务器在接受这两类操作前都会校验 Slack 用户 ID，其他任何人的请求都会被拦截，提案保持待定状态。

每项拟议变更都会出现在一张用 Block Kit 构建的 Slack 审批卡片中。获授权的审核人可以对比当前值和拟议值、做出修改并批准最终方案。随后由代码应用已批准的变更，并检查广告平台以确认变更成功。

这带来了很有价值的职责分离：智能体可以分析表现并建议行动，但是否真正执行该行动由人来决定。

“💡 要点：闭环靠的不只是写权限。要给智能体一条清晰的行动路径，内置权限、审批和验证。”

Slack 作为第一个界面效果很好，因为审批卡片可以和引出它的分析与讨论留在同一线程里。跨团队的成员都能提问和发表意见，而广告系列负责人仍掌控着哪些变更真正被应用。

这种方式最适合相对聚焦的决策。当智能体开始处理更复杂的工作——例如包含大量广告组和广告素材的广告系列、批量编辑，或需要多轮修改的方案——Slack 作为主要工作区就变得难以胜任了。

我们正在把这些更复杂的工作流迁移到一个围绕智能体构建的专用界面中，同时保留 Slack 作为轻量的场所，用于提问、查看建议和批准变更。相关内容将在后续文章中详述。

我们想要一个能应对未曾预料的问题、产出可核验的数字、并基于发现采取行动的智能体。以下是我们会带进下一个智能体的设计原则：

• 1像为新员工置办装备一样武装智能体。给它沙箱、好用的库、访问正确数据的权限和清晰的文档。一个设计良好的工作区，让智能体无需为每个新问题单独建工作流，就能展开调查。
• 2把可复用的指令与公司知识分开。技能说明如何做事，wiki 解释业务，实时工具提供当前信息。把这些层分开，每一层都更容易更新，系统提示词也不会随之膨胀。
• 3需要可复现的工作交给代码。计算、对比和硬性规则都属于代码。模型于是可以专注于解读结果、判断其含义。
• 4显式设计边界。子智能体仍需明确的规则来约束它能访问哪些工具、文件和状态，应该返回什么，以及如何处理失败。独立的上下文窗口只是隔离的一部分。
• 5以智能体能否完成工作为优化目标。降低 token、成本和延迟固然重要，但如果因此削弱了智能体的能力就得不偿失。我们发现，把这些指标与完成率和回答质量放在一起评估更有用。
• 6让真实使用告诉你哪些集成需要改进。智能体反复难以回答的问题，正揭示了哪里值得构建更干净的关联、更好的定义或专用工具。

目前，智能体主要响应定时运行和团队的请求。我们希望它变得更加主动：持续监控广告系列表现，提示值得关注的变化，并提出新的实验和优化方案供团队审核。

更大的机会是把这些经验在整个 GTM 体系中打通。广告系列互动可以指导销售如何跟进，而管道推进、销售对话和成单结果又能加深我们对理想客户的理解，并影响下一个广告系列。

随着时间推移，我们希望各个 GTM 智能体都能为同一份共享知识和打法手册做贡献，让组织中一部分学到的东西，能改进漏斗其余部分的定向、信息传递和实验。

欢迎参加太平洋时间 9 月 23 日上午 11 点的 GTM Engineering Live：How We Built Our Paid Media Agent。在这场网络研讨会上，我们将演示智能体，讲解代码和设计决策，并回答如何把这些模式应用到你自己智能体上的问题。

你也可以把这个付费媒体智能体带到自己的团队。我们已将其开源，其中包括广告平台工具、付费媒体技能、示例 wiki、报告和审批工作流。接入你的账户，给它你公司的上下文，然后通过 Managed Deep Agents 一条命令就能部署到 Slack。