Memória gerida do agente

A memória gerida para agentes permite aos seus agentes ter memória de longo prazo ao longo de várias conversas. O Azure Databricks gere a infraestrutura e isola as memórias de cada escopo, por isso não precisas de gerir o armazenamento ou particionar tu próprio.

Com memória gerida, os seus agentes podem:

• Lembre-se das preferências do utilizador, decisões passadas e contexto acumulado entre as conversas.
• Assegure esse conhecimento com a governação do Unity Catalog.
• Partilha memórias entre agentes e projetos.
• Melhore a sua precisão e eficiência ao longo do tempo.

Requerimentos

• Um espaço de trabalho Databricks com o Unity Catalog ativado.
• O privilégio CREATE MEMORY STORE no esquema principal para criar armazenamentos em memória.

Como funciona a memória gerida

A memória gerida tem dois níveis:

• Um armazenamento de memória é um Unity Catalog securável que atua como um contentor para entradas de memória. Um armazenamento de memória herda a mesma governação, controlo de acesso e linhagem que qualquer outro ativo do Unity Catalog.
• Uma entrada de memória é um conteúdo individual armazenado dentro de um armazenamento de memória. Cada entrada é identificada por um âmbito e um caminho. O âmbito determina a que memórias pertence uma entrada, e o caminho organiza as entradas dentro de um escopo, semelhante a um caminho de ficheiro (por exemplo, /memories/preferences.md).

Scope

Scope é como se torna uma memória privada para um utilizador ou partilhada entre um grupo. A sua aplicação define um âmbito para cada leitura e escrita, e uma pesquisa só retorna entradas com um âmbito correspondente. Escolha a estratégia que corresponda ao que o seu agente precisa de ter em mente:

• Memória privada para cada utilizador: Defina o âmbito para a identidade verificada do utilizador final. Cada utilizador recebe a sua própria partição e só vê as suas próprias entradas. O valor user_client resolve o ID do utilizador final por si.
  • Exemplo: Um agente de suporte lembra-se das preferências de comunicação de um utilizador e dos tickets anteriores.
• Memória partilhada para um grupo: Defina o âmbito para uma chave fixa que escolher, como um ID de organização, equipa ou projeto. Todos os utilizadores lêem e escrevem as mesmas memórias.
  • Exemplo: Um agente de equipa lembra-se de um glossário partilhado de termos da empresa e políticas internas.
• Memória dividida por outra coisa: Construa o escopo a partir dos seus próprios valores, como um ID do inquilino ou um user_id:project compósito.
  • Exemplo: Uma aplicação multi-inquilino mantém a memória de cada cliente separada, ou a memória de um único utilizador é isolada por projeto.

Um único agente pode combinar estratégias numa só conversa. Por exemplo, pode ler a memória privada de um utilizador e a memória partilhada da equipa no mesmo pedido.

Defina o âmbito no código da sua aplicação, a partir do contexto do chamador confiável que o pedido não possa alterar: a identidade verificada do utilizador final a partir do token OBO para memória por utilizador, ou uma chave de inquilino, equipa ou projeto confiável para memória partilhada. Nunca deixes o modelo escolhê-lo. Se a sua estratégia de âmbito depender de uma identidade de utilizador final, rejeite pedidos que não a tenham em vez de recorrer a um âmbito partilhado. A managed-memory competência orienta-te neste processo de configuração.

O Scope separa memórias, mas não concede acesso à loja. O autor da chamada continua a precisar do privilégio READ MEMORY STORE ou WRITE MEMORY STORE para o abrir. Ver Controlo de acesso à memória.

O que o agente guarda e recorda

A memória gerida fornece o armazenamento de memória e as APIs para ler e escrever entradas. A sua aplicação controla o que o agente guarda, quando recupera memória e como utiliza os resultados.

Defina este comportamento no prompt de sistema do agente: especifique que informação persistente o agente deve guardar e quando a deve recuperar. A managed-memory habilidade e os templates mantêm este sistema apressado numa constante chamada MEMORY_INSTRUCTIONS. O âmbito é configurado separadamente em código de aplicação confiável e nunca é escolhido pelo modelo.

Ajusta a redação à tua estratégia de alcance. Segue-se um exemplo da estratégia por utilizador:

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 com competências de memória gerida

A forma mais fácil de adicionar memória gerida a um agente é através da funcionalidade managed-memory Claude Code. A skill trata de toda a configuração necessária por si e funciona tanto com o OpenAI Agents SDK como com o LangGraph.

Incorpora a competência no teu projeto de duas formas:

Comece a partir de um modelo

