Costruire un assistente IA consapevole del contesto con AgentCore e OpenClaw

Costruire un assistente IA consapevole del contesto con AgentCore e OpenClaw

Il problema della continuità conversazionale

Gli assistenti IA disponibili sul mercato risolvono bene una problematica specifica: rispondere a domande individuali con precisione e velocità. Tuttavia, falliscono completamente su un aspetto altrettanto cruciale: la continuità conversazionale. Immaginate di chiedere a un assistente senza memoria informazioni sul vostro giardino oggi, e questo non ricorda che tre settimane fa avevate menzionato i vostri letti rialzati con drenaggio rapido, che utilizzate solo fertilizzanti biologici, o che le vostre petunie stavano soffrendo durante un'ondata di calore. Ogni conversazione ricomincia da zero, e l'onere di rispiegare il contesto ricade interamente sull'utente.

Il problema non risiede nella qualità delle risposte fornite dall'IA, ma nel fatto che l'assistente non possiede alcuna memoria di voi come individuo. Questo articolo presenta come costruire un assistente personale che accumula e mantiene il contesto utilizzando OpenClaw, un sistema agentico open source, in esecuzione su AgentCore runtime, una capacità di Amazon Bedrock AgentCore. La memoria di AgentCore trasforma le chat monouso in conoscenza duratura e accessibile. Vedremo anche come etichettare queste memorie con metadati strutturati per recuperare i record che sono effettivamente rilevanti per la domanda specifica posta.

Sprout: un caso di studio applicabile a qualsiasi dominio

L'esempio esecutivo presentato in questo articolo è Sprout, un assistente specializzato in giardinaggio, ma l'architettura è completamente domain-agnostic e riutilizzabile. Modificate semplicemente la persona dell'assistente e il manifesto delle competenze, e la stessa pipeline può servire un bot di supporto clienti, un coach di fitness, un helpdesk interno, o qualsiasi altro tipo di assistente IA specializzato. L'intero sistema risiede in un singolo template AWS CloudFormation, si distribuisce con un comando, e funziona su un modello basato sul consumo effettivo che costa solamente pochi dollari al mese per un uso personale leggero. Nel corso della discussione, condividiamo linee guida di design che potete applicare agli assistenti che costruirete su questo stack tecnologico.

Panoramica della soluzione

Come funziona il flusso end-to-end

AgentCore è una piattaforma progettata per costruire, connettere e ottimizzare agenti in scala, con qualsiasi framework o modello disponibile. Il flusso di richiesta end-to-end parte da un webhook in entrata da Telegram, passa attraverso il runtime di AgentCore, e coinvolge vari servizi AWS di supporto.

Il sistema presenta due punti di ingresso che convergono su un singolo agente. I messaggi di Telegram arrivano attraverso Amazon API Gateway e una funzione Lambda webhook, mentre i lavori programmati come i promemoria mattutini per l'innaffiamento arrivano attraverso Amazon EventBridge Scheduler e una funzione Lambda di cronjob. Entrambi i percorsi invocano l'API InvokeAgentRuntime sul runtime di AgentCore, dove un processo server.py sottile coordina il gateway OpenClaw, la memoria di AgentCore, e l'API Converse di Amazon Bedrock. Amazon Simple Storage Service (Amazon S3) fornisce l'archiviazione dello spazio di lavoro, AWS Key Management Service (AWS KMS) gestisce la crittografia, AWS Secrets Manager contiene il token del bot, e Amazon CloudWatch cattura i log e le metriche.

Prerequisiti per l'implementazione

Per distribuire la vostra versione utilizzando il pulsante Launch Stack o gli script deployment, avrete bisogno di:

• Accesso ad Amazon Bedrock AgentCore, inclusi il runtime di AgentCore e la memoria di AgentCore
• Accesso ai modelli concesso per i modelli che intendete utilizzare: Claude Haiku 4.5 per il testo e Claude Sonnet 4.5 per la visione (o gli equivalenti disponibili nel vostro account)
• Docker con supporto per build linux/arm64, più AWS Command Line Interface (AWS CLI) configurato. Questo è necessario solo se intendete costruire e spingere la vostra immagine personalizzata
• Un token bot Telegram (ottenuto da BotFather) che serve come porta d'ingresso dell'assistente
• Familiarità di base con i concetti di orchestrazione degli agenti e CloudFormation

