我们怎么造 LangChain 的付费媒体 Agent

For LangChain's first three years, our sales pipeline grew largely organically, driven by open source, content, YouTube, community, and meetups. In January, we wanted to kickstart our paid advertising program to start connecting with prospects we weren't reaching organically, such as those in new regions and enterprise decision makers. We wanted to scale from a largely organic growth engine to five paid channels in just six months. This created new challenges for our small marketing team. We had to keep track of new campaigns launching across channels, different creative and targeting experiments, and a growing volume of performance data to understand and act upon. Each advertising platform has its own data schema, making it difficult to reconcile performance across channels. Campaign parameters also do not map cleanly to the outcomes we ultimately care about, such as sales inquiries, signups, or content downloads. We set out to build an agent that could help manage that complexity. It would track new product announcements, draft campaigns, add keywords, test variations, and surface proposed experiments to the team for approval. Over time, it would operate as a continuous learning loop: analyze performance, make a change, observe the outcome, capture what it learned, and apply those insights for future campaigns.

LangChain 头三年的销售管道主要靠自然增长：开源、内容、YouTube、社区与线下聚会。一月我们想启动付费广告计划，触达自然渠道够不到的人群——新地区的企业决策者等。目标：六个月内从自然增长引擎扩到 5 个付费渠道。这给小营销团队出了新难题：跨渠道跟踪新上的 campaign、各式创意与定向实验、越来越大的表现数据量要看懂并行动。每个广告平台有自己的数据 schema，跨渠道对账困难；campaign 参数也与我们真正关心的结果（销售询问、注册、内容下载）对不干净。我们着手造一个 agent 来管这份复杂：跟踪产品公告、起草 campaign、加关键词、试变体、把建议的实验提给团队审批——随时间运转成一个持续学习环：分析表现、做改动、观察结果、记下所学、用于后续 campaign。

Paid media went from driving 0 to 20% of our marketing pipeline in six months. Cost per qualified lead (CPL) fell 30% from June to August, while monthly spend rose about 60%. On LinkedIn, our largest social channel, CPL was 40% lower than it had been in January. We saved about $5K per month by bringing analysis and reporting in-house instead of relying on an agency. We also optimized the agent itself by moving calculations into code and removing unnecessary model calls, making an early reporting workflow about 40x cheaper and 13x faster, with runtime dropping from 18 minutes to 85 seconds.

六个月内，付费媒体对营销管道的贡献从 0 涨到 20%；单合格线索成本（CPL）六到八月降 30%（月花费还涨了约 60%）；最大社交渠道 LinkedIn 的 CPL 比 1 月低 40%。分析与报告收回自家做（不再依赖代理），每月省约 5,000 美元。agent 自身也被优化：把计算挪进代码、砍掉不必要的模型调用后，早期报告工作流便宜约 40 倍、快 13 倍——运行时间从 18 分钟降到 85 秒。

The Paid Media Agent is a long-running agent that lives in Slack. Every Monday, it combines ad-platform data with lead and pipeline from our warehouse. It posts a summary and a branded PDF for each platform explaining what changed, why, and what the team should do next. The team can tag it in a thread to ask follow-up questions about campaigns, costs, or pipeline. It can also propose new keywords, targeting changes, ad copy, or new search campaigns based on our playbook and encoded judgement.

付费媒体 agent 是住在 Slack 里的长跑 agent。每周一，它把广告平台数据与仓库里的线索及管道数据合并，为每个平台发一份摘要与品牌化 PDF：什么变了、为什么、团队下一步该做什么。团队可在线程里@它追问 campaign、成本或管道；它也能按我们的 playbook 与编码在案的业务判断，提议新关键词、定向调整、广告文案或新搜索 campaign。

We built this agent around a simple principle: a coding agent is a knowledge worker. Knowledge work often involves reading files, transforming information, running analyses, and writing things down. A coding agent also does these tasks with files and a shell. We treated the agent like a new paid-media analyst. We gave it a computer, the software it needed to do the job, access to our data, and documentation about how our business works.

