有效商业智能体构建指南 | Anthropic 的 Claude

在过去一年里，我们与商务行业的各类团队展开合作——包括零售商、市场平台、旅游、娱乐和电信服务提供商——使用 Claude 构建商务代理。Over the past year, we've worked with teams across the commerce industry — retailers, marketplaces, travel, entertainment, and telecom providers — to build commerce agents using Claude. 

这些代理已投入生产环境，企业客户在使用它们时看到了更大的购物车和更高效的卖家运营。它们还共享一种简单的架构：处于代理循环中的 Claude，配备一组技能、工具和完善的评估套件。These agents are in production, and enterprise customers have seen larger carts and more efficient seller operations when using them. They also share a simple architecture: Claude in an agent loop equipped with a set of skills, tools, and a strong eval suite.

这篇文章面向构建这些（或其他面向消费者的）智能体的工程师和工程负责人。第一部分介绍架构，这部分只需决定一次。第二部分介绍延迟和成本。第三部分介绍生产环境：记忆、安全性、评估，以及如何在组织内扩展这项工作。This post is for the engineers and engineering leaders building these (or other consumer facing) agents. Part 1 covers the architecture, which you decide once. Part 2 covers latency and cost. Part 3 covers production: memory, safety, evals, and scaling the work across an organization.

什么是商务代理？What is a commerce agent?

我们将商务代理定义为一种简化在线目录中买卖流程的代理。We define a commerce agent as an agent that simplifies buying and selling across an online catalog.

有些代理面向消费者：它们进行搜索、比较、替代和组装订单。这可能是一个零售购物车、一份旅行行程、移动套餐变更，或为演出预留的座位。有些代理面向企业：它们回答有关销售的问题，开展促销和营销活动，并管理库存与定价。Some agents face consumers: they search, compare, substitute, and assemble the order. That could be a retail cart, a travel itinerary, a mobile plan change, or seats held for a show. Some agents face the business: they answer questions about sales, run promotions and campaigns, and manage inventory and pricing. 

核心架构是标准智能体循环中的一种模型：围绕目标进行推理、探索上下文、通过工具采取行动、通过技能学习流程、提出澄清性问题，并观察结果，直到目标达成为止。The core architecture is a model in a standard agent loop: reasoning about a goal, exploring context, taking actions through tools, learning procedures through skills, asking clarifying questions, and observing the results until the goal is accomplished.

它前面没有用于划分对话的意图路由器，后面也没有一组特定领域的代理。There is no intent router in front of it that segments the conversation and no set of domain specific agents behind it.

工程背景Engineering context

技能，而不是子代理Skills, not subagents

商务代理需要覆盖许多类别和意图中的广泛能力，这很容易让人想要为每个领域创建一个子代理。A commerce agent has to cover a wide range of capabilities across many categories and intents, which makes it tempting to create one subagent per domain.

在实践中，这种做法并不理想，因为商务对话是一个跨越多个意图和轮次的紧密耦合会话，需要大量共享上下文。In practice this proves suboptimal, because a commerce conversation is one tightly coupled session across multiple intents and turns, and requires considerable shared context.

在子代理架构中，编排器保存购物车或暂存的更改、用户偏好以及对话历史。In a subagent architecture, the orchestrator holds the cart or staged changes, the user's preferences, and the conversation history.

向子代理的每次交接都是一种有损状态传递操作，通常会影响子代理响应的质量，进而影响整体响应的质量。此外，每次交接可能会消耗数倍的令牌，并增加数秒的延迟。Every handoff to a subagent is a state-lossy operation, which often impacts the quality of the subagent’s response and, consequently, the overall response. On top of that, each handoff can cost several times the tokens and adds seconds of latency.

这些领域也很少能清晰地分开。退货流程可能需要访问订单历史记录、当前购物车和产品目录，这意味着按领域为每个子代理分配任务的方法，要么在各处重复提供这些访问权限，要么就在任务进行到一半时转交任务。The domains also rarely separate cleanly. A returns flow might need the order history, the current cart, and the product catalog, meaning a subagent-per-domain approach either duplicates that access everywhere or hands off mid-task.

随着模型变得更加智能，它们也能处理更长的上下文、掌握更多技能并使用更多工具，因此，当前部署规则背后的限制会随着每一代模型的推出而逐渐放宽。As models get smarter, they also handle longer context, more skills, and more tools, so the limits behind today's placement rules loosen with each model generation.

相反，代理技能无需承担交接成本，就能为你提供类似的按领域模块化和上下文控制，因为技能指令会加载到已经掌握完整历史记录的主代理中。Instead, agent skills give you similar per-domain modularity and context control without the handoff tax, because the skill instructions load into the main agent that already holds the entire history.

在我们对多个企业部署方案进行比较时，一个具备技能的单一代理在质量方面始终优于“一条提示词处理所有任务”的设计和子代理设计，而且每项任务的成本和延迟通常也更低。In our comparisons across several enterprise deployments, a single agent with skills consistently has outperformed both the one-prompt-for-everything design and the subagent design on quality, and often at a lower cost and latency per task.

子代理真正发挥作用的场景，是编排器可以将其作为工具调用，用于某个狭窄或自包含的任务，而该任务又能从专属的上下文窗口中受益。Where subagents do earn their place is when the orchestrator can call them as a tool for a narrow or self-contained task that would benefit from its own dedicated context window.

一个常见的生产环境示例是深度研究子代理：子代理会搜索和阅读文档、编写并运行代码、遍历数据模型，也会走入死胡同。所有工作都在一个或多个子代理内部完成，最终只有简洁的答案返回给编排器。A common production example is a deep-research subagent, where the subagent searches and reads documents, writes and runs code, traverses data models, and hits dead ends. All the work happens inside one or more subagents, and only a compact answer comes back to the orchestrator.

另一个例外是某个领域已经拥有专门为其打造的代理。如果你的药房或金融服务体验运行着一个具有自身合规范围的专用代理，那么合适的做法可能是进行交接：由该代理接管任务，并通过自身的循环直接与用户协作，直到任务完成。The other exception is a domain that already has its own purpose-built agent. If your pharmacy or financial-services experience runs a dedicated agent with its own compliance surface, the right move can be a hand-off, where that agent takes over the task and works with the user directly through its own loop until the task is done. 

区别在于对话的所有权。移交会让领域代理成为用户的对话方，而委派则保留编排器的主导地位，在单个回合中让领域代理不断进出，并且在每次交互中逐渐退化。The distinction is ownership of the conversation. A hand-off makes the domain agent the user's counterpart, while delegation keeps the orchestrator, bouncing the domain agent in and out within a single turn and degrading on every exchange.

系统提示词或技能：按频率决定System prompt or skill: decide by frequency

决定是否将一组指令放入系统提示词还是技能中的主要因素，是代理需要它的频率。加载技能会占用模型的一轮交互，因此代理在大多数轮次中都需要的内容通常应放在系统提示词中。The main factor when deciding whether to put a set of instructions within a system prompt or skill is how often the agent will need it. Loading a skill costs a model turn, so anything the agent needs on most turns generally goes in the system prompt. 

