Pular para o conteúdo principal
Última atualização em

Memória do agente

info

Beta

Esse recurso está na versão Beta.

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

nota

Durante a visualização, você é cobrado pela instância do Lakebase subjacente que armazena suas entradas de memória. Não há cobranças adicionais pela memória do agente em si. Os preços estão sujeitos a alterações conforme o avanço da visualização.

Use a memória do agente quando você quiser que seus agentes:

  • Lembre-se de preferências, fatos e decisões do usuário em conversas separadas.
  • Personalize as respostas com base no que um 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 do agente funciona com agentes baseados em qualquer framework. Para uma história de conversa de curto prazo dentro de uma única interação, use sessões de agente.

Requisitos​

  • Instale o Python 3.10 ou acima para usar o AgentKit SDK. O AgentKit SDK é o cliente Python do Databricks para APIs de agentes usado pelos exemplos abaixo. Você também pode chamar a REST API diretamente de qualquer linguagem, sem a exigência do Python.

Como funciona a memória do agente​

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

A memória do agente tem dois níveis:

  • Um armazenamento de memória é o contêiner com escopo de Workspace para as memórias de um agente. Creating a store provisions the backing Lakebase storage automatically. You address a store by its display_name.
  • Uma entrada de memória é um pedaço individual de conteúdo em um armazenamento. Cada entrada tem um content de texto de formato livre, um description curto usado para recuperação e um conjunto de campos que a organizam e particionam:
    • actor_id (obrigatório): quem é o proprietário da memória, como um usuário final ou outro agente.
    • session_id (opcional): registra de qual sessão a memória foi capturada, para rastreamento e procedência. Deixe sem definição para memórias que não estão vinculadas a uma sessão específica.
    • path (obrigatório): um caminho semelhante a um filesystem que organiza entradas dentro de um ator, como /preferences/response-style.md.

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

As entradas chegam a um armazenamento de duas maneiras: seu agente ou aplicativo as grava diretamente, ou um pipeline de memória as destila das conversas em um armazenamento de sessão.

Recuperação​

Retrieve memory two ways:

  • Listar entradas para um ator, opcionalmente filtradas por session_id ou um prefixo path. Use isto para navegar ou renderizar um índice do que um agente conhece.
  • Pesquise entradas para um ator com uma query em linguagem natural. A pesquisa retorna as entradas mais relevantes ordenadas por uma pontuação de relevância de texto completo (BM25).

Começar​

Esses exemplos definem a memória do agente para um agente de suporte: eles criam um armazenamento de memória, salvam a preferência de um usuário e a lembram em uma conversa posterior. Escolha o cliente que se adapta ao seu projeto. O display_name de um armazenamento 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 hifens.

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

  1. Instale o AgentKit SDK:

    Bash
    pip install databricks-agentbricks

  2. Crie um memory store para o seu agente. AgentKitClient se autentica com suas credenciais do WorkspaceClient:

    Python
    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 aprender algo duradouro sobre um usuário. actor_id é de quem é essa memória, path a organiza dentro desse ator e description melhora a recuperação:

    Python
    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 posterior com uma pesquisa em linguagem natural:

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

Forneça ferramentas de memória ao seu agente​

To let an agent decide when to save and recall memory, wrap the client operations as tools and instruct the agent on when to use them in its system prompt. Set the actor_id in trusted application code from the verified end-user identity. Never let the model choose whose memory to read or write.

O exemplo a seguir encapsula o SDK do AgentKit memory_store de Introdução como ferramentas para o OpenAI Agents SDK.

Python
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 outras estruturas: encapsule as operações de pesquisa e adição do armazenamento como o tipo de ferramenta da estrutura.

Se você também execução um pipeline de memória no mesmo armazenamento de memória, o pipeline poderá reescrever, fazer merge, dividir ou excluir as entradas que seu agente salva para qualquer ator que processar.

Particionar e proteger a memória​

Dentro de um armazenamento, actor_id é a forma como você separa as memórias de cada um. Cada lista e pesquisa é escopada para um único actor_id, portanto, escolha a estratégia que corresponde ao que o seu agente precisa lembrar:

  • Private memory for each user: Set actor_id to the verified end-user identity. Each user gets their own partition, and the agent only recalls that user's entries.

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

  • Shared memory for a group: Set actor_id to a fixed key you choose, such as a team, project, or organization ID. Everyone reads and writes the same memories.

    • Exemplo: Um agente de equipe se lembra de um glossário compartilhado de termos da empresa e convenções internas.

  • Memória dividida por outro critério: crie actor_id a partir de seus próprios valores, como uma ID de tenant ou um composto de user:project.

    • Exemplo: Um aplicativo multi-tenant define actor_id como {tenant}:{user} para 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 de equipe ou de projeto confiável para memória compartilhada. Nunca permita que o modelo faça a escolha. Se a sua estratégia depender da identidade de um usuário final, rejeite solicitações que não possuam uma em vez de recorrer a um actor_id compartilhado.

atenção

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

Para permitir que outra entidade principal, como o service principal do seu agente, use um armazenamento, conceda acesso a ele com a operação grant-permission do armazenamento (memory_store.grant_permission(principal_id) no AgentKit SDK).

Limitações​

  • A memória do agente fornece apenas memória de longo prazo. Para obter a história de conversas de curto prazo, consulte sessões de agente.
  • A pesquisa é uma operação de texto completo (BM25) classificada por relevância que retorna um conjunto de resultados top-N de até 100 entradas. Ele não oferece suporte à paginação ou à busca por similaridade de vetores.
  • Access control is enforced at the store level. Per-entry and per-actor access control are not available.
  • O armazenamento display_name é imutável após a criação. Apenas description pode ser atualizado.

Próximos os passos​

Nesta página