Memória do agente gerenciado

Importante

Esse recurso está em Beta.

A memória gerenciada do agente oferece aos seus agentes uma memória duradoura e de longo prazo que persiste entre as conversas. O Azure Databricks armazena a memória no Lakebase e gerencia o armazenamento, indexação e busca semântica para você, para que seus agentes possam lembrar das preferências do usuário, decisões passadas e contexto acumulado sem que você opere um banco de dados.

Note

Durante a prévia, você é cobrado pela instância Lakebase subjacente que armazena suas entradas de memória. Não se aplicam cobranças adicionais pela memória do agente gerenciado em si. Os preços podem variar conforme a prévia avança.

Use memória gerenciada quando quiser que seus agentes:

  • Lembre-se das preferências dos usuários, fatos e decisões em conversas separadas.
  • Personalize as respostas com base no que o agente aprendeu em sessões anteriores.
  • Compartilhe o conhecimento acumulado entre agentes e projetos.
  • Melhorar a precisão e a eficiência ao longo do tempo.

A memória gerenciada funciona com agentes construídos em qualquer framework. Para histórico de conversas de curto prazo dentro de uma única interação, use sessões de agentes gerenciados.

Requirements

  • Instale o Python 3.10 ou superior para usar o SDK AgentKit. AgentKit SDK é o cliente Python do Databricks para APIs de agentes, que os exemplos abaixo utilizam. Você também pode chamar a API REST diretamente de qualquer linguagem, sem necessidade de Python.

Como funciona a memória gerenciada

Hierarquia de recursos de memória de agente gerenciado: um repositório de memória contém várias entradas de memória, cada uma identificada por actor_id, session_id opcional e path, e armazena conteúdo e uma descrição.

A memória gerenciada tem dois níveis:

  • Um armazenamento de memória é o contêiner com escopo de workspace para as memórias de um agente. Criar um repositório provisiona automaticamente o armazenamento subjacente do Lakebase. Você identifica uma loja pelo seu display_name.
  • Uma entrada de memória é um item de conteúdo individual em uma loja. Cada entrada possui um texto livre content, uma description curta usada para recuperação e um conjunto de campos que a organizam e particionam:
    • actor_id (obrigatório): a quem pertence a memória, como um usuário final ou outro agente.
    • session_id (opcional): registros de qual sessão a memória foi capturada, para rastreamento e procedência. Deixe sem definir para memória que não esteja vinculada a uma sessão específica.
    • path (obrigatório): um caminho semelhante a um sistema de arquivos que organiza entradas dentro de um ator, como /preferences/response-style.md.

Uma entrada é identificada de forma única pela combinação de actor_id, session_id, e path.

Recuperação

Recuperar memória de duas formas:

  • Lista entradas de um ator, filtradas opcionalmente por session_id ou por um prefixo path. Use isso para navegar ou renderizar um índice do que um agente sabe.
  • Pesquise entradas sobre um ator usando uma consulta em linguagem natural. A busca retorna as entradas mais relevantes classificadas por uma pontuação de relevância em texto completo (BM25).

Introdução

Esses exemplos configuram memória gerenciada para um agente de suporte: eles criam um armazenamento de memória, salvam a preferência do usuário e a recuperam em uma conversa posterior. Escolha o cliente que se encaixe no seu projeto. Um armazenamento display_name de memória deve ter de 3 a 56 caracteres, começar com uma letra minúscula, terminar com uma letra ou número, e conter apenas letras minúsculas, números e hífens.

AgentKit SDK

O SDK AgentKit é o cliente Python do Databricks para APIs de agentes, distribuído no databricks-agentbricks pacote. Ele se autentica com o WorkspaceClient do SDK do Databricks.

  1. Instale o SDK do AgentKit:

    pip install databricks-agentbricks

  2. Crie um armazenamento de memórias para seu agente. AgentKitClient Autentica com suas WorkspaceClient credenciais:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

  3. Salve uma memória depois que o agente aprende algo duradouro sobre um usuário. actor_id é de quem é esta memória, path a organiza dentro desse ator e description melhora a recuperação:

    memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
    description="User 123 communication preferences",
)

  4. Recupere as memórias do usuário em uma conversa futura usando uma busca em linguagem natural:

    results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