不过，这取决于你的流量分布情况，以及评估结果所显示的智能体行为。一个不错的起点是：凡是与你三分之一或更多流量相关的内容，无论是在上线前预期到的，还是在生产环境中观察到的，都应放入系统提示词中，其余内容则放入技能中。This does, however, depend on how your traffic is distributed, and what agent behavior your evals show. A good starting point is that anything relevant to a third or more of your traffic, whether anticipated before launch or observed in production, goes in the system prompt, and the rest goes in skills.

如果可以根据你已经拥有的信号（例如用户到达的页面）预测所需的技能，我们建议在首次模型调用之前通过 harness 注入该技能，并跳过用于加载技能的额外轮次。If a skill is predictable from a signal you already have, such as the page the user arrived from, we recommend injecting it from the harness before the first model call and skipping the extra turn to load the skill.

关键指令，例如安全和法律规则、品牌限制，以及过敏等重要用户事实，始终应写入系统提示中。Critical instructions, such as safety and legal rules, brand constraints, and key user facts such as allergies, always go in the system prompt.

对于商务代理而言，这意味着产品搜索存在于提示词中，因为几乎每个会话都会涉及产品搜索，而技能则承载着大量长尾功能。For commerce agents, this means product search lives in the prompt, since nearly every session touches it, and skills carry the long tail of features. 

在我们的参考实现中，购物代理的提示词包含依据、购物车和结账语义以及呈现规则，以下技能则涵盖其余部分：搜索发现、购买调研、规划目标、客户服务和记忆个性化。In our reference implementation, the shopping agent's prompt holds grounding, cart and checkout semantics, and presentation rules, and the following skills cover the rest: search-discovery, purchase-research, planning-goals, customer-care, and memory-personalization. 

商家代理也采用相同的划分方式，其技能包括绩效洞察、目录刊登、库存运营、定价促销和营销活动，每项技能对应一个运营领域。The merchant agent splits the same way, with performance-insights, catalog-listings, inventory-operations, pricing-promotions, and marketing-campaigns as its skills, one per operational domain.

工程代理工具集Engineering agent tooling

我们关于如何为智能体编写有效工具的文章涵盖了工具设计的一般原则。在商务场景中，以下两点最为重要：Our post on writing effective tools for agents covers tool design in general. Two points have mattered most in commerce:

在核心系统和逻辑之上构建智能体工具。Build agent tools on top of your core systems and logic.

一家电商公司已经拥有搜索和排序、购物车、偏好与个人资料存储、库存系统、促销与营销活动引擎、销售分析等系统；其中每个系统都封装了经过多年调优的逻辑，并能获取模型永远无法看到的信号。A commerce company already has search and ranking, a cart, a preferences and profile store, an inventory system, promotion and campaign engines, sales analytics, and more, each encoding logic tuned over years and seeing signals the model never will.

代理的工具应调用那些系统，而不是重新实现它们；工具边界就是其逻辑终止、模型判断开始的地方。The agent's tools should call those systems, not reimplement them, and the tool boundary is where their logic ends and the model's judgment takes over.

例如，当代理调用 search_products 时，结果应当已经完成排序；它的任务是决定哪些结果符合用户的目标、展示多少条结果，以及如何呈现这些结果。For example, when the agent calls search_products, the results should arrive already ranked; its job is to decide which results serve the user's goal, how many to show, and how to present them.

工具结果属于上下文。Tool results are context.

返回模型进行推理所需的字段，删除其余字段。每个搜索结果行中的图片 URL 通常就是罪魁祸首。Return the fields the model reasons with and drop the rest. Image URLs on every search row are the usual offender.

根据需要，在工具内部重新整理原始响应，包括在数据无法明确表明下一步时追加后续步骤。As needed, reshape the raw response inside the tool, including appending a next step when it isn't obvious from the data.

这对于错误场景尤其重要，因为相比错误代码，模型从指令中获益更多。例如，添加一条错误指令“查询可用性时请包含产品 ID”，而不是使用笼统的 403。This is especially relevant for error scenarios, where the model benefits from instructions instead of error codes. For example, add an error instruction "Include a product ID when querying availability," instead of a generic 403.

UI 组件是工具The UI components are tools

大多数商务代理的响应是 UI 组件，而不是散文，无论是产品轮播图、行程单、座位图还是图表。这意味着代理必须输出架构，而不是文本。Most commerce agent responses are UI components rather than prose, whether a product carousel, an itinerary, a seat map, or a chart. That means the agent has to emit a schema rather than text.

团队有时会先提示模型输出自定义标签，然后在客户端进行解析。但随着应用表面不断扩大，这种方式会逐渐失效，因为：Teams sometimes start by prompting the model to emit custom tags and parsing them on the client-side. This stops working as the surface grows, because:

• 该模型在处理你的标记语言方面的训练不如处理工具调用充分，因此随着嵌套组件的增加，可靠性会下降。仅通过提示并不能保证数据格式良好。
  The model isn’t as well trained on your markup as it is on tool calls so reliability drops as nested components get added. Well-formed data is not guaranteed just through prompting.
• 标签定义存在于系统提示中，因此每个新组件都会使上下文膨胀，而每次编辑都可能导致提示中其他部分出现回归问题。
  The tag definitions live in the system prompt, so every new component bloats context and every edit risks regressions elsewhere in the prompt.
• 过去的对话最终会以只有你的解析器才能读取的格式存储，因此加载历史记录意味着要么在客户端解析原始消息，要么以非模型 API 原生支持的格式保留第二份副本。
  Past conversations end up stored in a format only your parser can read, so loading history means either parsing raw messages on the client or keeping a second copy in a format that isn't native to the model API.

经受住考验的模式是将每个 UI 组件都做成一个工具。模型使用类型化参数调用 present_products、present_itinerary 或 present_plan_comparison；你的服务器会验证并丰富该调用，然后发出一个事件；你的客户端则负责渲染它。The pattern that has held up is to make each UI component a tool. The model calls present_products, present_itinerary, or present_plan_comparison with typed arguments; your server validates and enriches the call and emits an event; and your client renders it. 

由于这些组件是工具调用，它们已经以原生格式存在于 messages 数组中，因此重新加载旧对话时无需再次解析。下面以及参考仓库中展示了一个演示工具契约示例。As the components are tool calls, they're already in the messages array in native format, so you don’t need to re-parse when you reload an old conversation. An example presentation-tool contract is illustrated below and in the reference repo.

权衡之处在于流式传输的粒度。工具调用的每个顶层参数都会在服务器上缓冲以进行验证，因此，即使开启了流式传输，演示工具的子组件也会分步骤到达。这会影响用户感知的延迟。The tradeoff is streaming granularity. Each top-level argument of a tool call buffers on the server for validation, so the sub-components of a presentation tool arrive in steps even with streaming on. This impacts perceived latency. 

要获取 token 级流，请在工具定义中将 eager_input_streaming: true 设置为 true，这会跳过缓冲过程，同时也意味着不再具备服务器端 schema 保证。To get a token-level stream, set eager_input_streaming: true on the tool definition, which skips the buffering and with it the server-side schema guarantee.

在我们的评估中，Claude Sonnet 级别及更高版本的模型很少违反架构规范，但请为调用添加重试机制，以应对偶尔出现的违规情况。In our evals, schema violations are very rare on Claude Sonnet-class models and up, but wrap the call in a retry for the cases where one slips through.

