Anthropic's full playbook for building commerce agents

Hi, I'm Shii-chan! Today I found a really substantial technical article for anyone building commerce agents, so let me walk you through it!

Claude Blog claude.com

What was announced?

This is a technical guide on Claude Blog, written by Anthropic engineers Ali Shazal and Matthew Koen, titled "A guide to the anatomy of effective commerce agents." It lays out architecture patterns, performance optimization, and safety practices for building commerce agents with Claude, covering both consumer-facing and merchant-facing agents across retail, travel, telecom, and entertainment. It's the engineering deep-dive companion to "Building commerce agents with Claude," published the same day.

Why it matters

Commerce agents often get handed operations where real money moves, like placing orders or processing payments. That raises the stakes on design decisions in a way most agents don't face. This article compiles what Anthropic learned building commerce agents, organized around architecture, performance, safety, evaluation, and team operations — giving anyone building in this space a practical checklist to work from.

What changes

Adopting the ideas in this guide shapes several design decisions:

• Using one model plus a long tail of skills instead of splitting work across subagents avoids state-loss during handoffs
• Splitting instructions between the system prompt and skills based on frequency (anything touching a third or more of traffic goes in the system prompt) avoids wasting context
• Treating UI components as tools rather than free-form markup keeps data well-formed and conversation history clean

Dive Deep

The performance and safety sections are especially actionable.

Performance optimization

• Load predictable context, like user page context, upfront
• Run independent operations as parallel tool calls
• Start dispatching tool execution as arguments stream in, ahead of the full response
• Design prompt caching across three layers — global (system prompt, tool definitions), session (user history), and volatile (timestamps and similar) — which can hit 90-99% cache-hit rates and cut cached-token cost to a tenth of a fresh read
• Judge model choice by cost per completed task, not cost per call

Safety practices

• Never let a single model tool call move money or change business logic — enforce that in the harness (server-side), not the model
• Only accept IDs the server issued within the current session; reject hallucinated IDs, user-pasted IDs, or IDs planted in data
• Enforce spending limits against resulting state rather than individual requests, and serialize writes per session so parallel calls can't slip past the cap
• Sanitize any third-party text, like reviews or product listings, by stripping control characters and fence markers and capping size before it reaches the model

The guide also shares concrete numbers on memory: storing typed records in an existing database instead of markdown profiles, and writing memory asynchronously after the conversation ends, improved fact-recall accuracy on their internal eval by 13% while removing the latency hit. On evaluation, it describes building test states directly from snapshots and always pairing every acceptance case with a matching refusal case.

Wrap-up

• Commerce agents work best as one model plus skills, not split subagents
• Money-moving operations must be enforced in the harness, not left to model judgment
• A three-layer prompt cache design can reach 90-99% hit rates
• Memory works best as typed records written asynchronously, improving both accuracy and speed
• Pairing every positive eval case with a negative one catches mistakes before they ship

If you're seriously designing or building a commerce agent that touches carts and checkout, this one is worth bringing straight back to your own codebase!