我们围绕一条简单原则建它：**coding agent 是知识工作者**。知识工作常是读文件、转换信息、跑分析、写下结论；coding agent 用文件和 shell 干同样的事。我们把它当一位新来的付费媒体分析师对待：给它一台电脑、干活的软件、数据访问、以及一份「我们业务怎么运作」的文档。

We used LangChain Deep Agents for our agent harness so we didn't have to build core agent infrastructure from scratch. Just like an operating system, Deep Agents manages access to files, code execution, and working memory. It gives the model tools to plan work, delegate tasks to subagents, and manage context as tasks become more complex. This foundation is the agent harness. We layer our paid-media tools, skills, and business knowledge on top. Every run has a LangSmith Sandbox available by default. It's an isolated microVM with a 32 GB disk and a shell for running commands. We equip it with pandas and DuckDB for analysis, openpyxl for spreadsheets, and WeasyPrint and Jinja2 for generating reports. Alongside that software are its working data and business knowledge, stored in Markdown across six skills and a nineteen-page wiki. To keep startup fast, we bake the software and business wiki into a snapshot, a saved image that the sandbox starts from. This reduced the average startup time by 10 seconds.

harness 用 LangChain Deep Agents，不必从零造 agent 基建。它像操作系统：管文件访问、代码执行与工作内存，给模型规划工作、把任务委托给子代理、随任务变复杂管理上下文的工具。这个底座就是 agent harness，我们把付费媒体的工具、skills 与业务知识叠在上面。每次运行默认配一个 LangSmith Sandbox——隔离 microVM，32GB 磁盘带 shell。装备：分析用 pandas 与 DuckDB、表格用 openpyxl、报告生成用 WeasyPrint 与 Jinja2；随软件一起的还有工作数据与业务知识（6 个 skill+19 页 wiki 的 Markdown）。为保启动快，软件与业务 wiki 烤进快照（沙箱从其启动的保存镜像）——平均启动时间省了 10 秒。

Once the agent had a computer, the next challenge was giving it the right context. A human analyst needs to understand their role, the methods they use, the company they work for, what is happening right now, and the rules they need to follow. The naive approach is to put all of that in the system prompt. However, that would lead to a prompt that is overly long, expensive to carry into every run, and likely to go stale. A better way to think about the problem is that the context window is often the bottleneck, not the model. Many apparent reasoning failures are actually context failures. Instead of treating the prompt as the place where knowledge lives, we treat it as a map. We split context into five layers: System prompt defines the agent's role and navigation — a one-sentence role description plus three short sections (how to operate, where numbers come from, how to present results), everything else is a pointer. Skills: six folders of instructions progressively disclosed at runtime. Wiki: nineteen pages explaining how our funnel works, what each campaign is intended to accomplish, which data source owns which number, and what decisions the team has made and why. Live tools: spend, settings, and pipeline change daily, so the agent fetches them at request time — we have 218 such calls. Deterministic code: we use code for anything that should be consistent and reproducible, including calculations, date windows, account matching, and hard safeguards — for example, a rule preventing the agent from cutting a top pipeline driver after one bad week is enforced in code, so the model cannot override it.

有了电脑，下一个挑战是给对上下文。人类分析师要懂角色、方法、公司、眼下发生的事、要守的规则。天真的做法是全塞系统提示词——那会太长、每次运行背着都贵、还容易过期。更好的思考方式：**上下文窗口常常是瓶颈，不是模型**——很多表面上的推理失败其实是上下文失败。我们不把提示词当知识的家，而当**地图**。上下文分五层：**系统提示词**定角色与导航（一句角色描述+三小节：怎么运作/数字从哪来/怎么呈现，其余全是指针）；**Skills**：六个指令文件夹运行时渐进披露；**Wiki**：19 页讲漏斗怎么运作、每个 campaign 意图为何、哪个数据源拥有哪个数字、团队做过什么决定为什么；**Live tools**：花费/设置/管道天天变，请求时现取——共 218 个此类调用；**确定性代码**：一切要求一致可复现的都进代码——计算、日期窗、账户匹配、硬护栏。例如「不许因一周表现差就砍头部管道来源」这条规则在代码里强制执行，模型无法覆写。