演示工具还会为代理提供屏幕上内容的记录。当客户说“第一家酒店”或“左侧从上往下数第三个”时，布局信息就在消息数组中，位于上一次演示调用的参数里。Presentation tools also give the agent a record of what's on screen. When a customer says "the first hotel" or "the third one down on the left," the layout is in the messages array, in the arguments of the last presentation call.

要实现这一点，参数必须反映渲染后的布局，因此应按照 UI 的结构组织它们，采用有序的行和轮播，而不是使用由客户端重新排列的扁平列表。For that to work, the arguments have to reflect the rendered layout, so structure them the way the UI is structured, as ordered rows and carousels rather than a flat list the client rearranges.

延迟在商业领域至关重要，而面向消费者的界面对延迟最为敏感。然而，在智能代理界面上，我们始终看到，真正推动留存率、参与度和购物车规模等指标的，是结果的质量。Latency matters in commerce, and consumer surfaces are the least forgiving. However, on agentic surfaces, what we have consistently seen move metrics like retention, engagement, and cart size is the quality of the outcome.

与延迟方面的边际提升相比，答案是否相关以及任务是否真正完成，对这些指标而言更为关键。Whether the answer was relevant and the task actually completed was more critical to those metrics as compared to marginal latency gains. 

因此，从两个方面着手降低延迟。通过良好的工程实践，将端到端延迟降至最低；同时降低感知延迟（因为用户观看代理工作的时间会被视为进展）。So attack latency on two fronts. Minimize end-to-end latency through good engineering, and pair that with dropping perceived latency (since time spent watching an agent work reads as progress).

每位用户都有自己的延迟预算，下面的技术可以让智能体在不牺牲智能水平的情况下将延迟控制在预算之内。Every user has a latency budget, and the techniques below keep the agent inside it without spending intelligence to get there.

最小化任务完成延迟Minimizing task completion latency

任务完成延迟是各模型轮次中“最后一个 token 所需的时间”加上工具处理时间的总和。因此，你可以从三个方面着手：减少轮次、加快工具处理速度，以及加快 token 生成速度。这些方面有时会相互制约，因此应最小化的是总和，而不是其中任何单项。Task completion latency is the sum, over model turns, of time to last token plus tool processing. That gives you three levers to work towards: fewer turns, faster tools, and faster tokens. These levers sometimes compete, so the thing to minimize is the sum rather than any one of them.

更少的回合Fewer turns

查询复杂度会增加交互轮次，而且通常不受你的控制。模型智能程度和相关上下文有助于代理用更少的轮次完成任务。我们在这方面的一些关键经验包括：Query complexity adds turns, and is generally out of your control. Model intelligence and relevant context help the agent get to task completion in fewer turns. Some of our key learnings in this area include:

• 预先加载可能相关的上下文。如果用户从产品页面打开助手，或者商家从营销活动控制面板打开助手，就将该页面的数据放入会话上下文中。对话很可能与此相关，而基于上下文作答无需额外轮次。
  Load likely context up front. If the user opened the assistant from a product page, or a merchant opened it from a campaign dashboard, put that page's data in the session context. The conversation is likely about it, and answering from context costs no extra turns.
• 提升模型智能水平。更智能的模型能够让智能体更高效地规划并发出工具调用，从而减少完成任务所需的总体交互轮次。这通常足以抵消其生成令牌速度较慢的影响。如果你的查询偏复杂，或者生产环境中每项任务的交互轮次经常超过大约五轮，那么更快的模型往往才是更明智的选择。具体是哪一个取决于你的流量情况，因此应按照下文“选择模型”部分所述，通过全面测试来做出选择。
  Increase model intelligence. Smarter models can decrease overall turns in the completion of a task as the agent can more efficiently plan and issue its tool calls. That often outweighs their slower tokens. If your queries skew complex, or production shows more than about five turns per task, the faster model is frequently the smarter one. Which one that is depends on your traffic, so choose by sweep, as described under "Choosing the model" below.
• 让模型并行调用彼此独立的工具。商务用例通常需要并行执行许多操作：无论是搜索多个产品、查询许多政策文档，还是从多个销售数据源获取记录。并行工具可确保多个彼此独立的查询不会额外占用轮次。提示模型在一个轮次内调用多个工具，并在一条用户消息中以工具结果数组的形式返回结果（请参阅并行工具使用文档）。
  Have the model call independent tools in parallel. Commerce use cases often require many operations in parallel: be it searching for multiple products, querying many policy docs, or fetching records from many sources of sales data. Parallel tool ensures multiple independent queries don’t burn additional turns. Prompt the model to call many tools within a turn and return the results in one user message as an array of tool results (see the parallel tool use docs).

更快的工具Faster tools

• 优化工具自身的后端。有时，工具确实需要扇出调用——例如，一个带有“获取今日快照”查询的商户代理，会通过三个相互独立的调用分别读取销售、库存和活动状态。但我们经常看到，工具边界变成了拼接缺失后端逻辑的地方：可用性检查先调用目录服务查询 SKU，再按门店调用库存服务，还要调用履约服务获取截止时间，随后在工具自身的代码中应用替代规则和自提资格判断，最后才给出答案。这样一来，工具就承载了过多领域知识；随着规则变化，它很难保持正确，而且还承担了本应位于上游系统中的逻辑。当你发现自己正在工具中编写这类逻辑时，正确的做法是提供一个能够直接回答该问题的后端接口，然后让代理工具调用这个接口。
  Optimize the tool's own backend. Sometimes a tool genuinely fans out – a merchant agent with a  "get today's snapshot" query reads sales, inventory, and campaign status in three independent calls. But we often see the tool boundary become the place where missing backend logic gets stitched together: an availability check that calls the catalog for the SKU, the inventory service per store, and the fulfillment service for cutoffs, then applies substitution rules and pickup eligibility in the tool's own code before answering. That tool is now overloaded with domain knowledge, hard to keep correct as the rules change, and is carrying logic that should sit in an upstream system. When you find yourself writing that logic in a tool, the fix is one backend endpoint that answers the question, and calling that with an agent tool.
• 积极调度工具。工具参数会像其他 token 一样从模型中流出，因此，随着每个工具调用的参数逐步完成，执行框架可以立即执行该调用，并在模型仍在流式传输其他并行工具或内容块的同时对其进行处理。我们发现，这能将数秒的间隔缩短至几百毫秒，而 Claude Agent SDK 默认就采用这种方式。为了最大限度地降低延迟，应提示模型先发出耗时最长的调用。
  Dispatch tools eagerly. Tool arguments stream out of the model like any other tokens, so the harness can execute each tool’s call as its arguments complete and process it while the model is still streaming other, parallel tools or content blocks. We've seen this take multi-second gaps down to a few hundred milliseconds, and the Claude Agent SDK does it by default. You should prompt the model to emit its slowest call first for maximum latency gains.

感知延迟Perceived latency

