Memória gerida do agente

Importante

Este recurso está em versão Beta.

A memória gerida de agentes dá aos seus agentes uma memória duradoura e de longo prazo que persiste em todas as conversas. O Azure Databricks armazena a memória no Lakebase e gere o armazenamento, indexação e pesquisa semântica por si, para que os seus agentes possam memorizar as preferências do utilizador, decisões passadas e contexto acumulado sem que opere uma base de dados.

Note

Durante a versão de pré-visualização, ser-lhe-á cobrada a instância subjacente de Lakebase que armazena os seus registos de memória. Não existem custos adicionais para a memória gerida do agente em si. Os preços podem variar à medida que a pré-visualização avança.

Use memória gerida quando quiser que os seus agentes:

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

A memória gerida funciona com agentes construídos em qualquer framework. Para um histórico de conversas de curto prazo numa única interação, utilize sessões de agentes geridos.

Requerimentos

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

Como funciona a memória gerida

Hierarquia de recursos de memória do agente gerido: um armazenamento de memória contém muitas entradas de memória, cada uma identificada por actor_id, session_id opcional e caminho, e armazena conteúdo e uma descrição.

A memória gerida tem dois níveis:

  • Um repositório de memória é o contentor associado ao espaço de trabalho das memórias de um agente. Criar um armazenamento provisiona automaticamente o armazenamento Lakebase de suporte. Acede a uma loja pelo seu display_name.
  • Uma entrada de memória é um conteúdo individual numa loja. Cada entrada tem um texto livre content, uma breve description utilizada 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 utilizador final ou outro agente.
    • session_id (opcional): registos de que sessão a memória foi capturada, para rastreio e procedência. Deixe-o não definido para a memória que não esteja associada a uma sessão específica.
    • path (obrigatório): um caminho semelhante a um sistema de ficheiros 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 de entradas para um ator, opcionalmente filtradas por session_id ou por um path prefixo. Use isto para navegar ou renderizar um índice do que um agente sabe.
  • Pesquise entradas de um ator utilizando uma consulta em linguagem natural. A pesquisa retorna as entradas mais relevantes classificadas por uma pontuação de relevância em texto integral (BM25).

Introdução

Estes exemplos configuram memória gerida para um agente de suporte: criam um armazenamento de memória, guardam a preferência do utilizador e recuperam-na numa conversa posterior. Escolha o cliente que se encaixe no seu projeto. Um armazenamento display_name de memória deve ter entre 3 e 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. Autentica-se com o WorkspaceClient SDK da Databricks.

  1. Instale o SDK AgentKit:

    pip install databricks-agentbricks

  2. Crie um armazenamento de memórias para o seu agente. AgentKitClient Autentica-se com as tuas 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. Guarde uma memória depois de o agente aprender algo duradouro sobre um utilizador. actor_id indica de quem é esta memória, path organiza-a nesse ator e description melhora a sua 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. Recorde as memórias do utilizador numa conversa posterior com uma pesquisa em língua natural:

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

API REST

Os clientes invocam a API REST em /api/2.0/agents/memory-stores. Chame-o diretamente em linguagens diferentes de Python.

  1. Gerar um token de 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 o 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. Guardar uma entrada de memória para um utilizador. actor_id é de quem é esta memória, path organiza-a 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. Recorde as memórias do utilizador com uma pesquisa 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 guardar e recuperar memória, encapsule as operações do cliente como ferramentas e instrua o agente sobre quando deve usá-las no prompt de sistema. Defina o actor_id no código de aplicação fidedigno a partir da identidade verificada do utilizador final. Nunca deixes que o modelo escolha de que memória deve ler ou em que memória deve escrever.

O exemplo seguinte encapsula o SDK AgentKit memory_store de Get started como ferramentas para o SDK de Agentes da OpenAI.

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 Claude Agent SDK e outros frameworks: envolve as operações de pesquisa e adição da loja como o tipo de ferramenta do framework.

Partição e memória segura

Dentro de uma loja, actor_id é como se separa de quem pertencem as memórias. Cada lista e cada pesquisa está limitada a um único actor_id, por isso escolha a estratégia que corresponde àquilo de que o seu agente precisa de se lembrar:

  • Memória privada para cada utilizador: Definir actor_id para a identidade verificada do utilizador final. Cada utilizador recebe a sua própria partição, e o agente apenas recupera as entradas desse utilizador.
    • 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 actor_id para uma chave fixa que escolha, como um ID de equipa, projeto ou organização. Todos 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 convenções internas.
  • Memória dividida por outra coisa: Crie actor_id a partir dos seus próprios valores, como um ID de inquilino ou um user:project composto.
    • Exemplo: Uma aplicação multi-tenant define actor_id como {tenant}:{user}, para que os utilizadores de cada cliente fiquem isolados uns dos outros.

Defina actor_id no seu código de aplicação a partir do contexto do chamador confiável: a identidade verificada do utilizador final para memória por utilizador, ou uma chave de equipa ou projeto confiável para memória partilhada. Nunca deixes o modelo escolhê-lo. Se a sua estratégia assentar numa identidade de utilizador final, rejeite os pedidos que não incluam essa identidade, em vez de recorrer a uma identidade partilhada actor_id.

Warning

actor_id separa memórias, mas não é um controlo de acesso. Os armazenamentos de memória geridos estão no âmbito do espaço de trabalho, pelo que qualquer principal que tenha acesso a um armazenamento pode ler e escrever todas as entradas de todos os atores. A loja, não o ator, é o limite de segurança. Para isolamento rigoroso entre inquilinos ou utilizadores, crie um armazenamento de memória separado por limite.

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

Limitations

  • A memória gerida fornece apenas memória de longo prazo. Para o histórico de conversas de curto prazo, consulte sessões geridas do agente.
  • A pesquisa é uma operação de pesquisa em texto integral, classificada por relevância (BM25), que devolve um conjunto dos N resultados mais relevantes, até um máximo de 100 entradas. Não suporta paginação nem pesquisa por similaridade vetorial.
  • O controlo de acesso é aplicado ao nível da loja. O controlo de acesso por entrada e por ator não está disponível.
  • A loja display_name é imutável após a criação. Só description pode ser atualizado.

Passos seguintes

  • Última atualização a