# Inizia a usare AgentCore Memory Amazon Bedrock Amazon Bedrock AgentCore Memory ti consente di creare e gestire risorse di AgentCore memoria che memorizzano il contesto delle conversazioni per i tuoi agenti AI. Questa guida introduttiva ti guida nell'installazione delle dipendenze e nell'implementazione delle funzionalità di memoria a breve e lungo termine. Le istruzioni utilizzano la AgentCore CLI. I passaggi sono i seguenti: 1. Crea una AgentCore memoria contenente una strategia semantica 1. Scrivi eventi (cronologia delle conversazioni) nella risorsa di memoria 1. Recupera i record di memoria dalla memoria a lungo termine Per altri esempi, consulta gli [esempi di Amazon Bedrock AgentCore Memory](memory-examples.md). ## Prerequisiti Prima di iniziare, assicurati di avere: + ** AWS Account** con credenziali configurate () `aws configure` + **Python 3.10\+ installato** + Node.js 18\+ installati (per la AgentCore CLI) Per iniziare a usare Amazon Bedrock Amazon Bedrock AgentCore Memory, installa le dipendenze, crea un progetto AgentCore CLI e configura un ambiente virtuale. I comandi seguenti possono essere eseguiti direttamente nel terminale. ``` pip install bedrock-agentcore npm install -g @aws/agentcore agentcore create --name agentcore-memory-quickstart --no-agent cd agentcore-memory-quickstart python -m venv .venv source .venv/bin/activate ``` La AgentCore CLI fornisce comandi per la creazione e la gestione delle risorse di memoria. Viene utilizzato `agentcore add memory` per creare una memoria e `agentcore deploy` per inserirla. AWS Per le operazioni sugli eventi e la gestione delle sessioni, usa AWS Python SDK (Boto3) (). `bedrock-agentcore` **Nota** La AgentCore CLI consente di creare e distribuire risorse di memoria. [Per il set completo di operazioni di Amazon Bedrock AgentCore Memory, consulta la documentazione di Boto3: bedrock-agentcore-control e [bedrock-agentcore](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html).](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore.html) **Esempio completo:** consulta gli [ AgentCore esempi di Amazon Bedrock](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials) che illustrano i passaggi 1-3. ## Fase 1: Creare una memoria AgentCore Hai bisogno di una AgentCore memoria per iniziare a memorizzare le informazioni per il tuo agente. Per impostazione predefinita, gli eventi di memoria (che chiamiamo memoria a breve termine) possono essere scritti su una AgentCore memoria. Affinché le informazioni vengano estratte e inserite in record di memoria a lungo termine, la risorsa richiede una *strategia di memoria* che è una configurazione che definisce come devono essere elaborati i dati conversazionali e quali informazioni estrarre (come fatti, preferenze o riepiloghi). In questo passaggio, si crea una AgentCore memoria con una strategia semantica in modo da poter utilizzare sia la memoria a breve che a lungo termine. Questa operazione richiederà 2-3 minuti. È inoltre possibile creare risorse di AgentCore memoria nella AWS console. Crea memoria con una strategia semantica: **Example** 1. ``` agentcore add memory --name CustomerSupportSemantic --strategies SEMANTIC agentcore deploy ``` 1. **Esegui `agentcore` per aprire il TUI, quindi seleziona **aggiungi** e scegli Memoria:** 1. Inserisci il nome della memoria: ![Memory wizard: inserisci il nome](https://docs.aws.amazon.com/it_it/bedrock-agentcore/latest/devguide/images/tui/memory-add-name.png) 1. Seleziona la strategia **semantica**, quindi conferma: ![Memory wizard: seleziona la strategia SEMANTIC](https://docs.aws.amazon.com/it_it/bedrock-agentcore/latest/devguide/images/tui/memory-add-strategies.png) Quindi `agentcore deploy` esegui per fornire la memoria. AWS Dopo la distribuzione, verifica che la memoria sia stata creata: ``` agentcore status ``` ## Fase 2: scrivere gli eventi in memoria È possibile scrivere eventi su una AgentCore memoria come memoria a breve termine ed estrarre informazioni per la memoria a lungo termine. La scrittura di eventi in memoria ha molteplici scopi. Innanzitutto, i contenuti degli eventi (più comunemente la cronologia delle conversazioni) vengono archiviati come memoria a breve termine. In secondo luogo, le informazioni pertinenti vengono estratte dagli eventi e scritte nei registri di memoria come parte della memoria a lungo termine. L'id della risorsa di memoria, l'id dell'attore e l'id della sessione sono necessari per creare un evento. In questo passaggio, crei tre eventi, simulando i messaggi tra un utente finale e un chat bot. ``` import boto3 from bedrock_agentcore.memory import MemorySessionManager from bedrock_agentcore.memory.constants import ConversationalMessage, MessageRole control_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') # Retrieve the memory created in Step 1 response = control_client.list_memories() memory = response['memories'][0] memory_id = memory['id'] # Create a session to store memory events session_manager = MemorySessionManager( memory_id=memory_id, region_name="us-west-2") session = session_manager.create_memory_session( actor_id="User1", session_id="OrderSupportSession1" ) # Write memory events (conversation turns) session.add_turns( messages=[ ConversationalMessage( "Hi, how can I help you today?", MessageRole.ASSISTANT)], ) session.add_turns( messages=[ ConversationalMessage( "Hi, I am a new customer. I just made an order, but it hasn't arrived. The Order number is #35476", MessageRole.USER)], ) session.add_turns( messages=[ ConversationalMessage( "I'm sorry to hear that. Let me look up your order.", MessageRole.ASSISTANT)], ) ``` Puoi ottenere eventi (turni) per un attore specifico dopo che sono stati scritti. ``` # Get the last k turns in the session turns = session.get_last_k_turns(k=5) for turn in turns: print(f"Turn: {turn}") ``` In questo caso, puoi vedere gli ultimi tre eventi relativi all'attore e alla sessione. ## Fase 3: Recuperare i record dalla memoria a lungo termine Dopo che gli eventi sono stati scritti nella risorsa di memoria, sono stati analizzati e le informazioni utili sono state inviate alla memoria a lungo termine. Poiché la memoria contiene una strategia semantica di memoria a lungo termine, il sistema estrae e archivia informazioni fattuali. È possibile elencare tutti i record di memoria con: ``` # List all memory records memory_records = session.list_long_term_memory_records( namespace_path="/" ) for record in memory_records: print(f"Memory record: {record}") print("--------------------------------------------------------------------") ``` Oppure richiedi le informazioni più pertinenti come parte di una ricerca semantica: ``` # Perform a semantic search memory_records = session.search_long_term_memories( query="can you summarize the support issue", namespace_path="/", top_k=3 ) ``` È probabile che le informazioni importanti sull'utente siano memorizzate nella memoria a lungo termine. Gli agenti possono utilizzare la memoria a lungo termine anziché una cronologia completa delle conversazioni per assicurarsi che gli LLM non siano sovraccarichi di contesto. ## Aggiungere memoria a un agente esistente Se hai creato un agente Strands senza memoria e desideri aggiungerlo in un secondo momento, procedi nel seguente modo: 1. Aggiungi una risorsa di memoria al tuo progetto: ``` agentcore add memory --name MyMemory --strategies SEMANTIC,SUMMARIZATION agentcore deploy ``` 1. Crea la `memory/` directory nel tuo agente: ``` mkdir -p app/MyAgent/memory ``` 1. Crea`app/MyAgent/memory/session.py`: ``` import os from typing import Optional from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig, RetrievalConfig from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager MEMORY_ID = os.getenv("MEMORY_MYMEMORY_ID") REGION = os.getenv("AWS_REGION") def get_memory_session_manager(session_id: str, actor_id: str) -> Optional[AgentCoreMemorySessionManager]: if not MEMORY_ID: return None retrieval_config = { f"/users/{actor_id}/facts": RetrievalConfig(top_k=3, relevance_score=0.5), f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5) } return AgentCoreMemorySessionManager( AgentCoreMemoryConfig( memory_id=MEMORY_ID, session_id=session_id, actor_id=actor_id, retrieval_config=retrieval_config, ), REGION ) ``` 1. Aggiorna il tuo `main.py` per utilizzare il gestore delle sessioni: ``` from memory.session import get_memory_session_manager @app.entrypoint async def invoke(payload, context): session_id = getattr(context, 'session_id', 'default-session') user_id = getattr(context, 'user_id', 'default-user') agent = Agent( model=load_model(), session_manager=get_memory_session_manager(session_id, user_id), system_prompt="You are a helpful assistant.", ) response = agent(payload.get("prompt")) return response ``` 1. Distribuisci il progetto aggiornato: ``` agentcore deploy ``` **Nota** Ogni risorsa di memoria riceve una variabile di ambiente `MEMORY__ID` (in maiuscolo, con caratteri di sottolineatura) che è automaticamente disponibile nell'ambiente di runtime dell'agente dopo la distribuzione. ## Pulizia Quando hai finito con la risorsa di memoria, puoi eliminarla: ``` agentcore remove memory --name CustomerSupportSemantic agentcore deploy ``` ## Fasi successive Considera i seguenti aspetti: + [Aggiungi un'altra strategia](long-term-enabling-long-term-memory.md#long-term-adding-strategies-to-existing-memory) alla tua risorsa di memoria. + [Abilita l'osservabilità](memory-observability.md) per una maggiore visibilità sul funzionamento della memoria + Guarda altri [esempi](memory-examples.md).