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

Sessões de agente

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve ativar as Sessões de memória do agente na página Visualizações . Consulte Gerenciar prévias do Databricks.

As sessões de agente oferecem aos seus agentes um armazenamento durável e independente de framework para o estado da sessão: o estado que um agente ou framework mantém para uma interação. Normalmente, trata-se do histórico de conversas, a transcrição ordenada de mensagens, chamadas de ferramentas e resultados que um agente lê no início de um turno e aos quais ele acrescenta à medida que entra em execução. Pode também ser qualquer outro estado que um framework persista para a interação, como um gráfico LangGraph. O Databricks armazena-o no Lakebase e gerencia o armazenamento para você, para que você não precise criar ou operar o banco de dados.

nota

Durante a visualização, você será cobrado pela instância do Lakebase subjacente que armazena suas sessões. Não se aplicam cobranças adicionais para as sessões do agente em si. O preço está sujeito a alterações conforme a pré-visualização avança.

Use as sessões do agente quando quiser:

  • Mantenha a história da conversa de um agente para que ela sobreviva a reinicializações e possa ser retomada posteriormente.
  • Reconstrua o contexto completo (incluindo chamadas de ferramentas e raciocínio) em uma mensagem de acompanhamento.
  • List, resume, and branch past conversations from your own UI.

As sessões de agente mantêm o estado de uma única interação (estado de curto prazo, na sessão). Para memória de longo prazo que persiste em todas as conversas, use a memória do 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.
  • Para usar os exemplos da API REST, instale a CLI do Databricks (para gerar um token OAuth), curl e jq.

Como funcionam as sessões do agente​

Hierarquia de recursos de sessões do agente: um armazenamento de sessões contém muitas sessões, e cada sessão contém muitos itens de sessão ordenados.

As sessões do agente têm três níveis:

  • Um armazenamento de sessão é o contêiner com escopo de workspace para as sessões de um agente. A criação de um armazenamento provisiona o armazenamento Lakebase de suporte automaticamente. Você escolhe um ID de armazenamento exclusivo do workspace e o usa para se referir ao armazenamento em chamadas posteriores. Passe o ID do armazenamento como:

    • O argumento name no SDK AgentKit.
    • O parâmetro de query session_store_id na API REST.

  • Uma session é uma interação durável (tipicamente um histórico de conversa) dentro de um armazenamento. Uma session é identificada por:

    • actor_id (obrigatório): a quem a sessão pertence, como um usuário final ou outro agente. Ele agrupa todas as sessões de um assunto para que você possa listá-las e filtrá-las juntas. Ao criar um aplicativo por usuário, defina actor_id como o ID do usuário (por exemplo, a identidade verificada do usuário final proveniente da autenticação do seu aplicativo) para que as sessões de cada usuário permaneçam agrupadas. Defina-o a partir do contexto de aplicativo confiável, nunca de um valor fornecido pelo modelo ou pelo usuário.
    • session_id (opcional): um ID escolhido pelo chamador para a interação. O serviço gera um quando você o omite.
    • parent_session_id (opcional): torna a sessão filha de outra sessão no armazenamento, como a conversa de um subagente. Defina-o ao criar a sessão.

  • Um item de sessão é uma entrada na história ordenada de uma sessão. Cada item contém um valor data opaco e compatível com JSON, como uma mensagem, uma chamada de ferramenta, um resultado de ferramenta ou um bloco de raciocínio. O Databricks atribui a cada item um item_id e um create_time e não inspeciona nem valida seu conteúdo. Os itens são imutáveis após serem acrescentados.

O serviço mantém uma ordem determinística para os itens de uma sessão e autoriza cada operação no armazenamento da sessão.

Começar​

Esses exemplos configuram sessões de agente para um agente de suporte: eles criam um armazenamento de sessão, começam uma sessão para uma conversa, anexam os turnos da conversa e leem a história em uma solicitação posterior. Escolha o cliente que se adapta ao seu projeto.