L'architettura: un agente serverless su AgentCore runtime

Componenti centralizzati in un singolo template

Ogni componente vive in un singolo template CloudFormation, e nessuno strumento di build è richiesto per il lancio. Le seguenti sezioni esamineranno le decisioni architetturali fondamentali.

AgentCore runtime: pagare solo per il calcolo attivo. L'agente vive in un container su AgentCore runtime, che utilizza la determinazione dei prezzi basata sul consumo. Siete fatturati per il calcolo che il vostro agente consuma attivamente, non per il tempo di parete, e non pagate per il tempo di attesa per operazioni di I/O come la risposta del modello. Per un assistente personale utilizzato in brevi esplosioni, questa è la differenza tra una base di circa 1-2 dollari al mese e un'istanza Amazon Elastic Compute Cloud (Amazon EC2) sempre attiva di circa 35 dollari al mese. Queste cifre sono stime per un uso personale leggero a partire da luglio 2026. Consultate il pricing di AgentCore per le tariffe attuali.

Il runtime applica un contratto minimo di container: ascoltare sulla porta 8080 ed esporre GET /ping per l'integrità e POST /invocations come punto di ingresso dell'agente. Il nostro container è linux/arm64, costruito multi-stage dall'immagine ufficiale di OpenClaw più un livello Python.

OpenClaw come substrato dell'agente

OpenClaw fornisce il ciclo dell'agente, l'uso dello strumento, e un sistema di competenze. Esegue un wrapper (server.py) che lo adatta al contratto del protocollo HTTP di AgentCore:

• All'avvio del container, server.py avvia openclaw gateway run come processo secondario e lo verifica con health check
• GET /ping restituisce rapidamente uno stato sano, in modo che il probe di prontezza di AgentCore passi
• POST /invocations fa il lavoro reale: analizza il payload, recupera la memoria, assembla il contesto, inoltra il turno al gateway e persiste il risultato. Una callout importante: AgentCore può scongelare un container congelato il cui processo secondario è terminato. Quindi il percorso di invocazione non presume che il gateway sia vivo, ma chiama un helper ensure_openclaw_ready() che ri-verifica l'integrità (e riavvia il gateway se necessario) prima di inoltrare il turno

Questo modello di wrapper si generalizza ad altri casi d'uso. Qualsiasi framework di agenti che funziona come processo locale può essere adattato al runtime di AgentCore allo stesso modo, senza modificare il framework stesso.

Due modelli, instradati per compito

La chat di testo e la comprensione delle immagini hanno diversi compromessi di costo e qualità, quindi l'assistente li instrada a diversi modelli Claude su Bedrock:

• Claude Haiku 4.5 per il testo: veloce ed economico per i turni conversazionali ad alto volume che dominano l'uso quotidiano
• Claude Sonnet 4.5 per la visione: ragionamento multimodale più forte per il compito meno frequente ma più difficile di diagnosticare una pianta da una foto

I turni di testo fluiscono attraverso il gateway OpenClaw, che porta competenze e stato di sessione. I turni di immagine chiamano il modello linguistico di grandi dimensioni (LLM) da Bedrock direttamente da server.py, passando i byte dell'immagine come blocchi di contenuto multimodale. Instradiamo deliberatamente le immagini attorno al gateway: la build OpenClaw in-container ha eliminato le parti di contenuto image_url prima che raggiungessero Bedrock, quindi chiamare l'API Converse direttamente da server.py assicura che il modello veda i pixel effettivi. Entrambi i percorsi condividono lo stesso prompt di sistema (persona più memoria), in modo che l'esperienza rimanga coerente.

Gli ID del modello sono variabili di ambiente (MODEL_ID, VISION_MODEL_ID), quindi potete scambiare i modelli per distribuzione senza ricostruire l'immagine.

Le competenze come unità di capacità riutilizzabile