感知延迟是指用户感觉屏幕开始有所响应之前所经历的时间。在面向消费者的使用场景中，这一点尤为关键，因为任何交易摩擦都会影响结账率和收入。以下两种技术无需改动模型即可缩短感知延迟：Perceived latency is the time a user feels until the screen does something. It’s especially critical in consumer-facing use cases where any transaction friction impacts checkout rates and revenue. Two techniques shorten it without touching the model:

• 在组件形成时对其进行流式传输。一次渲染后的商务响应通常包含 500–700 个输出 token，如果不使用流式传输，用户可能要面对五秒甚至更久的加载旋转图标。随着演示工具的各个参数流式传输，将其发送到客户端，并逐步渲染页面。
  Stream components as they form. A rendered commerce response is typically 500–700 output tokens, which without streaming is five or more seconds of a spinner. Send each parameter of a presentation tool to the client as it streams and render the page progressively.
• 展示处理过程。在代理收集上下文时，为每个步骤用通俗易懂的语言显示一条简短的进度信息（例如：“正在寻找水边附近的酒店”）。你可以根据工具现有的参数（例如产品搜索的查询内容）生成这条信息，也可以添加一个额外的 user_facing_message 参数工具，提示模型编写这条信息。
  Show the work. While the agent is gathering context, render a short progress line for each step in plain language (for example, "finding hotels near the water"). You can build it from the tool's existing arguments (such as the query for a product search), or add an additional user_facing_message parameter tool that prompts the model to write the line. 

提示词缓存Prompt caching

提示缓存是最有潜力大幅降低成本的方案，而电商流量非常适合采用这一方案。读取缓存输入令牌的成本仅为新输入令牌的十分之一；尽管写入缓存的成本约为新输入的 1.25 倍，但缓存前缀在第二次使用时就能收回成本。在面向客户的应用中，由于流量规模庞大，使用成本最低的默认 5 分钟缓存过期时间，您有独特的机会实现极高的缓存命中率。Prompt caching is your largest cost reduction candidate and commerce traffic is well-suited for it. Cached input token reads cost a tenth of fresh ones, and while cache-writes carry a premium of roughly 1.25x, a cached prefix pays for itself on its second use. In customer facing applications where volume is large, you have a unique opportunity to hit very high cache levels using the cheapest, default 5 minute cache expiration.  

我们见过的最佳电商部署，其缓存命中率可达到 90%–99%，这也是从一开始就应当以之为目标进行设计的范围。我们的经验表明，在约 10 万个 token 的规模下，缓存 token 的读取速度也会快约 1.5 到 2 倍，并且随着 token 数量增加，整体呈现相对线性的扩展。The best commerce deployments we've seen run at 90–99% cache hit rates, and that is the range to design for from the start. Our experience has shown cached token reads are also around 1.5 to 2x faster at ~100k tokens, with relatively linear scaling the more tokens there are. 

缓存是基于前缀的。请求会从缓存中读取内容，直到遇到与之前请求不同的第一个字节为止，因此重要的不仅是上下文中包含什么，还包括其排列顺序。可以将请求视为三个片段，按它们发生变化的频率排序：Caching is prefix-based. A request reads from cache up to the first byte that differs from a previous request, so what matters is not just what is in the context but the order it is in. Think of a request as three segments, ordered by how often they change:

• 全局：大部分系统提示和工具定义在每个会话中都相同。这是最温热的缓存，并且在大规模情况下很可能不会过期。在各轮对话和各个会话之间保持其字节级完全一致，并在其末尾设置一个缓存断点。
  Global: most of the system prompt and tool definitions, identical across every session. This is your warmest cache and, at scale, will likely not expire. Keep it byte-identical across turns and sessions and put a cache breakpoint at its end.
• 会话：每个用户的上下文和对话历史在不同会话之间有所不同，但在同一会话内保持稳定。此部分位于全局部分之后。
  Session: per-user context and conversation history, which differ across sessions but stay stable within one. This segment comes after the global one.
• 易变内容：任何会在一次会话中发生变化的信息，例如当前时间或当前页面。应将其放在请求的最末尾：要么作为最新用户消息中的带标签区块，要么对于支持在对话中途插入系统消息的模型，将其作为追加到消息数组中的 system 角色消息。我们最常见的错误，是将时间戳或当前页面放在系统提示词的顶部，这会导致缓存针对每个请求悄然失效。
  Volatile: anything that changes within a session, such as the current time or the current page. Put it at the very end of the request, either as a tagged block in the newest user turn or, on models that support mid-conversation system messages, as a system-role message appended to the messages array. The most common mistake we see is a timestamp or the current page at the top of the system prompt, which silently breaks the cache on every request.

这里有两个需要记住的实现细节。首先，应将技能作为工具结果加载，而不是附加到系统提示中。这样，技能正文就会进入对话前缀，并与其一起被缓存。There are two implementation details to remember here. First, skills should be loaded as tool results rather than appended to the system prompt. The skill body then lands in the conversation prefix and is cached along with it.

其次，在每轮中向前推进你的断点：一次请求允许使用有限数量的断点，因此请将最新的断点移动到每个用户回合的末尾。这样，每一轮都会从缓存中读取累积的历史记录，包括搜索响应等较长的工具结果。Second, roll your breakpoints forward in each turn: a request allows a limited number of breakpoints, so move the newest one to the end of each user turn. Each round then reads the accumulated history, including long tool results such as search responses, from cache.

选择模型及其配置Choosing the model and its configuration

模型规模和努力程度设置面临的是同一种权衡——智能水平与延迟和成本之间的权衡——你应该通过测量来选择二者：Model size and the effort setting are the same tradeoff – intelligence against latency and cost – and you should choose both by measurement:

1. 选择你的指标和底线。选择业务所依赖的质量指标（任务完成率、答案相关性、基于事实的准确性）、你不会低于的评估分数，以及 p50 和 p99 延迟与成本预算。
   Pick your metric and your floor. Pick the quality metrics your business runs on (task completion, answer relevance, grounded accuracy), the eval score you won't go below, and your p50 and p99 latency and cost budgets.
2. 全面测试。针对你会考虑的每个模型和每个工作强度级别，运行完整的评估套件。对于任务以分析为主的商家代理，我们建议从 Opus 开始；而对于延迟更重要的消费者代理，则建议从 Sonnet 开始。如果你有生产流量，请根据实际查询构成对结果进行加权。然后让数据做决定。有时，Opus 5 在推动购物车操作方面的提升足以抵消其与 Sonnet 之间的成本差异，但有时则不值得。
   Sweep. Run your entire eval suite across every model and effort level you'd consider. We recommend starting at Opus for merchant agents, whose tasks are analysis-heavy, and Sonnet for consumer agents, where latency weighs more. If you have production traffic, weigh the results by your real query mix. Then let the numbers decide. Sometimes Opus 5's lift on cart-driving tasks justifies the cost difference over Sonnet, and sometimes it doesn't.‍
