View a markdown version of this page

Memória - Base da Amazônia AgentCore
Como funciona a memóriaMemória gerenciadaAdicionar memória existente (BYO)Desativar memóriaPer-user escopo de memória com ID do atorLong-term recuperação de memóriaTruncamento de contexto

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Memória

Quando a memória está ativada, o equipamento persiste no estado de conversação na AgentCore Memória. Em invocações subsequentes com o mesmo ID de sessão, o agente carrega o histórico armazenado antes que ele decida.

Como funciona a memória

  • Short-term a memória captura eventos brutos (mensagens, chamadas de ferramentas) em uma sessão. É isso que dá continuidade ao agente em todos os turnos.

  • Long-term a memória extrai conhecimento durável por meio de estratégias configuráveis (semântica, resumida, preferência do usuário , episódico ou personalizado) e os torna recuperáveis por meio de pesquisa semântica em sessões posteriores.

  • A ID do ator identifica a entidade que está interagindo com o agente (um usuário, outro agente ou um sistema). Os eventos de memória têm como escopo ActorID + sessionID, portanto, cada ator tem memória isolada. Long-term a recuperação usa ActorID como uma variável de modelo em caminhos de namespace (por exemplo/summary/{actorId}/{sessionId}/), mapeando para as estratégias de memória configuradas.

Memória gerenciada

Quando você cria um equipamento diretamente com a API de serviço e omite a configuração da memória, o serviço provisiona a memória gerenciada. A AgentCore CLI usa um padrão diferente: os novos equipamentos de CLI têm a memória desativada, a menos que você selecione memória gerenciada ou um recurso de memória existente.

Cargas de memória

Não há custo adicional para o arnês em si. A memória gerenciada incorre em cobranças de AgentCore memória padrão para eventos de curto prazo, registros de memória armazenados de longo prazo e solicitações de recuperação. Para evitar cargas persistentes de memória, desative a memória ao criar o chicote. Para obter mais informações, consulte Entenda os custos de aproveitamento os AgentCore preços https://aws.amazon.com/bedrock/agentcore/pricing/ do Amazon Bedrock.

Para personalizar a memória gerenciada no momento da criação:

exemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --memory '{"managedMemoryConfiguration": {"strategies": ["SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE"], "eventExpiryDuration": 60}}'

Para atualizar estratégias em um equipamento existente:

aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"managedMemoryConfiguration": {"strategies": ["SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE", "EPISODIC"]}}}'
AgentCore CLI

Crie um projeto vazio e adicione um equipamento com memória gerenciada:

agentcore create --project-name MyHarnessProject --no-agent
cd MyHarnessProject
agentcore add harness \
  --name myagent \
  --memory-mode managed \
  --memory-strategies SEMANTIC,SUMMARIZATION \
  --memory-event-expiry-days 30
agentcore deploy

A memória está desativada por padrão. Para criar o chicote sem memória, execute o seguinte comando em vez do comando anterioragentcore add harness:

agentcore add harness --name myagent --no-memory
Interactive

Execute agentcore em um diretório de projeto, selecione adicionar e escolha Harness. O assistente inclui uma etapa de memória.

  1. Na etapa Memória, escolha Sem memória persistente ou Ativado para criar memória persistente para o equipamento.

    Etapa de memória: sem memória persistente ou ativada

  2. Quando a memória está ativada, uma opção extra de ajuste de memória aparece nas configurações avançadas. Ative-o com Espaço e pressione Enter para ajustar a recuperação.

    Configurações avançadas: opção de ajuste de memória

  3. Opcionalmente, defina a contagem de mensagens, o top K de recuperação e a pontuação de relevância (cada um pode ser ignorado).

    Ajuste de memória: contagem de mensagens, top K, pontuação de relevância

Confirme o assistente e, em seguida, execute agentcore deploy para se inscrever.

