Memória do agente gerenciado

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

A memória gerenciada do agente oferece aos seus agentes memória de longo prazo ao longo das conversas. Azure Databricks executa a infraestrutura e isola as memórias de cada escopo, para que você não precise gerenciar o armazenamento ou particionamento por conta própria.

Com a memória gerenciada, seus agentes podem:

• Lembre-se das preferências do usuário, das decisões passadas e do contexto acumulado nas conversas.
• Garanta a segurança desse conhecimento com a governança do Unity Catalog.
• Compartilhe memória entre agentes e projetos.
• Melhore sua precisão e eficiência ao longo do tempo.

Requirements

• Um espaço de trabalho do Databricks com o Unity Catalog habilitado.
• O privilégio CREATE MEMORY STORE no esquema pai para criar repositórios de memória.

Como funciona a memória gerenciada

A memória gerenciada tem dois níveis:

• Um repositório de memória é um objeto protegível do Unity Catalog que funciona como um contêiner para entradas de memória. Um repositório de memória herda a mesma governança, controle de acesso e linhagem que qualquer outro ativo do Catálogo do Unity.
• Uma entrada de memória é um conteúdo individual armazenado dentro de um repositório de memória. Cada entrada é identificada por um escopo e um caminho. O escopo determina a quais memórias uma entrada pertence e o caminho organiza entradas dentro de um escopo, semelhante a um caminho de arquivo (por exemplo, /memories/preferences.md).

Scope

Escopo é como você define se uma memória será privada para um único usuário ou compartilhada com um grupo. Sua aplicação define um escopo para cada leitura e escrita, e uma busca retorna apenas entradas com escopo correspondente. Escolha a estratégia que corresponde ao que seu corretor precisa lembrar:

• Memória privada para cada usuário: Defina o escopo para a identidade verificada do usuário final. Cada usuário recebe sua própria partição e só vê suas próprias entradas. O valor user_client resolve o ID do usuário final para você.
  • Exemplo: Um agente de suporte lembra das preferências de comunicação de um usuário e dos tickets anteriores.
• Memória compartilhada para um grupo: Defina o escopo para uma chave fixa que você escolher, como um ID de organização, equipe ou projeto. Todo usuário lê e escreve as mesmas memórias.
  • Exemplo: Um agente da equipe lembra de um glossário compartilhado de termos da empresa e políticas internas.
• Memória dividida por outro elemento: Crie o escopo a partir de seus próprios valores, como um ID de locatário ou um elemento composto user_id:project.
  • Exemplo: Um aplicativo multi-inquilino mantém a memória de cada cliente separada, ou a memória de um único usuário é isolada por projeto.

Um único agente pode combinar estratégias em uma única conversa. Por exemplo, ele pode ler a memória privada de um usuário e a memória compartilhada da equipe na mesma solicitação.

Defina o escopo no código do seu aplicativo, a partir de um contexto de chamada confiável que a solicitação não pode adulterar: a identidade verificada do usuário final do token OBO para memória por usuário ou uma chave confiável de locatário, equipe ou projeto para memória compartilhada. Nunca deixe a modelo escolhê-la. Se sua estratégia de escopo depende de uma identidade de usuário final, rejeite solicitações que não possuem uma, em vez de recorrer a um escopo compartilhado. A habilidade managed-memory orienta você nessa configuração.

O escopo separa as memórias, mas não concede acesso ao armazenamento. Um chamador ainda precisa do privilégio READ MEMORY STORE ou WRITE MEMORY STORE para abri-lo. Veja Controle de acesso à memória.

Warning

O escopo é a fronteira de isolamento entre os usuários, mas não é um controle de acesso. A entidade de serviço do aplicativo pode ler todos os escopos, portanto, proteja suas credenciais adequadamente.

O que o agente salva e recupera

A memória gerenciada fornece o armazenamento de memória e as APIs para ler e escrever entradas. Sua aplicação controla o que o agente salva, quando recupera a memória e como usa os resultados.

Defina esse comportamento no prompt do sistema do agente: instrua o agente sobre quais informações duráveis salvar e quando recuperá-las. A habilidade managed-memory e os modelos mantêm este prompt do sistema em uma constante chamada MEMORY_INSTRUCTIONS. O escopo é configurado separadamente em código de aplicação confiável e nunca é escolhido pelo modelo.

Ajuste a redação à sua estratégia de escopo. A seguir está um exemplo da estratégia por usuário:

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Comece a gerenciar habilidades de memória

A maneira mais fácil de adicionar memória gerenciada a um agente é a habilidade do managed-memory Claude Code. O recurso cuida de toda a configuração para você e funciona tanto com o OpenAI Agents SDK quanto com o LangGraph.

Coloque a habilidade em seu projeto de duas maneiras:

Começar usando um modelo

A habilidade vem incluída nos modelos de aplicativo do Databricks. Faça scaffolding de um novo agente a partir de um dos modelos de agente e encontre a habilidade em .claude/skills/managed-memory/.

1. Clone o repositório de modelos:

   git clone https://github.com/databricks/app-templates.git
   

2. Navegue pelo app-templates e selecione um modelo de agente para começar. Por exemplo, para usar o template do OpenAI Agents SDK:

   cd app-templates/agent-openai-agents-sdk
   

   Note

   Para modelos de aplicativo "avançados", depois da implantação, você deve conceder à entidade de serviço do aplicativo privilégios do Lakebase Postgres. Caso contrário, a configuração da sessão retornará um erro 502.

3. Depois que a habilidade estiver em seu projeto, descreva o que você deseja e seu assistente de codificação cuidará do restante:

   Dica

   Add Databricks managed long-term memory to my agent.
   