3. 仔细阅读结果。有两点经常让团队感到意外。第一，提示词是针对特定模型调优的，因此使用某个提示词运行的横向测试，可能会逊于并非为其编写的其他模型。较小的模型通常需要明确写出当前模型能够自行推断的指令，而较大的模型则会逐字遵循指令，反而是较小的模型忽略了这些指令。针对每个候选方案的失败案例进行几轮迭代，是在排除任何方案之前成本很低的一步。第二，更智能的配置有时反而能在延迟方面胜出（最常见的是 p90 和 p99），尽管其生成 token 的速度较慢，因为它能更好地规划工具调用，并且在处理最复杂的请求时需要更少的轮次。
   Read the results carefully. Two things regularly surprise teams. The first is that a prompt is tuned to a model, so a sweep run with one prompt may underperform other models that it wasn't written for. A smaller model usually needs instructions the current model infers on its own, and a larger one will follow instructions to the letter that the smaller one was ignoring. A few rounds of iteration on each candidate's failing cases is a cheap step before ruling any of them out. The second is that a more intelligent configuration sometimes wins on latency (most commonly on p90 and p99) despite slower tokens, because it plans its tool calls better and needs fewer rounds on the most complex requests.

按每项已完成任务的成本来衡量，而不是按每次模型调用的成本来衡量，因为需要更多轮次或更常失败的廉价模型并不更便宜。当结果相近，且成本符合你的单任务经济效益和延迟要求时，应选择智能程度更高的模型。质量是推动采用率和留存率的关键，也能为未来 6 个月的构建留出空间，因为模型会变得越来越好。Measure cost per completed task rather than per model call, since a cheaper model that needs more turns, or fails more often, is not cheaper. When the result is close, and the cost fits your per-task economics and latency, choose intelligence. Quality is what drives adoption and retention, and allows for room to build for the next 6 months as models become better.

最后，我们将讨论如何让智能体顺利投入生产：记忆、安全性、评估，以及如何在整个组织中扩展这项工作。Lastly, we talk about what gets an agent through production: memory, safety, evals, and scaling the work across an organization.

跨会话保留的记忆Memory that survives the session

您与客户之间的关系和互动至关重要。记忆让代理能够从上次对话中断的地方继续，而不是每次都从零开始。一位在三月提到自己对坚果过敏的顾客，不应该到了六月还要再次说明；一位每周一都会查看同三个营销活动的商家，也不应该每次都要重新说出它们的名称。长期记忆，即那些应当跨会话保留的事实，是一个需要构建的系统，它包含三个部分：事实如何存储、如何写入，以及如何读取。The relationship and interactions you have with your customers matter. Memory is what lets an agent pick up where the last conversation left off instead of starting from nothing. A shopper who mentioned a nut allergy in March shouldn't have to repeat it in June, and a merchant who checks the same three campaigns every Monday shouldn't have to name them each time. Long-term memory, the facts that should survive across sessions, is a system you build and it has three parts: how facts are stored, how they are written, and how they are read.

存储记忆Storing memories 

记忆应属于你的系统，而不是模型。Memory belongs in your systems, not in the model. 

当用户档案规模较小且代理是唯一读取者时，扁平化 Markdown 档案是可行的。大多数生产环境中的商务代理最终都会超出这种方式，而实际可行的替代方案就是你已经在运营的数据库。事实是一条小型的类型化记录：包括一个键（例如 shoe_size、default_store、preferred_report_cadence）、一个简短值、一个类别，以及它来源的会话。有些键由你预先决定，所有用户都会拥有；其余的则由提取器发现。随着存储规模扩大，数据库仍可查询，让你能够针对特定属性构建确定性行为，并与现有的用户数据进行关联。A flat markdown profile works when profiles are small and the agent is the only reader. Most production commerce agents outgrow it, and the practical replacement is the database you already operate. A fact is a small typed record: a key (such as shoe_size, default_store, preferred_report_cadence), a short value, a category, and the session it came from. Some keys you decide up front and every user gets; the rest the extractor discovers. A database stays queryable as the store grows, lets you build deterministic behavior on specific attributes, and joins to the user data you already have.

对于面向商户的代理，应按人员而不是按账户建立记忆键。商户登录信息通常由多名操作员共享，因此每位操作员都需要拥有自己的配置文件，并且读取操作必须遵循该操作员的权限：门店经理的代理不应回忆起区域经理曾陈述的事实。For merchant-facing agents, key memory by person rather than by account. Merchant logins are often shared between operators, so each operator needs their own profile, and reads have to respect that operator's permissions: a store manager's agent should not recall a fact a district manager stated.

在电子商务领域，智能体记忆中存储着个人数据。值得记忆的信息往往也是监管最严格的信息，而不同司法管辖区之间的规则各不相同。应将记忆视为一个数据处理设计问题，而不仅仅是存储问题。实际上，这意味着四件事：In the commerce domain, agent memory holds personal data. The facts worth remembering are often the most regulated ones, and the rules between jurisdictions differ. Treat memory as a data-handling design problem and not just a storage one. In practice that means four things:

• 决定你愿意保存哪些类型的记忆。在写入路径上执行这一点，让每次保存都经过验证器，而不要仅仅依赖提示词。
  Decide which types of memories you are willing to hold. Enforce that at the write path, with a validator that every save goes through, rather than in the prompt alone.
• 为用户提供查看、更正和删除已存储内容的方式。将删除功能接入账号删除和数据请求流程。
  Give users a way to see, correct, and delete what is stored. Wire deletion into your account-deletion and data-request flows. 
• 设置一个保留期限。几年前的偏好很可能已经过时，因此保留期限有助于保持记忆事实的新鲜度。
  Set a retention period. A preference from a few years ago is likely to be outdated, so a retention period helps keep memory facts fresh.
• 内存应作为每次部署的开关。这样一来，无法承担这些义务的区域也可以在不启用内存的情况下运行。
  Memory should be a per-deployment switch. This allows regions that can't take on these obligations to run without it.

写作记忆Writing memory

异步写入记忆。在每轮对话结束时，或在长会话中每隔几轮，由单独线程或进程中的代理读取对话内容，并在存储中创建、更新或删除事实，同时随着会话的进行维护自身的工作上下文。Write memory asynchronously. At the end of each turn, or every few turns in a long session, an agent in a separate thread or process reads the conversation and creates, updates, or deletes facts in the store, keeping its own working context as the session goes on.

它不会增加对话的延迟，并且在我们内部的商务记忆评测套件中，事实回忆率提高了 13%。It adds nothing to the conversation's latency, and achieved 13% higher fact recall on our internal commerce memory eval suite.

显而易见的替代方案——让代理调用一个工具来保存事实——对于注重延迟的商务代理来说是错误的选择。每次保存都是面向用户的交互轮次中的一次工具调用；除非整个存储库都已在上下文中，否则保存前还需要先读取以进行更新或去重，而这本身又会增加一轮交互。The obvious alternative, a tool the agent calls to save a fact, is the wrong one for a latency-sensitive commerce agent. Every save is a tool call inside a user-facing turn, and unless the whole store is in context, a save needs a read first to update or dedupe, which is a round of its own.

它还会让智能体在每一轮都多做一个决策，而在我们的评估中，这种对注意力的争夺表现为遗漏记忆。It also puts one more decision in front of the agent on every turn, and in our evals that competition for attention showed up as missed memories.