Os IDs de armazenamento são exclusivos em um workspace. Se você executar ambas as tab, ou o ID já estiver sendo usado, escolha um ID diferente ou exclua o armazenamento existente primeiro. As respostas de armazenamento também incluem um UUID atribuído pelo serviço em session_store_id. Chamadas posteriores usam o ID de armazenamento que você escolheu.

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

    O pacote databricks-agentbricks fornece o módulo Python databricks_agentkit.

  2. Crie um armazenamento de sessão e, em seguida, inicie uma sessão para uma conversa. actor_id é o proprietário da conversa; o session_id opcional identifica exclusivamente esta conversa:

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_agentkit import AgentKitClient

    client = AgentKitClient(WorkspaceClient())
    session_store = client.session_stores.create("support-agent-sessions-sdk")
    session = session_store.add(actor_id="customer-123", session_id="case-456")

  3. Append the conversation's turns as the agent runs. Each item is any JSON-compatible value:

    Python
    session.append_items(
        [
            {"type": "message", "role": "user", "content": "I need help with my cluster."},
            {"type": "message", "role": "assistant", "content": "Let's take a look."},
        ]
    )

  4. Em uma solicitação de acompanhamento, recarregue a sessão e leia a história completa para reconstruir o contexto:

    Python
    session = session_store.get("case-456")
    # Request chronological order; list_items defaults to newest-first and auto-pages.
    history = [item.data for item in session.list_items(order_by="create_time asc")]

Os clientes também oferecem suporte para remover o item mais recente, limpar os itens de uma sessão e bifurcar uma conversa em uma cópia independente (opcionalmente até um item específico). Um fork não tem sessão pai, e a exclusão da sessão de origem não a exclui. A exclusão de uma sessão sempre exclui suas sessões filhas e seus itens.

Apoiar a sessão de um framework de agente com sessões de agente​

Agent frameworks such as the OpenAI Agents SDK and the Claude Agent SDK read conversation história at the começo of a execução and append new items at the end. The session store maps directly onto that pattern:

Operação de framework

Chamada do SDK AgentKit

Ler história

list_items(order_by="create_time asc")

Adicionar itens de turno

append_items(items)

Desfazer último item

pop_item()

Limpar o thread

clear_items()

Operação de framework

Chamada do SDK AgentKit

Ler história

list_items(order_by="create_time asc")

Adicionar itens de turno

append_items(items)

Desfazer último item

pop_item()

Limpar o thread

clear_items()

Escopo e acesso​

As sessões de agente armazenam itens de uma sessão como valores opacos e compatíveis com JSON: o serviço persiste e retorna o que seu agente ou aplicativo adicionar, sem interpretá-lo. Ele não adiciona recursos de controle de execução como execuções, pontos de verificação ou aprovações como conceitos de primeira classe, embora uma estrutura que serializa esse estado possa persistir como itens.

Os repositórios de sessões têm escopo de workspace e o acesso é autorizado no nível do repositório. O controle de acesso ao repositório cobre as sessões de um repositório. Qualquer usuário do workspace pode listar e obter repositórios de sessão, incluindo seus IDs e descrições. Os campos actor_id e metadata suportam apenas agrupamento e filtragem; eles não concedem nem restringem o acesso. Defina actor_id do contexto do aplicativo confiável em vez de um valor fornecido pelo modelo ou pelo usuário.

Para permitir que outro principal, como o service principal do seu agente, use um armazenamento, conceda acesso a ele com a operação de permissão de concessão do armazenamento (session_store.grant_permission(principal_id) no SDK do AgentKit). Somente o criador do armazenamento ou um administrador do workspace pode conceder acesso. Consulte Gerenciar permissões para memória de agente e armazenamentos de sessão para níveis de permissão, operações com suporte e exemplos.

As sessões do agente e a memória do agente são independentes. Excluir uma sessão ou armazenamento de sessão não exclui a memória retida em um armazenamento de memória. Para criar memória de longo prazo a partir das sessões em um armazenamento, crie um pipeline de memória.

Next steps​

Nesta página