We originally built two agent graphs because the user experiences looked different: the weekly report agent was scheduled and artifact-heavy (a Deep Agent, sandbox, large model, PDF generation), while Slack needed answers in seconds (a lightweight loop on a cheaper model, with Google Ads and warehouse tools, no sandbox, read-only). That split only lasted five weeks. Every new capability had to be implemented twice. Features reached Slack and the report at different times. Slack could not process attachments because it had no sandbox, and it could not answer follow-ups on Monday reports because those PDFs came from another graph. The mistake was treating them as two products. They are two entry points into the same analysis, backed by the same wiki, skills, tools, and source rules. We instead isolate state and capabilities for each request. Each thread gets its own sandbox and checkpoint, and each run sees only the tools it needs. Now there is one graph, instantiated fresh for every request: Slack mentions and the Monday cron enter with different run modes. Scheduled runs see a single tool, task(), which delegates to one subagent per platform. Slack gets a broader set of read, warehouse, and campaign-operations tools. It is the same runtime with different capability profiles, hosted on LangSmith Deployment. And because Slack now shares the same sandboxed architecture, the agent can also open a report PDF and answer follow-up questions in the thread that produced it.

我们最初建了两个 agent 图，因为用户体验看着不同：周报 agent 定时跑、产物重（Deep Agent+沙箱+大模型+PDF 生成）；Slack 要秒答（便宜模型上的轻循环，Google Ads 与仓库工具，无沙箱、只读）。这个分裂只活了五周：每个新能力要做两遍、功能到达两边时间不同、Slack 端没沙箱处理不了附件、更答不了周一报告的追问——那些 PDF 出自另一个图。错误在于把它们当两个产品。**它们是同一分析的两个入口**，背后是同一套 wiki、skills、工具与数据源规则。改为按请求隔离状态与能力：每线程自己的沙箱与检查点，每次运行只见所需工具。现在只有一个图、每请求全新实例化：Slack 提及与周一 cron 以不同 run mode 进入；定时跑只见单一工具 task()（按平台委托给子代理），Slack 见更宽的只读/仓库/campaign 运营工具集。同一运行时、不同能力档，托管在 LangSmith Deployment 上。因为 Slack 现在共享同一沙箱架构，agent 还能打开报告 PDF、在产出它的线程里回答追问。

Our first version of the weekly analysis asked the model to do everything. We loaded every campaign row, keyword, pipeline record, and landing-page check into context, then asked it to calculate spend, week-over-week changes, classify campaign performance, and write the report. It worked, but inefficiently. On our frozen test set, a single report processed about 3.9 million input tokens because the model had to read all of that raw data and repeatedly work through calculations itself. That made each run slower and more expensive, taking 1,112 seconds and costing just over $3. It also made the results harder to trust because the model was responsible for recomputing the underlying numbers every time. We found that code was better suited for deterministic work. Python now fetches the data, aligns date windows, calculates totals and comparisons, applies fixed rules, and writes a compact set of results to the sandbox. The model then focuses on the work that requires judgment: connecting the evidence, explaining likely causes, evaluating campaigns against their goals, and recommending what to do next.

v1 的周分析让模型什么都干：全部 campaign 行、关键词、管道记录、落地页检查载入上下文，让它算花费、环比、给 campaign 分类、写报告。能用，但低效——冻结测试集上单报告处理约 390 万（3.9 million）输入 token（模型要读全部原始数据、反复亲自过计算），单次跑 1,112 秒、花 3 美元出头；而且结果更难信：底层数字每次都靠模型重算。我们发现**确定性工作代码更胜任**：现在 Python 取数、对齐日期窗、算合计与对比、套固定规则，把紧凑的结果集写进沙箱；模型专注需要判断的工作——连证据、释可能原因、对照目标评 campaign、建议下一步。