A competência está incluída nos modelos de aplicação do Databricks. Crie um novo agente a partir de um dos modelos de agentes e localize a competência em .claude/skills/managed-memory/.

1. Clone o repositório de modelos:

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

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

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

   Note

   Para modelos de aplicação "avançados", depois de implementar, tem de conceder ao principal de serviço da aplicação os privilégios do Lakebase Postgres; caso contrário, a inicialização da sessão devolverá o erro 502.

3. Quando a competência estiver no seu projeto, descreva o que quer e o seu assistente de programação trata do resto:

   Dica

   Add Databricks managed long-term memory to my agent.
   

Adicione a competência a um projeto já existente

Se já tens um projeto de agente, acrescenta a tua competência.

1. Cria o diretório de competências se este não existir:

   mkdir -p .claude/skills/managed-memory
   

2. Descarregue o SKILL.md ficheiro do managed-memory diretório de habilidades e guarde-o em .claude/skills/managed-memory/.

3. Quando a competência estiver no seu projeto, descreva o que quer e o seu assistente de programação trata do resto:

   Dica

   Add Databricks managed long-term memory to my agent.
   

Crie e utilize um armazenamento de memória manualmente

Esta secção mostra como criar e usar um armazenamento de memória sem recorrer à managed-memory funcionalidade Claude Code.

O exemplo seguinte configura memória gerida para um agente de apoio ao cliente que armazena as preferências do utilizador e as recupera numa conversa posterior.

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

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

2. Crie um armazenamento de memórias para guardar as memórias do seu 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. Escreve uma entrada de memória depois de o agente aprender algo sobre um utilizador. A scope entrada é particionada para um único utilizador. Utilize o campo contents para o texto completo da memória e o 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 desse utilizador numa 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 a API REST completa, incluindo endpoints, campos de pedido e campos de resposta, veja Memory API reference.

Adicionar memória a um agente através de conversas

O fluxo de trabalho REST acima chama diretamente as APIs de armazenamento e entrada de memória. Quando criares um agente num ponto final de disponibilização de modelos do Azure Databricks, liga um repositório de memória a uma conversa com o cliente compatível com OpenAI no SDK databricks-openai, em vez disso.

Uma conversa é um estado de conversação compatível com a OpenAI — o histórico contínuo de mensagens e invocações de ferramentas — suportado por um repositório de memória e associado a um único âmbito. Reutiliza a mesma conversa entre pedidos para dar ao agente memória dos turnos anteriores.

1. Associe um arquivo de memória existente e um âmbito a uma nova conversa. memory_store.name é o nome de três níveis da loja, e scope particiona o estado da conversa, normalmente pelo utilizador 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 o ID da conversa para responses.create. O agente lê e escreve o estado da conversa no armazenamento de memória vinculado nesse 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 o mesmo ID da conversa em pedidos futuros para que o agente se lembre das interações 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 campos de pedido, consulte APIs de Conversa.

Controlo de acesso à memória

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

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 utilizar. Para dar ao seu agente memória de curto prazo gerida numa sessão, o Databricks recomenda vincular o seu armazenamento de memória a uma conversa. Também pode fazer o seguinte:

• Mantenha a memória de sessão do seu framework de agentes, como o parâmetro OpenAI session= ou um checkpointer do LangGraph.
• Utilize memória autogerida do agente como arquivo do histórico de conversas.

Recomendações de segurança

O Azure Databricks fornece o armazenamento governado, encriptação, primitivas de isolamento e traço de auditoria. Como desenvolvedor da aplicação, a Databricks recomenda o seguinte:

• Utilize o âmbito predefinido por utilizador (user_client), a menos que tenha um motivo específico para particionar de outro modo (por exemplo, memória por projeto ou por conta).
• Atribua privilégios mínimos: apenas o principal de serviço do seu agente precisa de WRITE MEMORY STORE. Conceda subsídios READ MEMORY STORE restritos e evite subsídios amplos a utilizadores humanos ou a grandes grupos.
• Proteger a credencial principal do serviço de aplicação: é a chave para o plano de dados da loja. Trate-o como qualquer credencial de serviço de alto valor — use tokens de curta duração, evite logá-los e adicione defesas SSRF à sua aplicação.

Limitations

• As entradas de memória fornecem apenas memória de longo prazo. Para a diferença entre memória de curto e longo prazo, veja Memória de curto prazo e de longo prazo.
• Os armazenamentos e entradas de memória são criados e geridos apenas através da API REST do Unity Catalog; não existe um SDK Python para estas APIs. Para usar um repositório de memória de um agente, associe-o a uma conversa com o cliente compatível com a OpenAI. Consulte Adicionar memória a um agente através de conversas.

Passos seguintes

• Referência da API de memória