A guide to the anatomy of effective commerce agents高效商务智能体架构指南

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.这些智能体已投入生产，企业客户在使用后发现，购物车规模有所扩大，卖家运营效率也得到了提升。它们都采用了一种简单的架构：Claude 处于一个智能体循环中，配备了一系列技能、工具和强大的评估套件。

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.每次切换到子智能体都是一次有损状态的操作，这往往会影响子智能体的响应质量，进而影响整体表现。此外，每次切换都会消耗数倍的 token，并增加数秒的延迟。

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.当然，这取决于您的流量分布以及评估显示的智能体行为。一个好的起点是：任何与三分之一或更多流量相关的内容（无论是在发布前预测的还是在生产中观察到的）都放入系统提示词，其余内容则放入技能中。

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. 智能体的工具应该调用这些系统，而不是重新实现它们。工具边界是现有逻辑结束、模型判断开始的地方。

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.例如，当智能体调用 search_products 时，结果应该已经是排好序的；它的工作是决定哪些结果符合用户目标、显示多少个以及如何呈现它们。

Tool results are context. 工具结果就是上下文。

Return the fields the model reasons with and drop the rest. Image URLs on every search row are the usual offender. 仅返回模型推理所需的字段，舍弃其余部分。搜索结果每一行都带图片 URL 通常是常见的问题所在。

As needed, reshape the raw response inside the tool, including appending a next step when it isn't obvious from the data. 根据需要，在工具内部重塑原始响应，包括在数据中不明显时追加下一步操作。

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.这在错误场景中尤为重要，模型从指令中获益比从错误代码中获益更多。例如，添加错误指令“查询可用性时请包含产品 ID”，而不是返回通用的 403。

The UI components are toolsUI 组件即工具

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.大多数商务智能体的响应是 UI 组件而非纯文本，无论是产品轮播图、行程单、座位图还是图表。这意味着智能体必须输出模式（schema）而非文本。

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.标签定义位于系统提示词中，因此每个新组件都会增加上下文负担，且每次编辑都有可能导致提示词中其他部分的回归问题。
• 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.过去的对话最终以只有您的解析器能读取的格式存储，因此加载历史记录意味着要么在客户端解析原始消息，要么保留一份模型 API 不支持的格式的副本。

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. 行之有效的模式是将每个 UI 组件作为一个工具。模型使用类型化参数调用 present_products、present_itinerary 或 present_plan_comparison；您的服务器验证并丰富该调用并发出事件；然后由您的客户端进行渲染。

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. 权衡在于流式传输的粒度。工具调用的每个顶级参数都会在服务器上缓冲以进行验证，因此即使开启了流式传输，演示工具的子组件也会分步到达。这会影响感知延迟。

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. 要获得 token 级别的流，请在工具定义中设置 eager_input_streaming: true，这将跳过缓冲，但同时也放弃了服务器端的模式保证。

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.在我们的评估中，Claude Sonnet 级别及以上的模型出现模式违规的情况非常罕见，但对于偶尔出现的违规，请将调用封装在重试逻辑中。

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. 演示工具还为智能体提供了屏幕内容的记录。当客户说“第一个酒店”或“左边数第三个”时，布局信息就在消息数组中，位于最后一次演示调用的参数里。

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.为了使其生效，参数必须反映渲染后的布局，因此请按照 UI 的结构（如有序行和轮播图）来组织它们，而不是使用客户端重排的平铺列表。

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最小化任务完成延迟

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.任务完成延迟是模型轮次中“到达最后一个 token 的时间”加上“工具处理时间”的总和。这为您提供了三个杠杆：更少的轮次、更快的工具和更快的 token 生成。这些杠杆有时会相互竞争，因此要最小化的是总和，而不是其中任何一个。

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.提高模型智能。更聪明的模型可以减少完成任务所需的总轮次，因为智能体能更有效地规划和发出工具调用。这通常超过了它们在 token 生成速度上的不足。如果您的查询偏向复杂，或者生产环境显示每个任务超过五轮，那么更快的模型往往就是更聪明的模型。具体选择哪个取决于您的流量，因此请按下方“选择模型”所述进行扫描测试。
• 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更快的工具