将提取器单独分离出来，还可以让你对其进行精确提示。它只读取用户和助手的文本，从不读取工具结果，因此产品描述或评论不会变成关于用户的事实。它的提示明确说明哪些内容算作事实——例如明确陈述的尺寸、饮食限制、履约偏好、商家通常使用的物化视图——以及哪些不算，比如来自商品列表的任何内容或一次性的细节。Separating the extractor also lets you prompt it precisely. It reads only the user's and the assistant's text, never tool results, so a product description or a review can't become a fact about the user. Its prompt says what counts as a fact — a stated size, a dietary constraint, a fulfillment preference, a merchant’s usual materialized views — and what doesn't, such as anything from a listing or a one-off detail.

读取内存Reading memory

分三层读取内存。Read memory in three layers.

由于记忆是每个用户独有的上下文，因此全部内容都放在会话段中，位于全局缓存断点之下。Since memory is per-user context, all of it goes in the session segment, below the global cache breakpoint.

安全性：执行机制存在于测试线束中Safety: enforcement lives in the harness

提示词是安全行为的起点，但在商业场景中，安全不能只靠提示词来强制执行。这里的失败会造成财务损失，而且往往无法挽回；提示词规则只需遭遇一次注入或一个糟糕的样本，就可能被绕过。下面的每条规则都通过代码强制执行，同时应用于消费者代理和商家代理，并且只定义一次，以确保每个运行时都遵循这些规则。The prompt is where safe behavior starts, but in commerce it can't be where safety is enforced. The failures are financial and often irreversible, and a prompt rule is one injection or one bad sample away from being skipped. Every rule below is enforced in code, on both the consumer and the merchant agent, and defined once so every runtime shares it.

模型分阶段处理；由人员或政策应用The model stages; a person or a policy applies

没有任何模型工具调用会转移资金或改变业务。下单、付款、退款、价格变更和活动发布最终都会由测试框架而非模型控制操作。No model tool call moves money or changes the business. Order placement, payments, refunds, price changes, and campaign launches all end in an action the harness controls instead of the model.

在消费者端，这是结构性的问题：结账工具会渲染购物车，并提供一个用于下单的按钮，而代理调用的后端接口根本没有收费方法。On the consumer side this is structural: the checkout tool renders the cart with a button to place the order, and the backend interface the agent calls has no charge method at all.

在商户侧，每个写入工具都会生成一个带有服务器生成 ID 的暂存变更；只有通过真实界面获批的 ID，apply_change 才会成功：例如运营人员门户中的按钮、CLI 中的确认，或代理在 Managed Agents 上运行时由平台自身提供的工具批准提示。On the merchant side, every write tool produces a staged change with a server-generated ID, and apply_change succeeds only for IDs that have been approved through a real surface: a button in the operator's portal, a confirmation in the CLI, or the platform's own tool-approval prompt when the agent runs on Managed Agents. 

在应用时会根据当前限制重新检查防护措施，而不是依据变更暂存时生效的限制。无论采用何种界面，整体模式都是相同的：模型最危险的操作是提出建议，而审批则通过您的企业已针对这类变更采用的制作者—复核者流程完成。The guardrails are re-checked at apply time against current limits, not the limits in force when the change was staged. Whatever the surface, the shape is the same: the model's most dangerous action is to propose, and the approval routes through the maker-checker flow your business already uses for that kind of change.

写入和渲染仅接受服务器签发的 IDWrites and renders accept only server-issued IDs

该测试框架会为每个会话记录服务器交给模型的所有 ID，而该记录是任何写入或渲染操作唯一接受的密钥。The harness keeps a per-session record of every ID the server has handed the model, and that record is the only key any write or render will accept.

购物车只接受服务器返回给本次会话的产品 ID，商户工具只接受代理实际读取过的商品刊登 ID 和活动 ID。任何通过其他方式获取的 ID——无论是凭空编造的、用户粘贴的，还是植入评论中的——都会在后端看到它之前被拒绝。The cart accepts only product IDs the server returned to this session, and the merchant tools accept only listing and campaign IDs the agent has actually read. An ID that arrived any other way — hallucinated, pasted by a user, planted in a review — is refused before the backend sees it.

同样的规则也适用于 UI。展示工具接收 ID，由服务器自行填充产品、订单或变更记录，因此卡片只会渲染服务器自行填充的记录。The same rule covers the UI. Presentation tools take IDs, and the server fills in the product, order, or change records itself, so a card only renders records the server itself filled in.

它也涵盖委托方：商户分析子代理会读取数据，但绝不会向代理可能写入的 ID 集合中添加任何 ID。It covers delegates too: the merchant analysis subagent reads data but never adds to the set of IDs the agent may write to.

对于费用、披露信息及其他受监管内容，模型会选择要披露的产品，而服务器则从经批准的文案中提供每一个词。相同的费用字段也在商户代理的受保护列表中，因此交易双方都无法更改或改述这些内容，并且评估会逐字节检查渲染后的字符串。For fees, disclosures, and other regulated content, the model chooses which product to disclose and the server supplies every word from approved copy. The same fee fields are on the merchant agent's protected list, so neither side of the counter can change or paraphrase them, and evals check the rendered strings byte for byte.

达到上限的交易必须遵循重复请求。Capped transactions must hold to repeated requests 

大多数商业界面都会限制单个用户可购买的商品数量——出于票务分配、促销定价或欺诈控制等原因——而代理会以人类点击按钮时从未采用过的方式进行重试、改述和并行处理。Most commerce surfaces cap how many of an item one user can buy — for ticket allocations, promotional pricing, or fraud control — and an agent will retry, rephrase, and parallelize in ways a human clicking a button never did.

因此，该上限会按照写入后的行状态强制执行，所以第二次“再添加两个”无法叠加超过上限；此外，同一会话中的购物车写入操作会被串行化，因此单个回合中的并行工具调用也无法合并后超出该上限。The cap is therefore enforced on the line as it would be after the write, so a second "add two more" can't stack past it, and cart writes for one session are serialized so parallel tool calls in a single turn can't combine to exceed it.

商家的变更会以相同方式进行检查：核对价格变动幅度、折扣力度、补货规模和活动预算的上限，并检查不得修改的受保护字段列表。该规则具有普适性：应针对变更后的状态而非请求本身强制执行所有限制，并按会话串行化写入操作。Merchant changes are checked the same way against caps on price movement, discount depth, restock size, and campaign budget, plus a list of protected fields no change may touch. The rule generalizes: enforce every limit on the resulting state rather than the request, and serialize writes per session.

第三方内容已完成清理Third-party content is sanitized

在电子商务中，大部分上下文都是由并非你的人员编写的——卖家、评论者、竞争对手——因此每次后端读取的数据都是不可信输入，并且都要经过同一个清理器。In commerce most of the context is written by people who aren't you — sellers, reviewers, competitors — so every backend read is untrusted input and goes through one sanitizer.

模型看到的每条由第三方提供的工具结果，例如商品列表、评论、政策、卖家消息和存储的记忆，都会经过清理，并使用固定标签包裹在围栏中。Every tool result authored by a third party, such as listings, reviews, policies, seller messages, and stored memory,  is sanitized and wrapped in a fence with a fixed label before the model sees it. 

清理器会剥离控制字符和双向字符，移除任何仿冒围栏标记的内容，消除仿冒对话轮次或工具调用的文本，并限制大小，旨在阻止恶意列表冒充系统或填满上下文。The sanitizer strips control and bidirectional characters, removes anything that imitates the fence markers, defuses text that imitates a conversation turn or a tool call, and caps the size, which is designed to stop a hostile listing from impersonating the system or filling the context.

