# Open-Source Blueprint for Commerce Agents: A New Era in Agentic Shopping Experiences
## The Blueprint That Matches Industry Practice
A new open-source reference architecture has been released that mirrors the exact scaffolding most engineering teams build from scratch when constructing shopping assistants and commerce agents. The repository provides both a **shopping agent** and a **merchant agent**, each implemented across four verticals: retail, travel, telecom, and entertainment. It arrives with two detailed documentation pieces — a product overview and an engineering deep-dive on how effective commerce agents are structured.
The project is fully deployable. It is licensed under Apache 2.0, runs locally on Python 3.11 and Node 22, and requires only an API key to get started. Critically, the runtime is compatible with any standard client library, meaning the same codebase can be deployed on the primary Claude API, Amazon Bedrock, Microsoft Foundry, or Google Cloud Vertex AI without modification.
## Understanding the Two Core Agents
### The Shopping Agent
This agent operates within a merchant’s own application. Its responsibilities span the full customer journey: searching the product catalog, handling requests involving multiple items, comparing options side by side, building shopping carts, and answering questions about orders and returns — all within a single continuous conversation.
It is built around five core capabilities:
– **Search and discovery** — locating products based on natural-language queries
– **Purchase research** — comparing features, prices, and reviews across items
– **Goal planning** — helping users build coherent multi-item selections
– **Customer care** — handling post-purchase questions and return requests
– **Memory and personalization** — retaining user preferences across sessions
A deployment of this agent requires implementing a storefront backend that connects to the merchant’s catalog, cart, order, and policy systems.
### The Merchant Agent
Designed to support store staff, this agent assists with internal operations rather than customer-facing tasks. Its five capabilities include:
– **Performance insights** — sales data and metrics analysis
– **Catalog listings** — managing product entries and descriptions
– **Inventory operations** — stock alerts and supply chain updates
– **Pricing and promotions** — recommended pricing and campaign structures
– **Marketing campaigns** — drafting and organizing promotional content
This agent connects to a separate merchant backend focused on business operations rather than customer transactions.
## Running the Agents: Three Modes from One Definition
Both agents share a single unified definition of prompts, skill instructions, tool contracts, and approval gates, yet they can operate in three distinct execution modes: the Messages API, the Agent SDK, and Claude Managed Agents (currently in beta). Additionally, a CLI plugin is included that can either scaffold a brand-new agent with the `/scaffold-commerce-agent` command or audit an existing agent configuration with the `/review-commerce-agent` command.
## Skills Over Subagents: An Architectural Shift
One of the most transferable insights in this blueprint is the explicit preference for **skills over subagents**. Traditional agent designs route messages between domain-specific subagents, but every handoff between subagents discards context. The orchestrator must reconstruct cart state, user preferences, and conversation history each time, which multiplies token consumption and introduces latency — often adding several seconds per transition.
Domain boundaries also blur in practice. A returns flow simultaneously requires order history, the current cart, and the product catalog. By keeping everything in a single agent context and loading domain instructions as skills, the architecture avoids this state-loss problem entirely.
Across multiple enterprise deployments, the single-agent-with-skills pattern outperformed both the monolithic prompt approach and the subagent architecture in response quality, while also delivering lower costs and faster response times. Subagents are not discarded entirely — they remain valuable for isolated, self-contained tasks such as deep research that does not require access to session state.
The decision of what goes into the system prompt versus what lives in a skill is guided by traffic frequency. Roughly one-third or more of user interactions touch the content in the system prompt, which is where safety rules, brand constraints, and critical user facts reside. The remaining content is distributed across skills.
## Components, Not Prose: The Rendering Architecture
Most commerce responses are structured data — product carousels, comparison tables, itinerary summaries — not free-form paragraphs. The blueprint treats each of these as a **tool call** with typed arguments, rather than asking the model to emit custom markup tags. Tools like `present_products`, `present_itinerary`, and `present_plan_comparison` receive server-validated arguments that the client renders directly.
Because these calls appear natively in the message history, reloading a conversation does not require any custom parser — the agent can reference “the first hotel” by resolving the earlier presentation call directly. For token-level streaming, an `eager_input_streaming` option bypasses server-side buffering, delivering schema guarantees while maintaining responsiveness.
## Latency, Caching, and Enforcement
### Perceived vs. End-to-End Latency
A rendered commerce response typically spans 500–700 output tokens. Without streaming, this translates to roughly five seconds of a static spinner. The blueprint distinguishes between total latency and perceived latency by streaming components as they form and rendering plain-language progress indicators while the model continues processing. Eager tool dispatch — executing each tool call as its streaming arguments finish — reportedly collapses multi-second gaps to just a few hundred milliseconds.
### Prefix-Based Prompt Caching
Since prompt caching works on prefix matching, the order of content in the request matters enormously. The recommended structure is global → session → volatile: a global timestamp placed at the top of the prompt invalidates the cache on every request, destroying hit rates. Storing timestamps at the bottom preserves prefixes and drives cache hit rates of 90–99% in production deployments. Cached input reads cost roughly one-tenth the price of fresh tokens, and the cache write premium of approximately 1.25x means a cached prefix pays for itself after its second use.
Memory extraction runs asynchronously in a separate process, and measurements showed 13% better fact recall compared to saving facts through an in-turn tool call that competes with the model’s active reasoning.
### Harness-Based Guardrails
Enforcement is handled by the harness, not the prompt. The most dangerous action a model can attempt is proposing — order placement, payments, refunds, price changes, and campaign launches all terminate in an action controlled by the backend, routed through a maker-checker flow that mirrors the business’s existing approval processes. Order placement tools render the cart with a button for a human to actually submit; the backend interface itself has no charge method exposed to the model. All write operations pass through provenance gates that track every server-handed ID, with only those IDs accepted by any subsequent write request.
These safeguards mean the model can propose freely, but no destructive action occurs without explicit backend validation against the current state of the system.
—
## FAQ
**Q: What programming languages does the blueprint support?**
A: The reference implementation runs on Python 3.11 and Node.js 22, but the architecture is runtime-agnostic. The skills, prompts, and tool contracts are defined declaratively and work with any compliant API client.
**Q: Can I use this blueprint with models other than Claude?**
A: Yes. The same codebase accepts any `anthropic`-compatible client and is designed to operate across Amazon Bedrock, Microsoft Foundry, and Google Cloud Vertex AI, making it cloud-provider agnostic.
**Q: Why does the blueprint avoid subagents?**
A: Subagent handoffs discard shared state like cart contents, user preferences, and conversation history. Reconstructing that state at every transition increases token usage and adds seconds of latency. Skills within a single agent context achieve domain modularity without this overhead.
**Q: What is the difference between end-to-end latency and perceived latency?**
A: End-to-end latency measures the full time from request to complete response. Perceived latency measures how quickly the user sees meaningful content on screen. The blueprint optimizes for perceived latency by streaming components as they are generated and using eager tool dispatch to minimize gaps between page elements.
**Q: How does prompt caching actually work in this context?**
A: Prompt caching is prefix-based, meaning identical leading content across requests is cached server-side and read at a fraction of the cost of fresh tokens. The blueprint orders request content as global (static) → session (stable per user) → volatile (time-sensitive and user-specific), ensuring the longest stable prefixes are cached most effectively.
**Q: What happens if the model tries to take an unauthorized action?**
A: The harness intercepts all write operations through gate validation. The model can still propose actions like placing an order or changing a price, but the backend will not execute them without passing through the established approval workflow and state validation checks.
**Q: Is this blueprint suitable for production use?**
A: Yes. It is released under the Apache 2.0 license and is designed as a production-ready reference. Teams have already deployed variants of this architecture across retail, travel, telecom, and entertainment verticals.
**Q: How are user facts like preferences and allergies handled?**
A: Critical user facts are always stored in the system prompt rather than in skills, ensuring they are loaded for every interaction regardless of how frequently they are invoked.
—
## Conclusion
This open-source blueprint represents a significant step toward replacing bespoke agent scaffolding with a reusable, production-tested foundation. By codifying architectural decisions — skills over subagents, prefix-optimized caching, harness-based enforcement, and component-level streaming — it gives engineering teams a starting point that reflects what has been learned across enterprise deployments rather than requiring each team to rediscover the same trade-offs independently. The compatibility with multiple cloud providers and API runtimes further lowers the barrier to adoption, making it a practical option for teams at any stage of their agent-building journey.
Thank you for reading