API REST

Os clientes acessam a API REST em /api/2.0/agents/memory-stores. Chame-o diretamente em linguagens que não sejam Python.

  1. Gerar um token OAuth com a CLI do Databricks:

    databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

  2. Crie um armazenamento de memórias para seu agente:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'

  3. Salve uma entrada de memória para um usuário. actor_id é de quem é esta memória, path a organiza e description melhora a recuperação:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

  4. Lembre-se das memórias do usuário com uma busca em linguagem natural:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

Dê ao seu agente ferramentas de memória

Para permitir que um agente decida quando salvar e recuperar memória, envolva as operações do cliente como ferramentas e instrua o agente sobre quando usá-las no prompt do sistema. Defina o actor_id no código de aplicação confiável com base na identidade verificada do usuário final. Nunca deixe o modelo escolher de quem é a memória que deve ser lida ou escrita.

O exemplo a seguir encapsula o AgentKit SDK memory_store de Get started como ferramentas do SDK OpenAI Agents.

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

O mesmo padrão funciona com o SDK do Agente Claude e outras estruturas: encapsule as operações de busca e adição do armazenamento como o tipo de ferramenta da estrutura.

Partição e memória segura

Dentro de uma loja, actor_id é a forma de separar quais memórias pertencem a quem. Cada lista e pesquisa está vinculada a um único actor_id, então escolha a estratégia que corresponda ao que seu agente precisa lembrar:

  • Memória privada para cada usuário: Definido actor_id para a identidade do usuário final verificado. Cada usuário recebe sua própria partição, e o agente só recupera as entradas desse usuário.
    • 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 actor_id para uma chave fixa que você escolher, como um ID de equipe, projeto ou organização. Todo mundo lê e escreve as mesmas memórias.
    • Exemplo: Um agente da equipe lembra de um glossário compartilhado de termos da empresa e convenções internas.
  • Memória dividida por outra coisa: Construa actor_id a partir de seus próprios valores, como um ID de locatário ou um composto user:project.
    • Exemplo: Um aplicativo multi-inquilino configura actor_id para {tenant}:{user} que os usuários de cada cliente permaneçam isolados uns dos outros.

Defina actor_id no código do seu aplicativo a partir do contexto do chamador confiável: a identidade verificada do usuário final para memória por usuário ou uma chave confiável de equipe ou projeto para memória compartilhada. Nunca deixe a modelo escolhê-la. Se sua estratégia depende da identidade de um usuário final, rejeite solicitações que não incluam essa identidade, em vez de recorrer a um actor_id compartilhado.

Warning

actor_id Separa memórias, mas não é um controle de acesso. Os armazenamentos de memória gerenciados têm escopo de workspace, portanto, qualquer entidade que possa acessar um armazenamento pode ler e gravar todas as entradas em todos os atores. A loja, não o ator, é o limite de segurança. Para isolamento estrito entre inquilinos ou usuários, crie um armazenamento de memória separado por cada limite.

Para permitir que outro principal, como o principal de serviço do seu agente, use uma loja, conceda acesso a ela com a operação de concessão de permissão da loja (memory_store.grant_permission(principal_id) no SDK AgentKit).

Limitations

  • A memória gerenciada fornece apenas memória de longo prazo. Para histórico de conversas de curto prazo, veja sessões de agentes gerenciados.
  • A busca é uma operação de texto completo (BM25), classificada por relevância, que retorna um conjunto com os N principais resultados, limitado a 100 resultados. Não suporta paginação nem busca por similaridade vetorial.
  • O controle de acesso é aplicado no nível da loja. O controle de acesso por entrada e por ator não está disponível.
  • A loja display_name é imutável após a criação. Somente description pode ser atualizado.

Próximas Etapas 

  • Última atualização em