We had six platforms with different IDs, conversion definitions, attribution windows, and campaign hierarchies. Trying to normalize everything into one perfect schema would have added complexity without necessarily making the data more trustworthy. Instead, we defined which system should be trusted for each type of metric. The ad platforms are the source of truth for media activity such as spend, impressions, and clicks. Once someone converts, we rely on our warehouse for downstream outcomes such as leads, opportunities, and pipeline. We learned why this mattered when some Google video campaigns did not map cleanly into our warehouse. Our warehouse joined campaign data using keywords, but video campaigns do not always have keywords. As a result, about 10% of Google spend was missing from our warehouse even though Google itself had the correct spend data. Meta had the opposite limitation: it could tell us that an ad generated a conversion, but our warehouse was better at telling us what that conversion actually was, such as a "Contact Sales" request versus a "Sign Up." We encoded those source-of-truth rules into the agent. They live in the wiki, and we remove tools that would let the agent query the wrong system for a given metric. When data cannot be joined reliably, the agent does not try to fill in the gaps. It preserves those limitations and includes the relevant source, date window, and attribution model in its answers.

六个平台各有 ID、转化定义、归因窗口与 campaign 层级。试图把一切归一成一个完美 schema 只会加复杂度、未必加可信度。我们改为**按指标类型定义该信哪个系统**：媒体活动（花费/展示/点击）权威在广告平台；一旦发生转化，下游结果（线索/机会/管道）权威在仓库。为什么这要紧——Google 视频广告的教训：仓库用关键词 join campaign 数据，而视频 campaign 不总有关键词，结果约 10% 的 Google 花费在仓库里缺失（Google 自己的数据是对的）；Meta 反过来：它能说某广告产生了转化，但「转化到底是什么」（联系销售还是注册）仓库更清楚。这些权威源规则编进 agent：写在 wiki，并删掉会诱导 agent 查错系统的工具。数据连不起来时 agent 不硬填——保留局限，答案里带上来源、日期窗与归因口径。

Answering a question like "What pipeline did we get for our ad spend?" requires access to two systems. Pipeboard's MCP exposes more than 200 ad-platform tools. Back in June, even our smaller read-only catalog required 38,000 tokens just to load the available tool names, descriptions, and arguments before the agent had read the user's question. Most of that context was irrelevant to any individual request. Our warehouse had a related problem: we had built fixed queries for recurring questions, but each new way of grouping the data required another dedicated tool. We solved both problems by giving the agent a small interface for finding what it needs. Pipeboard's catalog sits behind three tools: Search finds up to eight tools based on the question; Read loads the full schema only for the selected tool; Run executes that tool through our server (campaign writes use a separate approval-gated path). For the warehouse, we added two flexible tools: describe the available tables and fields, and run an analytical query. The agent can inspect the schema and compose the query required for the question. The catalog brought the first turn down to about 12,000 tokens — in our comparison, 4x cheaper than loading every schema while maintaining the same judged quality. The catalog has nearly tripled since then, while its context cost has stayed roughly consistent. We tested fixed warehouse tools, the query interface, and both together across 60 live runs. Fixed tools worked well for routine questions but correctly reported deeper questions as unsupported. Both versions with the query interface answered all the analytical questions. We kept both approaches: fixed tools provide a fast path for common questions, while the query interface handles questions we did not anticipate.