提示词包含了契约的另一半：围栏文本是需要进行报告的材料，绝不能据此执行任何操作。The prompt carries the other half of the contract: fenced text is material to report on, never to act on.

评测：发布一个非确定性系统Evals: shipping a non-deterministic system

从提示词的小幅改动到新增工具，任何变化都可能以难以预测的方式改变代理的行为，而你正在发布的改动往往并不是导致性能回退的那个改动。评估可以帮助你在部署之前发现这一点。我们之前关于代理评估的博客文章介绍了一般实践。本节将介绍商务代理的具体做法。Anything from a small prompt change to a new tool can change agent behavior in ways that are hard to predict, and the change you're shipping is often not the one that regresses. Evals are how you find that out before you deploy. Our earlier blog post on evals for agents covers the general practice. This section covers specifics for commerce agents.

评估快照，而不是对话Evaluate snapshots, not conversations

该模型的 API 是无状态的，因此代理的输出取决于系统提示词、工具和消息数组。这意味着，商务对话能够达到的任何状态都可以直接构造出来。因此，创建一个评估用例意味着构造测试状态，追加测试用户消息，然后让代理从该状态开始运行。The model’s API is stateless, so what the agent outputs is a function of the system prompt, the tools, and the messages array. This means any state a commerce conversation can reach can be constructed directly. So creating an eval case means constructing the test state, appending the test user message, and letting the agent run from there. 

然后评估结果：最终状态和渲染后的响应，包括最后一次写入的参数。在大多数情况下，我们不建议评估智能体为达到该结果所采取的路径，因为这类测试用例脆弱且具有限制性。Then grade the outcome: the final state and the rendered response, including the arguments of the last write. In most cases, we recommend against grading the path the agent took to get there as such test cases are brittle and restricting.

模拟用户评测中，第二个模型扮演用户，由评判模型对整段对话进行评分，这种方式并不是一种理想的测量工具。两个非确定性系统相互交互，需要更大的样本量、每次试验成本更高、更难评判，而且产生的失败也很难归因。它们适合用于发现覆盖范围上的缺口，以及对智能体进行总体感受检查，因此可以用它们来发现案例，然后将每个案例编写成快照。Simulated-user evals, in which a second model plays the user and a judge grades the whole conversation, are a poor tool for measurement. Two non-deterministic systems interacting need larger samples, cost more per trial, are harder to judge, and produce failures that are hard to attribute. They are useful for finding coverage gaps and for a general vibe check on the agent, so use them to discover cases, then write each case as a snapshot.

评估在严苛条件下的行为Evaluate for behaviors in tough conditions

大多数团队都未能正确测试注入的状态。测试用例应当编码失败发生的前置条件，而不只是任务本身。如果某种行为只有在第一轮经过多次工具调用而变得繁忙之后，或在会话早期出现矛盾之后才会显现，那么从干净状态开始的测试用例在所有配置下都会通过，无法提供有意义的数据。Most teams fail to properly test the injected state. A case should encode the preconditions of a failure, not just the task. If a behavior only emerges after a busy first turn with several tool calls, or after a contradiction earlier in the session, a case that starts from a clean state passes on every config and provides no meaningful data.

我们观察到，大多数测试套件中这类干净状态的案例占比很高，因此请确保你的一部分案例从漫长、混乱或相互矛盾的历史记录开始。We've observed most suites to be heavy on such clean-state cases, so make sure a share of yours starts from long, messy, or contradictory histories.

Cover the different types of commerce agent evals 

有效的评估需要同时测试预期行为和非预期行为。Effective evaluation requires testing both desired and undesired behaviors.

对于每个正向用例，都要编写对应的负向用例：每个“应该拒绝”都要有一个“应该执行”，每个“应该询问”都要有一个“应该直接处理”。缺少负向用例是我们在测试套件中发现的最常见问题。For every positive case, write its negative counterpart: a "should serve" for every "should refuse," a "should just do it" for every "should ask." Missing negatives are the most common gap we find in a suite.

评估以下内容：Evaluate for the following:

• 构成大部分流量的核心请求，因为此处的失败会影响大多数会话。这些请求包括简单查询、多约束请求、产品和套餐问题，以及多意图消息。对于这些问题，请检查每个价格、可用性和属性是否都能追溯到返回的数据，并确保代理在数据缺失时明确说明，而不是凭空捏造。
  Core requests that make up the bulk of your traffic, since a failure here affects most sessions. These include simple lookups, multi-constraint requests, product and plan questions, and multi-intent messages. For the questions, check that every price, availability, and attribute traces back to returned data, and that the agent says when data is missing rather than inventing it.
• 依赖上下文的请求，例如引用屏幕上显示的内容、沿用前几轮对话中的限制条件，以及对现有购物车执行写入操作的请求。记忆评估也属于这一类。检查是否提取并检索了记忆，以及记忆是否改变了答案。
  Context-dependent requests, such as references to what is on screen, constraints carried over from earlier turns, and writes against an existing cart. Evaluating memory falls into this bucket as well. Check that memories were extracted, retrieved, and changed the answer.
• 安全性和品牌案例，其中一次失败就会造成金钱或信任方面的损失。这些案例包括注入尝试、试图读取其他用户的数据，以及受监管的语言（此类语言会逐字节进行检查）。将注入分为两种情况：用户编写的注入，即指令来自用户自己的消息；以及数据平面注入，即注入内容被植入产品名称、评论或通过工具结果传入的网页片段中。
  Safety and brand cases, where a failure costs money or trust. These include attempted injection, attempts to read another user's data, and regulated language, which is checked byte for byte. Split injection into two cases: user-authored injection, where the directive comes from the user's own message, and data-plane injection, where it is planted in product names, reviews, or web snippets that arrive via tool results.
• 进行界面评估，以确保渲染了正确的组件、遵守项目数量上限，并且面向用户的文本中不包含内部标识符。同时也要测试超时和空结果情况。
  Interface evaluations, to ensure the right component is rendered, item caps are respected, and there are no internal identifiers in user-facing text. Test for timeouts and empty results too.
• 同时涉及多个能力的请求。一名运营人员询问：“如果我把这个商品降价 15%，库存够不够满足需求？”这同时是一个定价问题和库存问题。正确的回答应给出降价方案，并附上库存预测；错误的回答只处理其中一项而忽略另一项。按单项能力编写的评测无法发现这一点，因为每项评测只评估问题的一半。请为那些需要将两个相邻能力结合起来的请求编写案例，并对答案的两部分都进行评分。
  Requests that belong to multiple capabilities at once. An operator asks "if I mark this down 15%, do I have enough stock to cover the demand?" That is a pricing question and an inventory question together. The right answer stages the markdown with a stock projection attached; the wrong answers do one and skip the other. Evals written per capability won't catch this, because each grades only its own half. Write cases for the requests that need two neighboring capabilities together, and grade both halves of the answer.

Write evals with SMEs and use real incidents