• 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.优化工具自身的后端。有时工具确实会发散——例如，商家智能体查询“今日快照”时，会在三个独立调用中读取销售、库存和活动状态。但我们经常看到工具边界变成了缺失后端逻辑的拼凑地：可用性检查调用目录获取 SKU、查询各门店库存服务、查询履行服务的截止时间，然后在工具代码中应用替换规则和提货资格后再回答。该工具现在被领域知识过载，规则变更时难以保持正确，且承载了本应在后端系统中的逻辑。当您发现自己在工具中编写此类逻辑时，修复方法是创建一个能回答该问题的后端端点，并使用智能体工具调用它。
• 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.急切地调度工具。工具参数像其他 token 一样从模型中流出，因此框架可以在工具参数完成时执行该调用，并在模型仍在流式传输其他并行工具或内容块时对其进行处理。我们已经看到这能将数秒的间隙缩短到几百毫秒，Claude Agent SDK 默认即执行此操作。为了获得最大的延迟增益，您应该提示模型优先发出其最慢的调用。

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:感知延迟是用户感觉屏幕发生变化所需的时间。这在面向消费者的用例中尤为关键，任何交易摩擦都会影响结账率和收入。以下两种技术可以在不触及模型的情况下缩短它：

• 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.组件形成时即流式传输。渲染后的商务响应通常为 500–700 个输出 token，如果不使用流式传输，加载图标会持续五秒或更久。在演示工具的每个参数流式传输时将其发送到客户端，并渐进式地渲染页面。
• 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. 展示工作进度。当智能体正在收集上下文时，为每一步渲染一行简短的、通俗易懂的进度提示（例如“正在查找水边的酒店”）。您可以根据工具现有的参数（如产品搜索查询）构建它，或者添加一个额外的 user_facing_message 参数工具，提示模型编写该行文字。

Prompt caching提示词缓存（Prompt Caching）

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.  提示词缓存是您降低成本的最佳候选方案，商务流量非常适合它。缓存的输入 token 读取成本仅为新请求的十分之一，虽然缓存写入有约 1.25 倍的溢价，但缓存的前缀在第二次使用时即可回本。在交易量大的面向客户的应用中，您有机会通过最便宜的 5 分钟默认缓存过期时间实现极高的缓存命中率。

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. 我们见过的最佳商务部署运行在 90–99% 的缓存命中率，这是从一开始就应该设计的范围。我们的经验表明，在约 10 万 token 时，缓存 token 读取速度也快约 1.5 到 2 倍，且随着 token 数量增加呈相对线性的扩展。

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.会话：每个用户的上下文和对话历史，它们在会话间不同，但在一个会话内保持稳定。该部分位于全局部分之后。
• 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:模型大小和努力程度（effort）设置是相同的权衡——智能与延迟和成本之间的权衡——您应该通过测量来选择两者：

1. 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.选择您的指标和底线。选择您的业务所依赖的质量指标（任务完成率、答案相关性、基础准确性）、您不会低于的评估分数，以及您的 p50 和 p99 延迟及成本预算。
2. 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.‍扫描测试。在您考虑的每个模型和努力级别上运行整个评估套件。我们建议商家智能体（任务分析繁重）从 Opus 开始，消费者智能体（延迟权重更高）从 Sonnet 开始。如果您有生产流量，请按您的真实查询组合对结果进行加权。然后让数据做决定。有时 Opus 在购物车驱动任务上的提升证明了其成本差异，有时则不然。
3. 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.仔细阅读结果。两件事经常让团队感到惊讶。首先，提示词是针对模型进行优化的，因此使用一个提示词进行的扫描测试可能会使未针对其编写的其他模型表现不佳。较小的模型通常需要当前模型能自行推断的指令，而较大的模型会严格执行较小模型忽略的指令。在淘汰任何候选者之前，对每个候选者的失败案例进行几轮迭代是一个低成本的步骤。其次，更智能的配置有时会在延迟（通常在 p90 和 p99）上胜出，尽管 token 生成较慢，因为它能更好地规划工具调用，并且在最复杂的请求上需要的轮次更少。

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.测量每个已完成任务的成本，而不是每个模型调用的成本，因为需要更多轮次或失败率更高的廉价模型并不便宜。当结果接近，且成本符合您的单任务经济效益和延迟要求时，请选择智能。质量是驱动采用和留存的关键，也为您在未来 6 个月内随着模型变得更好而进行构建留出了空间。

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. 记忆属于您的系统，而不是模型。

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.当个人资料很小且智能体是唯一读者时，简单的 Markdown 配置文件可以使用。大多数生产级商务智能体最终会超越这种方式，实际的替代方案是您已经运营的数据库。事实是一个小的类型化记录：键（例如 shoe_size, default_store, preferred_report_cadence）、简短的值、类别以及它来源的会话。有些键是您预先确定的，每个用户都会有；其余的由提取器发现。随着存储增长，数据库保持可查询性，让您能在特定属性上构建确定性行为，并与您已有的用户数据关联。

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. 异步写入内存。在每一轮结束时，或在长会话的每几轮后，一个在独立线程或进程中的智能体读取对话并创建、更新或删除存储中的事实，同时在会话进行时保持其自身的工作上下文。

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

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. 在消费者端，这是结构性的：结账工具渲染带有下单按钮的购物车，而智能体调用的后端接口根本没有收费方法。

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. 在商家端，每个写入工具都会产生一个带有服务器生成 ID 的暂存变更，且 apply_change 仅对通过真实界面（操作员门户中的按钮、CLI 中的确认，或智能体在托管智能体上运行时平台自身的工具批准提示）批准的 ID 成功。

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.护栏在应用时会针对当前限制进行重新检查，而不是针对变更暂存时的限制。无论界面如何，形式都是一样的：模型最危险的动作是提议，批准路由通过您的业务已用于此类变更的“制作者-检查者”（maker-checker）流程。