答「广告花费带来了多少管道」要碰两个系统。Pipeboard 的 MCP 暴露 200+ 广告平台工具——六月时哪怕我们较小的只读目录，光装工具名/描述/参数就要 38,000 token，而 agent 还没读到用户问题；其中大部分与单个请求无关。仓库有姊妹问题：为高频问题建了固定查询，但每种新分组方式又要一个专用工具。两题同解：给 agent 一个发现接口。Pipeboard 目录藏在三工具后：**Search**（按问题找最多 8 个工具）、**Read**（只读选中工具的完整 schema）、**Run**（经我们的服务器执行，campaign 写操作走单独的审批门）。仓库侧加两个弹性工具：**描述**可用表与字段、**跑**分析查询——agent 能检查 schema、按问题组装查询。目录方案把首回合降到约 12,000 token，对比便宜 4（4x）倍而质量持平；此后目录近三倍、上下文成本基本没涨。60 次实测（3 组各 20）（固定工具/查询接口/两者并用）：固定工具答好常规题但把深问题正确地报为「不支持」；带查询接口的两版答全了所有分析题。两种都留：固定工具走常用快路，查询接口接没预料到的问题。

Once we moved to a shared runtime, we had another challenge: how could the agent analyze five platforms without putting every platform's data into one context window? We tested three architectures on live data: one isolated run per platform; one agent handling every platform; a parent agent delegating to one subagent per platform. Separate runs were the simplest architecture, but they performed worst for the actual workflow — each run saw only one platform, so the system produced multiple Slack messages and struggled to synthesize performance across channels. Both consolidated approaches produced a single output with cross-platform synthesis. We ultimately chose the parent-plus-subagents architecture because it kept the parent's context small while giving each platform its own context window. But separate context windows did not automatically give us full isolation. For example: one platform could accidentally suppress another — two subagents were writing reports to the same location and sharing the same "done" flag; once the first finished, the second could mistake that state for its own and stop without producing a report (fixed by giving each platform its own report location and completion state). A subagent could get stuck trying to verify its own work — when one could not determine whether its PDF had rendered, it kept checking files, burned a ton of tokens, and eventually tried to build the PDF from scratch (subagents now get only three tools: read context, compute, render — if render succeeds, the job is done). A subagent gives you a separate context window. The rest of the isolation model is up to you.

转向共享运行时后又来一题：怎么分析 5 个平台而不把每家的数据塞进同一个上下文窗口？真数据上测了三种架构：每平台独立跑、单 agent 全包、父 agent 按平台委托子代理。独立跑最简单但对实际工作流最差——每次只见一个平台，产出多条 Slack 消息、跨渠道综合吃力。两种合并架构都能出带跨平台综合的单一产出；最终选**父+子代理**：父上下文保持小，各平台有自己的窗口装自己的数据与注意事项。但独立上下文窗口不自动等于完整隔离。例如：一个平台可能意外压掉另一个——两个子代理写同一报告位置、共享同一个 done 标志，第一个完成后第二个把状态误当自己的、没出报告就停了（修法：各平台独立的报告位置与完成态）。子代理会卡在验证自己的产出上——一个子代理判断不了 PDF 渲出来没有，反复查文件烧掉一堆 token，最后试图从零重建 PDF（修法：子代理只给三工具——读上下文、计算、渲染；渲染成功即完成）。**子代理给你的是独立上下文窗口，隔离模型的其余部分由你设计。**

An agent that only analyzes performance is ultimately a better dashboard. We wanted the agent to help the team act on what it found. It can propose changes directly in Slack, such as adding a keyword, updating geographic targeting, or creating a new search campaign. Giving the agent the ability to take action also introduced a new requirement: permissions. Teams outside paid media can use the agent to ask questions about campaign performance and pipeline, but only designated team members can edit or approve campaign changes. The server checks Slack user IDs before accepting either action. Requests from anyone else are blocked, and the proposal remains pending. Each proposed change appears in a Slack approval card built with Block Kit. Authorized reviewers can compare the current and proposed values, make edits, and approve the final plan. Code then applies the approved change and checks the ad platform to confirm it succeeded. This gave us a useful separation of responsibilities. The agent can analyze performance and recommend an action, but a human controls whether that action is actually taken.