与亲眼见证故障的领域专家合作，例如产品、法务、商户运营、客户服务和品类管理团队的成员，共同设计测试用例。真实故障最适合用来构建评测，而每个用户流程准备 50–100 个评测案例是一个不错的起点。Partner with the subject-matter experts who see the failures firsthand, such as team members in Product, Legal, Merchant Ops, Customer Care, and Category Management, to design test cases. Real failures make the best evals, and 50-100 eval cases per user flow is a good starting point. 

确保包含如上文所述的各种案例。生产环境中的转录记录是发掘新案例（尤其是棘手案例）的绝佳来源。编码代理擅长生成更多案例和对抗性变体。参考仓库包含一个 Claude Code 插件，其中集成了一个按照我们推荐的方法构建的评估编写技能。Make sure to have a variety of cases, as outlined above. Production transcripts are a great stream for sourcing new cases, especially the tricky ones. Coding agents are good at generating additional cases and adversarial variants. The reference repository includes a Claude Code plugin with an eval-authoring skill built with our recommended approach.

在大型组织中交付Shipping with a large organization

在一家商业企业中，该代理由许多工程团队共同构建。搜索、结账、定价、营销技术、客户服务和商品目录平台分别负责该代理所依赖的系统，各自按照自己的节奏发布，并且都希望添加或更改工具、技能或提示规则。In a commerce enterprise the agent is built by many engineering teams. Search, checkout, pricing, marketing tech, customer care, and the catalog platform each own systems the agent depends on, each ships on its own cadence, and each will want to add or change a tool, a skill, or a prompt rule. 

与服务不同，代理没有严格的模块边界来保护其他模块：定价团队所做的更改会与结账共享同一个上下文窗口。Unlike a service, an agent has no strict module boundary protecting the others: a change made by the pricing team shares a context window with checkout.

一个看似诱人的解决方案是将系统拆分成许多子代理，每个业务单元对应一个子代理。正如第 1 部分所述，出于质量方面的考虑，我们不建议这样做。相反，我们将介绍如何降低多团队协作风险：The tempting fix is to break the system into many subagents, one per business unit. As discussed in Part 1, we recommend against it for quality reasons. Instead, we outline the process for de-risking multi-team collaboration:

• 所有权随系统划分。每项技能和工具都由一个团队单独负责。例如，定价团队负责促销工具和定价技能，客户服务团队负责订单与退货工具以及客户服务技能。共享提示词的通用部分由平台层面的单一负责人负责，领域特定部分则由相应领域负责人负责。
  Ownership follows the systems. Every skill and tool has a single owner team. For example, pricing owns the promotion tools and the pricing skill, care owns the order and returns tools and the customer-care skill. The shared prompt has a single platform-level owner for the common parts and domain owner for the domain-specific section.
• 一项变更会随附其测试用例，并由 CI 运行为该变更选定的一组用例。贡献某项技能的团队也应贡献其测试用例，包括针对相邻技能的负面用例和边界用例。每次拉取请求都运行完整测试套件，速度太慢、成本太高，无法长期维持，因此应据此构建一个 CI 测试集。该测试集应包含一组核心用例，其中包括流量最高的请求以及所有安全用例。在此基础上，再运行变更所涉及内容对应的用例。对于一项技能，这意味着运行其自身的用例以及相邻技能的边界用例。对于一个工具，则是运行所有调用该工具的用例。对于共享提示词，则是运行完整的评估套件，因为所有内容都会读取系统提示词。我们建议在数次试验中对通过率设置门槛，同时关注缓存命中率和每轮成本。每晚运行完整测试套件，并在每次发布前运行一次，也是很好的实践。跨团队回归问题会在这些运行中被捕获。
  A change ships with its cases and CI runs a set chosen for it. A team contributing a skill also contributes its cases, including the negative cases and the boundary cases against neighboring skills. Running the full suite on every pull request is too slow and too expensive to survive, so build a CI set from it instead. That set will consist of a core set of cases with the highest-traffic requests and every safety case. On top of that, run the cases for whatever the change touched. For a skill, that means its own cases and its neighbors' boundary cases. For a tool, it is every case that calls it. For the shared prompt, it is the full eval suite since everything reads the system prompt. We recommend gating the pass rate over a few trials, and on cache hit rate and cost per turn. It is also a good practice to run the full suite nightly and before every release. Cross-team regressions are caught in these runs.
• 该智能体也应纳入发布日历。它是一个部署单元，因此有问题的更改会同时影响所有用户。首先将提示词和技能更改逐步发布到金丝雀用户群，保留一个无需部署即可关闭单项技能的开关，并像冻结其他系统一样，在业务高峰期前冻结该智能体。
  The agent should also be inside the release calendar. It's one deployment unit, so a bad change reaches every user at once. Roll prompt and skill changes to a canary cohort first, keep a switch that turns off one skill without a deploy, and freeze the agent ahead of peak periods the same way you freeze other systems.

关于这一安排中人的一方，请参阅《构建高效的人类—代理团队》。For the human side of this arrangement, see Building effective human-agent teams.

展望未来Looking ahead

这篇文章所描述的大部分内容都与模型无关。工具调用的是你已经在运行的系统，技能编码的是你已经遵循的流程，评估是以测试形式编写的产品需求文档，而线束则强制执行你对任何客户都会执行的策略。模型会不断改进；当更好的模型发布时，我们所描述的架构只需通过配置变更并进行一轮评估即可采用它。其他一切都会继续正常运行。Most of what this post describes is not about the model. The tools call systems you already run, the skills encode procedures you already follow, the evals are your product requirements doc written as tests, and the harness enforces policy you would enforce for any client. Models will keep improving, and when a better one ships, the architecture we describe adopts it as a config change with an eval sweep. Everything else keeps working.

同样重要的是，要思考产品界面的路线图。架构的生命周期会长于聊天面板。同一个智能体可以通过语音工作，也可以在用户提出请求之前，主动针对票价下降采取行动。对于已经具备评测和工具的团队来说，这些属于表现层项目。再往后，你的店面流量中会有一部分来自代表用户购物的智能体。让你自己的智能体保持在边界之内的同一套来源追踪、暂存和审批规则，也将使你能够安全地向这些智能体开放工具。It is also important to think about your roadmap for product surfaces. The architecture will outlast the chat panel. The same agent can work over voice, and it can proactively act on a fare drop before the user asks. For a team that already has the evals and the tools, those are presentation-layer projects. Further out, some of the traffic to your storefront will come from agents that shop on behalf of users. The same provenance, staging, and approval rules that keep your own agent in bounds are what will let you open your tools to those agents safely.

商业一直以来都在奖励那些能让购买流程尽可能顺畅的做法。代理能让这一过程变得更加轻松。查看完整的参考实现，其中包含消费者代理和商家代理，以及适用于零售、旅游、电信和娱乐领域的可运行示例。Commerce has always rewarded making the buying process as smooth as possible. Agents make that a lot easier. Check out the complete reference implementation, with both the consumer and the merchant agent and runnable examples for retail, travel, telecom, and entertainment.

致谢Acknowledgements

Written by Matthew Koen and Ali Shazal. Special thanks to Michael Segner, Rodrigo Olivares, Amandeep Khurana, Aiza Usman, John Lopus and others for their contributions.