Passa al contenuto principale
Intermedio

Blueprint per agenti di commercio (riferimento Anthropic)

What you'll learn
  • Capire la divisione in due agenti (shopping vs merchant) e perché Anthropic NON ha usato un intent router né subagent per dominio
  • Imparare il guardrail delle scritture in staging: come nessuna chiamata a strumento del modello sposta denaro o modifica il negozio, e ogni scrittura termina su una superficie approvata da un umano
  • Vedere i tre percorsi di runtime (Messages API, Agent SDK, Managed Agents) e come LO STESSO codice core si innesta in tutti e tre
  • Rubare tre pattern trasferibili per qualsiasi agente che tocchi un sistema aziendale reale: ID emessi dal server, testo di terzi racchiuso in recinti e separazione prompt-vs-skill

Il 2 settembre 2026 Anthropic ha pubblicato anthropics/commerce-agents, un blueprint di riferimento Apache 2.0 per costruire agenti di shopping e di merchant su Claude. Include due agenti funzionanti, quattro esempi verticali (retail, viaggi, telecom, intrattenimento) e, soprattutto, una serie di pattern di guardrail implementati nel codice, non nei prompt. Anthropic dichiara che il repo è un'implementazione di riferimento che non manterrà come prodotto e che non accetta contributi esterni.

La cosa interessante non è che ora puoi costruire un bot per lo shopping. La cosa interessante è la forma: una visione insolitamente netta di come dovrebbe essere strutturato un agente che tocca sistemi aziendali reali. Tutto ciò che segue è trasferibile a qualsiasi agente che debba scrivere su un backend reale: inventario, anagrafiche clienti, banking, strumenti operativi.

La divisione: due agenti, non uno​

Anthropic fornisce un agente di shopping (rivolto ai clienti) e un agente merchant (rivolto al personale), ciascuno con la propria interfaccia di backend (StorefrontBackend e MerchantBackend) e il proprio insieme di skill. Hanno deliberatamente evitato di costruire:

  • un intent router che smista verso sub-agent
  • subagent per dominio (un "agente carrello" + un "agente resi" + un "agente ricerca")
  • un unico agente monolitico che svolga sia il lavoro per i consumatori sia quello per il personale

Invece: un agente unificato per ciascun pubblico, in un ciclo di agente standard, con skill e strumenti. La loro indicazione, nel post sull'anatomia degli agenti di commercio efficaci: "tutto ciò di cui l'agente ha bisogno nella maggior parte dei turni va in genere nel system prompt", quindi per un agente di shopping la ricerca nel catalogo vive nel prompt perché serve in quasi ogni turno. "Il resto va nelle skill." Assistenza clienti, personalizzazione, resi: skill.

È una posizione forte. Intent router e subagent per dominio sono l'architettura predefinita in molti tutorial, e Anthropic ti sta dicendo: per un singolo pubblico con sessioni strettamente accoppiate, non farlo.

Il guardrail portante: le scritture in staging​

Pro tip
  • La riga più importante del blueprint: 'Nessuna chiamata a strumento del modello sposta denaro o modifica l'attività.' Ogni mutazione passa da un passaggio di approvazione controllato dal server. Se prendi una sola cosa dal repo, prendi questa.

Il blueprint impone la sicurezza nel codice, non nei prompt. Il meccanismo ha tre parti:

Guided walkthrough1 of 3
  1. Il server mantiene un registro per sessione di ogni ID di prodotto, SKU, ID di campagna e ID di prezzo che ha consegnato al modello. Scritture e rendering accetteranno SOLO ID presenti in quel registro. Se il modello inventa uno SKU, l'harness rifiuta, senza bisogno di prompt engineering.

Il blueprint gestisce anche altre due classiche trappole:

  • Contenuti regolamentati: per commissioni, informative e prezzo mostrato al consumatore, il modello sceglie quale prodotto illustrare; le parole vengono da un testo approvato fornito dal server. Il modello non scrive mai il testo delle informative.
  • Sanificazione del testo di terzi: qualsiasi contenuto generato dagli utenti (recensioni, note dei venditori, messaggi) viene racchiuso in marcatori di "testo recintato" prima di raggiungere il modello, così non può infilare istruzioni nel prompt.

Pagamenti: esplicitamente fuori ambito​