Le capacità sono dichiarate come competenze in un manifesto community-skills.json. Uno script in fase di distribuzione le materializza nel container e le registra nella configurazione di OpenClaw prima che l'immagine sia costruita. Sprout spedisce con competenze di meteorologia, promemoria e note sulle piante al momento della pubblicazione di questo articolo. Scambiate il manifesto e la stessa pipeline serve un dominio diverso. Questo è ciò che rende l'intera cosa uno schema riutilizzabile e non solo un bot.

Telegram come porta d'ingresso serverless

Telegram è un canale pratico per un assistente personale poiché è basato su webhook e mantiene tutto serverless. Non richiede sviluppo client, funziona su ogni dispositivo che l'utente già possiede, e supporta testo, immagini e formattazione ricca attraverso un'API bot diretta. BotFather emette un token bot, che è memorizzato in Secrets Manager. La distribuzione registra un webhook che punta Telegram all'endpoint del gateway API. Quando l'utente invia un messaggio, Telegram lo consegna alla funzione Lambda webhook per convalidare il payload e chiamare InvokeAgentRuntime. La risposta viaggia indietro attraverso l'API del bot Telegram.

Una lezione di formattazione da notare: il modello markdown legacy di Telegram è inflessibile riguardo ai caratteri non sfuggiti e un singolo underscore casuale in una risposta del modello può far fallire l'invio dell'intero messaggio. Rendere le risposte come HTML è affidabile, quindi l'assistente converte l'output del modello in HTML sicuro per Telegram prima dell'invio.

La memoria: trasformare le chat monouso in conoscenza duratura

Il modello mentale: eventi a breve termine, estrazione a lungo termine

L'architettura descritta finora è un agente capace, economico e serverless, ma di per sé ancora vi dimentica tra le conversazioni. La memoria è ciò che cambia tutto questo. Immaginate di aver menzionato settimane fa che coltivate biologicamente, e oggi l'assistente raccomanda un trattamento e aggiunge, di sua iniziativa, che ha scelto l'opzione biologica perché non utilizzate fertilizzanti sintetici. Un modello senza stato non può farlo.

La memoria di AgentCore ha due livelli. La memoria a breve termine memorizza ogni turno di conversazione come evento attraverso CreateEvent, codificato per actorId (l'ID della chat Telegram) e sessionId. Questo è il trascritto grezzo.

La memoria a lungo termine è prodotta in modo asincrono da strategie di estrazione gestite in record strutturati e duraturi. Abbiamo configurato tre strategie:

• USER_PREFERENCE: scelte esplicite dichiarate dal giardiniere ("utilizzo solo fertilizzanti biologici")
• SEMANTIC: fatti dedotti ("coltiva petunie messicane in un letto rialzato in acciaio Corten")
• SUMMARIZATION: riassunti di sessione episodica ("ha discusso di foglie inferiori ingiallite durante un'ondata di calore")

Spazi dei nomi: un giardino per giardiniere

Sprout archivia i record in spazi dei nomi per utente, quindi non due chat si mischiano mai:

• sprout/{chat_id}/long_term: preferenze e fatti semantici
• sprout/{chat_id}/episodic/{session_id}: riassunti di sessione

L'ID della chat è l'unico segmento variabile, il che rende l'isolamento facile da ragionare e testare: ogni giardiniere unico mappa esattamente a uno spazio dei nomi, e nessun due giardinieri si scontrano.

Il pipeline di recupero, assemblaggio e iniezione

A ogni turno, l'agente recupera i record a lungo termine rilevanti, li classifica e li inietta nel prompt di sistema. Ecco cosa accade ad ogni singolo messaggio, all'interno di server.py:

• Recuperare: chiamare RetrieveMemoryRecords contro sprout/{chat_id}/long_term, utilizzando il messaggio dell'utente come query di ricerca, limitato a 50 risultati, sotto un budget di 3 secondi. Se il recupero scade o genera errori, degrada al fallback
• Classificare: ordinare i risultati per rilevanza utilizzando un modello di rango incorporato
• Iniettare: formattare i record come sezione "Cosa conosco dell'utente" nel prompt di sistema, in modo che il modello possa utilizzi questa conoscenza nelle sue risposte

Specifiche tecniche e implementazione

Gestione delle transazioni e della persistenza

Ogni interazione con il sistema coinvolge molteplici passaggi di persistenza. Quando un utente invia un messaggio, il sistema:

1. Riceve il