A memória gerenciada é totalmente gerenciada pelo chicote:

  • A configuração da estratégia é controlada por meio deUpdateHarness. Você ainda pode realizar read/write eventos e consultar registros diretamente por meio das APIs de memória.

  • A memória gerenciada não pode ser excluída diretamente por meio das APIs de memória. Para transformar a memória gerenciada em um recurso de AgentCore memória regular, você pode desassociá-la do equipamento de duas maneiras:

    • Use UpdateHarness para mudar para BYO (agentCoreMemoryConfiguration) ou desabilitado.

    • deleteManagedMemory=falseEm vez disso, passe a exclusão para dissociar - DeleteHarness exclui em cascata a memória gerenciada por padrão.

Estratégias disponíveis

Estratégia Description

SEMANTIC

Extrai conhecimento factual de conversas, recuperável por meio de pesquisa semântica.

SUMMARIZATION

Cria resumos contínuos de conversas, com escopo definido por ator e sessão.

USER_PREFERENCE

Captura as preferências e configurações do usuário expressas durante as conversas.

EPISODIC

Registra eventos e experiências significativas como episódios discretos.

Adicionar memória existente (BYO)

Se você precisar de uma configuração avançada além da que a memória gerenciada oferece - modelos de namespace personalizados, criptografia KMS ou memória compartilhada em vários equipamentos - anexe uma instância de memória existente AgentCore .

exemplo
AWS CLI/boto3

Crie uma instância de memória:

aws bedrock-agentcore-control create-memory \
  --name "MyMemory" \
  --event-expiry-duration 30 \
  --description "Memory for my harness"

Conecte-o ao arnês:

aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"agentCoreMemoryConfiguration": {"arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123"}}}'
AgentCore CLI
agentcore create --project-name MyHarnessProject --no-agent
cd MyHarnessProject
agentcore add harness --name myagent \
  --memory-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123"
agentcore deploy

Desativar memória

Para desativar totalmente a memória:

aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"disabled": {}}}'

Per-user escopo de memória com ID do ator

Passe actorId no momento da invocação para definir o escopo da memória para um usuário específico. Cada ator obtém memória isolada de curto e longo prazo:

response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    actorId="user-123",
    messages=[{"role": "user", "content": [{"text": "What do you remember about my preferences?"}]}],
)

Long-term recuperação de memória

Quando um equipamento tem estratégias de memória ativas (gerenciadas ou BYO), a recuperação funciona automaticamente — o equipamento deriva uma configuração de recuperação das estratégias ativas da instância de memória. Em cada invocação, o agente consulta memórias relevantes de longo prazo e as injeta no contexto da conversa antes de raciocinar.

Comportamento padrão:

  • A recuperação é configurada automaticamente com parâmetros padrão (topK=10,relevanceScore=0.2) para cada namespace da estratégia ativa.

  • Nenhuma configuração manual é necessária para memória gerenciada ou BYO.

Substitua os padrões: se você fornecer explicitamente um retrievalConfig na configuração de memória BYO, seus valores terão prioridade e nenhuma derivação automática ocorrerá. Isso permite que você personalize quais namespaces são consultados, ajuste topK ou relevanceScore desative a recuperação para estratégias específicas.

aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"agentCoreMemoryConfiguration": {"arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123", "retrievalConfig": {"/facts/{actorId}/": {"topK": 5, "relevanceScore": 0.5, "strategyId": "FactExtractor-abc123"}}}}}'
Importante

Se você atualizar as estratégias da sua instância de memória BYO (adicionar ou remover) depois de conectá-la a um equipamento, chame UpdateHarness para atualizar a configuração de recuperação. Para memória gerenciada, a estratégia muda por meio da UpdateHarness atualização automática da configuração.

Truncamento de contexto

Quando o histórico de conversas cresce além da janela de contexto do modelo, o equipamento aplica uma estratégia de truncamento. Configure isso no chicote ou substitua por invocação.

  • sliding_window(padrão) - mantém as N mensagens mais recentes. Simples e previsível.

  • summarization- compacta mensagens antigas em um resumo, preservando mais contexto em menos tokens.

  • none- sem truncamento. Use somente se você mesmo gerenciar o tamanho do contexto.

aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --truncation '{"strategy": "sliding_window", "slidingWindowConfig": {"numMessages": 30}}'

Saiba mais: AgentCore Memória, criar um armazenamento de memória, estratégias de memória de longo prazo.

Tópicos relacionados