Memória do agente gerenciada (legado)

atenção

Legacy

Esta é uma versão anterior do armazenamento de memória do agente gerenciado e será desativada em breve. Não crie novos agentes nele. Para memória de agente de longo prazo, use Memória de agente gerenciada em vez disso.

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

Com a memória gerenciada, seus agentes podem:

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

Requisitos

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

Como a memória gerenciada funciona

A memória gerenciada tem dois níveis:

• Um armazenamento de memória é um objeto protegível do Unity Catalog que atua como um contêiner para entradas de memória. Um armazenamento de memória herda a mesma governança, controle de acesso e linhagem de qualquer outro ativo do Unity Catalog.
• Uma entrada de memória é um item de conteúdo individual armazenado em um armazenamento de memória. Cada entrada é identificada por um escopo e um caminho. O escopo determina a quem pertence uma entrada de memória, e o caminho organiza as entradas em um escopo, de forma semelhante a um caminho de arquivo (por exemplo, /memories/preferences.md).

Escopo

O escopo é como você torna uma memória privada para um usuário ou compartilhada em um grupo. Seu aplicativo define um escopo em cada leitura e gravação, e uma pesquisa retorna apenas entradas com um escopo correspondente. Escolha a estratégia que corresponde ao que seu agente precisa lembrar:

• Memória privada para cada usuário: defina o escopo para a identidade do usuário final verificada. Cada usuário obtém sua própria partição e vê apenas suas próprias entradas. O valor user_client resolve o ID do usuário final para você.

  • Exemplo: um agente de suporte se lembra das preferências de comunicação e dos tickets anteriores de um usuário.

• Shared memory for a group: Set the scope to a fixed key you choose, such as an organization, team, or project ID. Todos os usuários leem e gravam as mesmas memórias.

  • Example: Um agente de equipe se lembra de um glossário compartilhado de termos da empresa e de políticas internas.

• Divisão de memória por outro critério: crie o escopo a partir de seus próprios valores, como um ID de tenant ou um composto de user_id:project.

  • Exemplo: Um aplicativo multitenant 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 conversa. Por exemplo, ele pode ler a memória privada de um usuário e uma memória de equipe compartilhada na mesma requisição.

Defina o escopo no código do seu aplicativo, a partir do contexto de chamador 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 um tenant, equipe ou key de projeto confiável para memória compartilhada. Nunca deixe o modelo escolher isso. Se a sua estratégia de escopo depender da identidade de um usuário final, rejeite solicitações que não tenham uma em vez de recorrer a um escopo compartilhado. A habilidademanaged-memory o orienta durante essa 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. Consulte Controle de acesso à memória.

atenção

O escopo é o limite de isolamento entre usuários, mas não é um controle de acesso. O Service Principal do Databricks do aplicativo pode ler todos os escopos; portanto, proteja suas credenciais de acordo.

O que o agente salva e relembra

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

Defina esse comportamento no prompt do sistema do agente: instrua o agente sobre quais informações duradouras devem ser salvas e quando recuperá-las. A skill e os padrões managed-memory mantêm este prompt do sistema em uma constante chamada MEMORY_INSTRUCTIONS. O escopo é configurado separadamente no código de aplicativo confiável e nunca é escolhido pelo modelo.

Combine a redação com a sua estratégia de escopo. O exemplo a seguir é para a 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 usar habilidades de memória gerenciada

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

Adicione a habilidade ao seu projeto de uma das duas maneiras:

Start from a template

A skill é fornecida dentro de Databricks app padrões. Crie a estrutura de um novo agente a partir de um dos padrões de agente e localize a skill em .claude/skills/managed-memory/.

1. Clone o repository de padrões:

   Bash

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

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

   Bash

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

nota

Para modelos de aplicativo "advanced" (avançados), após a implantação, você deve conceder as privilégios do Lakebase Postgres ao service principal do aplicativo; caso contrário, a configuração da sessão retornará um erro 502.

3. Assim que a habilidade estiver no seu projeto, descreva o que você deseja e seu assistente de programação cuidará do resto:

prompt

Add Databricks managed long-term memory to my agent.

Add the skill to an existing project

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:

   Bash

   mkdir -p .claude/skills/managed-memory

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

3. Assim que a habilidade estiver no seu projeto, descreva o que você deseja e seu assistente de programação cuidará do resto:

prompt

Add Databricks managed long-term memory to my agent.