Writes 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 的会话记录，该记录是任何写入或渲染将接受的唯一键。

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.购物车仅接受服务器返回给此会话的产品 ID，商家工具仅接受智能体实际读取过的列表和活动 ID。以任何其他方式到达的 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.相同的规则适用于 UI。演示工具获取 ID，服务器自行填充产品、订单或变更记录，因此卡片仅渲染服务器自身填充的记录。

It covers delegates too: the merchant analysis subagent reads data but never adds to the set of IDs the agent may write to.它也涵盖了委托：商家分析子智能体读取数据，但从不添加到智能体可能写入的 ID 集中。

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评估快照，而非对话

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. 模型的 API 是无状态的，因此智能体的输出是系统提示词、工具和消息数组的函数。这意味着商业对话可能达到的任何状态都可以直接构建。因此，创建一个评估案例意味着构建测试状态，附加测试用户消息，并让智能体从该状态开始运行。

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.界面评估，以确保渲染正确的组件、遵守项目上限，且面向用户的文本中不包含内部标识符。同时测试超时和空结果的情况。
• 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.同时属于多种能力的请求。例如操作员询问：“如果我将此商品降价 15%，库存是否足以满足需求？”这是一个定价问题和库存问题的结合。正确的回答应在提供库存预测的同时设定降价；错误的回答则只处理其中一半而忽略另一半。按单一能力编写的评估无法捕捉到这一点，因为每项评估只对自身的一半负责。请为需要同时调用两个相邻能力的请求编写案例，并对回答的两个部分进行评分。

Write evals with SMEs and use real incidents与中小企业（SME）合作编写评估并使用真实事故案例

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. 与在一线发现故障的主题专家（SME）合作设计测试案例，例如来自产品、法务、商家运营、客户关怀和品类管理团队的成员。真实的故障是最好的评估素材，每个用户流程 50-100 个评估案例是一个很好的起点。

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.确保案例多样化，如上所述。生产环境的转录记录是获取新案例（尤其是棘手案例）的绝佳来源。编码智能体擅长生成额外的案例和对抗性变体。参考存储库中包含一个 Claude Code 插件，该插件具备我们推荐的评估编写技能。

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.与普通服务不同，智能体没有严格的模块边界来保护其他部分：定价团队所做的更改会与结账功能共享上下文窗口。

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.权责归属系统。每项技能和工具都有一个单一的负责人团队。例如，定价团队负责促销工具和定价技能，客户关怀团队负责订单和退货工具以及客户关怀技能。共享提示词有一个平台级的负责人负责通用部分，领域负责人负责领域特定部分。
• 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.变更应随其评估案例一同发布，CI 运行选定的测试集。贡献技能的团队也需贡献其案例，包括负面案例和针对相邻技能的边界案例。在每次拉取请求（PR）上运行完整套件既缓慢又昂贵，因此应改为构建一个 CI 专用测试集。该测试集应包含核心的高流量请求案例及所有安全案例。此外，运行与变更相关的案例。对于技能，这意味着运行其自身案例及相邻技能的边界案例；对于工具，则是运行所有调用它的案例；对于共享提示词，由于所有部分都会读取系统提示词，因此需运行完整评估套件。我们建议通过多次试验来设定通过率门槛，并关注缓存命中率和单次转轮成本。此外，每日及每次发布前运行完整套件也是一种良好的做法。跨团队的回归问题会在这些运行中被捕获。
• 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.由 Matthew Koen 和 Ali Shazal 编写。特别感谢 Michael Segner、Rodrigo Olivares、Amandeep Khurana、Aiza Usman、John Lopus 等人的贡献。