只分析表现的 agent 说到底是个更好的仪表盘。我们要 agent 帮团队**据发现而行动**：它能在 Slack 里直接提议改动——加关键词、更新地域定向、新建搜索 campaign。行动能力带来了新要求：**权限**。付费媒体之外的团队可以用它问 campaign 表现与管道，但只有指定成员能编辑或批准 campaign 改动——服务器先核 Slack 用户 ID，别人的请求被挡、提案保持待批。每个提案以 Block Kit 审批卡出现在 Slack：授权评审者对比现值与提案值、可改、批最终方案；然后由代码执行批准的变更并回查广告平台确认成功。这给了我们好用的责任分离：agent 分析表现、推荐行动，而**行动是否真被采取由人控制**。

Slack worked well as the first interface because the approval card could live in the same thread as the analysis and discussion that led to it. That approach works best for relatively focused decisions. As the agent started handling more complex work, such as campaigns with many ad groups and creatives, bulk edits, or plans that needed several rounds of revision, Slack became harder to use as the primary workspace. We are moving those more complex workflows into a dedicated interface built around the agent, while keeping Slack as a lightweight place to ask questions, review recommendations, and approve changes.

Slack 当第一界面好用，因为审批卡能和引出它的分析、讨论住在同一线程。这对相对聚焦的决定最合适。当 agent 开始接更复杂的活——多广告组与创意的 campaign、批量编辑、需要多轮修订的方案——Slack 作为主工作区就吃力了。我们正把这些复杂工作流迁进围绕 agent 建的专用界面，Slack 保留为轻量场所：问问题、看建议、批变更。

We wanted an agent that could handle questions we hadn't anticipated, produce numbers we could verify, and act on what it found. These are the design principles we would carry into another agent: Equip the agent like a hire — give it a sandbox, useful libraries, access to the right data, and clear documentation. Separate reusable instructions from company knowledge — skills explain how to do the work, the wiki explains the business, live tools provide current information. Use code for work that should be reproducible — the model then focuses on interpreting the results. Design boundaries explicitly — a separate context window is only one part of isolation. Optimize for whether the agent can finish the job — evaluate tokens, cost, and latency alongside completion rate and answer quality. Let real usage show you where integrations need improvement — the questions the agent repeatedly struggles to answer reveal where cleaner joins, better definitions, or dedicated tools are worth building.

我们要的 agent 能接没预料到的问题、产出可验证的数字、据发现而行动。这些是会带进下一个 agent 的设计原则：**像对待新员工一样装备它**（沙箱、好用的库、对的数据访问、清晰的文档）；**可复用指令与公司知识分离**（skills 讲怎么做、wiki 讲业务、live tools 给现值）；**可复现的活交给代码**（模型专注解读结果）；**显式设计边界**（独立上下文窗口只是隔离的一部分）；**以「能否把活干完」为优化目标**（token/成本/延迟与完成率、答案质量一起看）；**让真实用法指出集成哪里要改**（agent 反复答不好的问题，暴露哪里值得建更干净的 join、更好的定义或专用工具）。

Today, the agent primarily responds to scheduled runs and requests from the team. We want it to become more proactive by continuously monitoring campaign performance, surfacing changes that deserve attention, and proposing new experiments and optimizations for the team to review. The bigger opportunity is to connect those learnings across GTM. Campaign engagement can inform how sales follows up, while pipeline progression, sales conversations, and deal outcomes can improve our understanding of the ideal customer and influence the next campaign. Over time, we want our GTM agents to contribute to the same shared knowledge and playbooks so that what one part of the organization learns can improve targeting, messaging, and experimentation everywhere else.

今天 agent 主要响应定时跑与团队请求。我们想让它更主动：持续监控 campaign 表现、浮出值得注意的变化、给团队提议新实验与优化。更大的机会是把这些所学连通整个 GTM：campaign 互动指导销售跟进；管道推进、销售对话与成交结果反过来加深对理想客户的理解、影响下一场 campaign。随时间推移，我们要让 GTM agent 们贡献同一份共享知识与 playbook——组织一部分学到的东西，改进其余所有部分的人瞄、话术与实验。