Adicionar a habilidade a um projeto existente

Se você já tiver um projeto de agente, adicione a habilidade a ele.

1. Crie o diretório de habilidades se ele não existir:

   mkdir -p .claude/skills/managed-memory
   

2. Baixe o arquivo SKILL.md do managed-memory diretório de habilidades e salve-o em .claude/skills/managed-memory/.

3. Depois que a habilidade estiver em seu projeto, descreva o que você deseja e seu assistente de codificação cuidará do restante:

   Dica

   Add Databricks managed long-term memory to my agent.
   

Criar e usar um repositório de memória manualmente

Esta seção mostra como criar e usar um repositório de memória sem a managed-memory habilidade claude code.

O exemplo a seguir configura a memória gerenciada para um agente de suporte ao cliente que armazena as preferências de um usuário e as recupera em uma conversa posterior.

1. Gere um token OAuth usando a CLI do Databricks para chamar as APIs:

   databricks auth login --host ${DATABRICKS_HOST}
   databricks auth token
   

2. Crie um repositório de memória para armazenar as memórias do agente:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'
   

3. Escreva uma entrada de memória depois que o agente aprender algo sobre um usuário. O scope particiona a entrada para um único usuário. Use o campo contents para o texto completo da memória e o campo description como um breve resumo que melhora a recuperação:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'
   

4. Pesquise entradas de memória para esse usuário em uma conversa posterior para recuperar o que o agente aprendeu:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "user-123",
       "query": "communication preferences"
     }'
   

Para saber mais sobre a API REST completa, incluindo pontos de extremidade, campos da solicitação e campos da resposta, consulte a referência da API de Memória.

Adicionar memória a um agente usando conversas

O fluxo de trabalho REST acima chama diretamente o repositório de memória e as APIs de entrada. Ao criar um agente em um ponto de extremidade do Serviço de Modelo do Azure Databricks, conecte um repositório de memória a uma conversa com o cliente compatível com OpenAI no SDK databricks-openai.

Uma conversa é um estado de conversa compatível com a OpenAI — o histórico de execuções de mensagens e chamadas de ferramentas — mantido por um repositório de memória e vinculado a um único escopo. Reutilize a mesma conversa em várias solicitações para dar ao agente memória das interações anteriores.

1. Associe um repositório de memória existente e um escopo a uma nova conversa. memory_store.name é o nome de três níveis do repositório e scope particiona o estado da conversa, normalmente pelo usuário final:

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
           "memory_store": {"name": "main.default.support_agent_memory"},
           "scope": {"kind": "user", "value": user_id},
       },
   )
   

2. Passe a ID da conversa para responses.create. O agente lê e grava o estado da conversa no repositório de memória associado a esse escopo:

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

3. Reutilize a mesma ID de conversa em solicitações posteriores para que o agente se lembre de turnos anteriores. Não crie uma nova conversa por turno:

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

Para os endpoints de conversa e os campos de solicitação, consulte APIs de Conversa.

Controle de acesso à memória

Os repositórios de memória são objetos protegíveis do Unity Catalog. Os seguintes privilégios controlam o acesso:

Privilégio	Aplica-se a	Descrição
CREATE MEMORY STORE	Esquema principal	Crie novos repositórios de memória em um esquema.
READ MEMORY STORE	Repositório de memória	Leia os metadados de um repositório de memória e suas entradas.
WRITE MEMORY STORE	Repositório de memória	Crie, atualize e exclua entradas de memória em um repositório.
MANAGE	Repositório de memória	Atualize ou exclua o próprio repositório de memória. Conceda permissões a outros usuários.
USE SCHEMA	Esquema principal	Listar repositórios de memória em um esquema.

Implementar memória de curto prazo

As APIs de entrada de memória fornecem memória de longo prazo como ferramentas para o agente usar. Para fornecer memória de curto prazo gerenciada pelo agente em uma sessão, o Databricks recomenda associar seu repositório de memória a uma conversa. Você também pode:

• Mantenha a memória de sessão da estrutura do agente, como o parâmetro session= da OpenAI ou um ponto de verificação do LangGraph.
• Use memória autogerenciada do agente para o armazenamento do histórico de conversas.

Recomendações de segurança

Azure Databricks fornece o repositório controlado, criptografia, primitivos de isolamento e trilha de auditoria. Como desenvolvedor de aplicativos, o Databricks recomenda o seguinte:

• Use o padrão de escopo por usuário (user_client) a menos que você tenha um motivo deliberado para particionar de forma diferente (por exemplo, por projeto ou memória por conta).
• Aplique o princípio do menor privilégio: somente a entidade de serviço do seu agente precisa de WRITE MEMORY STORE. Conceda READ MEMORY STORE de forma restrita e evite concessões amplas a usuários humanos ou grandes grupos.
• Proteja a credencial da entidade de serviço de aplicativo: ela é a chave para o plano de dados do armazenamento. Trate-a como qualquer credencial de serviço de alto valor: use tokens de curta duração, evite registrá-la em logs e adicione proteções contra SSRF à sua aplicação.

Limitations

• As entradas de memória fornecem somente memória de longo prazo. Para obter a diferença entre memória de curto e longo prazo, consulte memória de curto e longo prazo.
• Os repositórios de memória e as entradas são criados e gerenciados apenas por meio da API REST do Catálogo do Unity; não há Python SDK para essas APIs. Para usar um repositório de memória de um agente, conecte-o a uma conversa com o cliente compatível com OpenAI. Consulte Adicionar memória a um agente com conversas.

Próximas Etapas 

• Referência da API de Memória