Il blueprint non effettua ordini e non addebita carte. Il checkout viene reso perché sia l'applicazione host a completarlo. Nelle parole di Anthropic, questo "tiene la gestione dei pagamenti, le regole antifrode e le credenziali fuori dall'agente". Visa, Mastercard e Accenture sono partner citati nell'annuncio, ma il passaggio di pagamento vive nel tuo checkout esistente o in un fornitore di pagamenti agentici, mai nella superficie di strumenti del modello.

È un'altra linea netta: se può far perdere denaro in un colpo solo, il modello non la tocca.

Tre percorsi di runtime, un solo core​

Il repo divide ogni agente in un pacchetto core (tipi, interfaccia di backend, prompt, contratti degli strumenti) e pacchetti runtime separati che adattano il core a diverse superfici di erogazione:

Messages API — il ciclo di riferimento

from shopping_agent import ShoppingAgentConfig
from shopping_agent_runtime import ShoppingAgent

agent = ShoppingAgent(
backend=your_backend,
skills_dir=Path("shopping-agent/skills"),
config=ShoppingAgentConfig(brand_name="Your Store"),
)
async for event in agent.stream_turn(messages, session, state):
# yields: text_delta | tool_call | ui | cart_update | turn_complete
...
await agent.update_memory(messages, session)

Agent SDK — con una console locale

python shopping-agent/runtime-agent-sdk/main.py \
--once "a two-person tent under $250"

python merchant-agent/runtime-agent-sdk/main.py
# prints staged changes and waits for y/n approval

Managed Agents (beta) — ospitato

scripts/deploy_managed_agent.sh \
shopping-agent/managed-agents/shopping-agent

# The manifest declares tools + a storefront MCP server;
# Anthropic hosts the loop.

Lo stesso codice core/ gira in tutti e tre, ed è questo il vero pattern portabile: tieni il contratto dell'agente (strumenti, prompt, interfaccia di backend) separato dall'harness di erogazione. Se fra sei mesi passi da Messages API a Managed Agents, cambia solo il pacchetto runtime.

Memoria: non nel contesto​

La memoria a lungo termine (preferenze, ordini passati, note di servizio) è persistita nei tuoi database esistenti, non nel contesto del modello. L'estrazione avviene in modo asincrono dopo la fine della conversazione, quindi non paghi latenza per aggiornare la memoria nel percorso caldo. Al turno successivo, il runtime idrata la memoria rilevante nel system prompt.

Vale la pena interiorizzarlo anche se non costruisci nel commercio: infilare riassunti di conversazione nel contesto a ogni turno è un errore di prestazioni comune. La forma del blueprint, scrittura asincrona e lettura all'inizio del turno, è quella più economica.

I quattro verticali (e perché differiscono)​

examples/ include demo end-to-end per quattro verticali, ciascuno con una sua particolarità strutturale che puoi copiare:

  • Retail — il caso di base. Catalogo standard, carrello, checkout.
  • Viaggi — inventario legato alle date (un posto in volo scade), presentazione dell'itinerario con confronto fra più tratte.
  • Telecom — contesto dell'account ("il tuo piano attuale è X"), matrici di piani, informativa regolamentata sulle commissioni.
  • Intrattenimento — blocchi a tempo sui biglietti, liste d'attesa, mappe dei posti della sede.

Se il tuo prodotto non è commercio ma ha una qualsiasi di queste caratteristiche (inventario che scade, informativa regolamentata, blocchi a tempo), vale la pena leggere il verticale corrispondente prima di progettare il tuo agente.

Fallo girare in un pomeriggio​

Clona, installa, esegui un verticale

git clone https://github.com/anthropics/commerce-agents.git
cd commerce-agents

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # add ANTHROPIC_API_KEY

(cd examples && npm ci)

python scripts/run_demo.py retail
# API on :8000, storefront on :3000

Il repo si verifica con ruff check . && ruff format --check . && pytest && python scripts/check.py, e c'è un python scripts/verify_all.py per il controllo completo.

Termini da conoscere​

Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 5

Verifica te stesso​

Check yourself

0/4
  1. Perché il blueprint mette in staging ogni scrittura invece di affidarsi a istruzioni nel prompt come 'non effettuare mai un ordine senza conferma'?
  2. In che cosa l'architettura dell'agente merchant differisce dal comune pattern 'router + subagent' insegnato da molti tutorial?
  3. Dove vive la memoria a lungo termine del cliente nel blueprint?
  4. Il blueprint 'non effettua ordini e non addebita carte.' Perché?

Fonti e letture di approfondimento​

Prossimi passi​