Criar e usar um armazenamento de memória manualmente

Esta seção mostra como criar e usar um armazenamento de memória sem a habilidade Claude Code managed-memory.

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:

   Bash

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

2. Crie um armazenamento de memória para conter as memórias do seu agente:

   Bash

   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 divide a entrada em partições para um único usuário. Use o campo contents para o texto completo da memória e o description como um resumo curto que melhora a recuperação:

   Bash

   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. Pesquisar entradas de memória para esse usuário em uma conversa posterior para recuperar o que o agente aprendeu:

   Bash

   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 ver a API REST completa, incluindo Endpoint, campos de solicitação e campos de resposta, consulte a referência da Memory API.

Adicionar memória a um agente com conversas

O fluxo de trabalho REST acima chama diretamente o armazenamento de memória e as APIs de entrada. Quando você cria um agente em um Endpoint de servindo modelo do Databricks, conecte um armazenamento de memória a uma conversa com o cliente compatível com a OpenAI no SDK databricks-openai.

Um conversation é um estado de conversa compatível com a OpenAI — a história de execução de mensagens e chamadas de ferramentas — respaldado por um armazenamento de memória e fixado a um único escopo. Reutilize a mesma conversa entre solicitações para fornecer ao agente a memória de turnos anteriores.

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

   Python

   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 o ID da conversa para responses.create. O agente lê e grava o estado da conversa no repositório de memória vinculado sob esse escopo:

   Python

   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 o mesmo ID de conversa em solicitações posteriores para que o agente se lembre de turnos anteriores. Não crie uma nova conversa por turno:

   Python

   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 Endpoint de conversação e campos de solicitação, consulte APIs de Conversação.

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 pai	Criar novos repositórios de memória em um esquema.
READ MEMORY STORE	Armazenamento de memória	Ler os metadados de um repositório de memória e suas entradas.
WRITE MEMORY STORE	Armazenamento de memória	Crie, atualize e exclua entradas de memória em um armazenamento.
MANAGE	Armazenamento de memória	Atualize ou exclua o armazenamento de memória. Conceda permissões a outros usuários.
USE SCHEMA	Esquema pai	Listar armazenamentos de memória em um esquema.

Privilégio	Aplica-se a	Descrição
CREATE MEMORY STORE	Esquema pai	Criar novos repositórios de memória em um esquema.
READ MEMORY STORE	Armazenamento de memória	Ler os metadados de um repositório de memória e suas entradas.
WRITE MEMORY STORE	Armazenamento de memória	Crie, atualize e exclua entradas de memória em um armazenamento.
MANAGE	Armazenamento de memória	Atualize ou exclua o armazenamento de memória. Conceda permissões a outros usuários.
USE SCHEMA	Esquema pai	Listar armazenamentos 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 seu agente usar. Para dar ao seu agente memória de curto prazo gerenciada em uma sessão, a Databricks recomenda vincular seu armazenamento de memória a uma conversa. Você também pode:

• Mantenha a memória de sessão do seu framework de agentes, como o parâmetro OpenAI session= ou um checkpointer do LangGraph.
• Use managed agent sessions para o repositório de histórico de conversas.

Recomendações de segurança

O Databricks fornece o armazenamento governado, criptografia, primitivas de isolamento e trilha de auditoria. Como desenvolvedor do aplicativo, o Databricks recomenda o seguinte:

• Use o default de escopo por usuário (user_client), a menos que você tenha um motivo deliberado para fazer o particionamento de outra forma (por exemplo, memória por projeto ou por account).
• Conceda o privilégio mínimo: apenas o Service Principal do Databricks 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 do Service Principal do Databricks do aplicativo: ela é a key para o plano de dados da loja. Trate-a como qualquer credencial de serviço de alto valor — use tokens de curta duração, evite registrá-la em logs e adicione defesas contra SSRF ao seu aplicativo.

Limitações

• As entradas de memória fornecem apenas memória de longo prazo. Para o histórico de conversas, consulte sessões de agente gerenciadas.
• Os armazenamentos de memória e as entradas são criados e gerenciados exclusivamente por meio da API REST do Unity Catalog; não há um SDK do Python para essas APIs. Para usar um armazenamento de memória de um agente, conecte-o a uma conversa com o cliente compatível com o OpenAI. Consulte Adicionar memória a um agente com conversas.

Os passos seguintes

• Referência da API de memória