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

Sessões de agente

info

Beta

Esse recurso está em Beta.

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.

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:

  • A session store é o contêiner com escopo para workspace para as sessões de um agente. Creating a store provisions the backing Lakebase storage automatically. You choose a workspace-unique session_store_name.

  • 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): vincula uma sessão àquela da qual ela foi bifurcada, para representar conversas ramificadas.

  • 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.

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 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")
    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 à remoção do item mais recente, à limpeza dos itens de uma sessão e à bifurcação de uma conversa em uma cópia independente (opcionalmente até um item específico). A exclusão de uma sessão que possui sessões filhas requer uma opção de força para propagar a exclusão para elas (por exemplo, session.delete(force=True)).

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 de armazenamento de sessão

Ler história

list_items em ordem cronológica (order_by="create_time asc")

Adicionar itens de turno

append os novos itens

Desfazer último item

pop o item mais recente

Limpar o thread

clear os itens da session

Operação de framework

Chamada de armazenamento de sessão

Ler história

list_items em ordem cronológica (order_by="create_time asc")

Adicionar itens de turno

append os novos itens

Desfazer último item

pop o item mais recente

Limpar o thread

clear os itens da session

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 session stores têm escopo de workspace, e o acesso é autorizado no nível do store. Os campos actor_id e metadata oferecem suporte apenas a agrupamento e filtragem; eles não concedem nem restrigem o acesso. Defina o actor_id a partir do contexto do aplicativo confiável, em vez de um valor fornecido pelo modelo ou pelo usuário.

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 (session_store.grant_permission(principal_id) no AgentKit SDK).

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