Visão geral das sessões da Agent Platform

As sessões da Agent Platform mantêm o histórico de interações entre um usuário e os agentes. As sessões fornecem fontes definitivas para memória de longo prazo e contexto de conversa.

Há várias opções para usar as sessões da Plataforma de Agentes:

  • Kit de Desenvolvimento de Agente (ADK): depois de implantar o agente do ADK na Gemini Enterprise Agent Platform, o gerenciamento de sessões é feito automaticamente.

  • Chamadas de API: é possível fazer chamadas de API diretas para as sessões da Agent Platform se você não quiser gerenciar sessões usando um agente do ADK.

Principais conceitos

  • Sessão: uma sessão representa a sequência cronológica de mensagens e ações (eventos) de uma única interação em andamento entre um usuário e seu sistema de agente.

  • Evento: um evento armazena o conteúdo da conversa, bem como as ações realizadas pelos agentes, como chamadas de função. Os eventos são compatíveis com um esquema flexível para acomodar dados do cliente e diferentes frameworks.

  • Estado: um estado contém dados temporários relevantes apenas durante a conversa atual.

  • Memória: são informações personalizadas que podem ser acessadas em várias sessões de um usuário específico. O agente pode usar memórias para personalizar as respostas ao usuário e garantir a continuidade entre as sessões.

Funcionalidades principais

As funcionalidades principais das sessões da Agent Platform incluem:

  • Iniciar novas conversas: crie novas sessões quando um usuário iniciar uma interação com um agente.

  • Retomar conversas: recuperar uma sessão específica para que o agente possa retomar uma conversa que foi pausada.

  • Salvar o progresso: anexe novas interações (eventos) ao histórico de uma sessão para atualizá-la.

  • Listar conversas: encontre as conversas de sessão de atividade de um usuário e aplicativo específicos.

  • Limpeza: exclua os objetos de sessão e os dados associados quando as conversas forem concluídas ou não forem mais necessárias.

Segurança e governança corporativas

As sessões da plataforma de agentes são compatíveis com controles de segurança corporativos para ajudar a proteger o histórico de conversas, o estado da sessão e os eventos contra acesso não autorizado ou exfiltração de dados.

VPC Service Controls (VPC Service Controls)

As sessões da plataforma de agentes são compatíveis com o VPC Service Controls para reduzir o risco de exfiltração de dados de sessão e eventos de conversa. Como sessions e events são recursos filhos de uma instância do Agent Runtime (reasoningEngines) disponibilizada pela API Agent Platform (aiplatform.googleapis.com), adicionar a API Agent Platform a um perímetro de serviço do VPC Service Controls protege todas as operações de sessão (CreateSession, GetSession, ListSessions, UpdateSession, DeleteSession, AppendEvent e ListEvents).

Ao configurar o VPC Service Controls para sessões, siga estas diretrizes:

  • Configuração do perímetro: adicione a API Agent Platform (aiplatform.googleapis.com) ao perímetro de serviço do VPC Service Controls. Verifique se o projeto foi adicionado ao perímetro de serviço antes de criar a instância pai do Agent Runtime que hospeda as sessões.
  • Conectividade de endpoint particular: encaminhe solicitações para LOCATION-aiplatform.googleapis.com (ou aiplatform.googleapis.com para endpoints globais) da sua rede VPC por meio de restricted.googleapis.com (199.36.153.4/30) ou de um endpoint interno do Private Service Connect para APIs do Google.
  • Como usar sessões com o Gateway de Agente em um perímetro de serviço: quando um agente implantado no Agent Runtime é vinculado a um Gateway de Agente de aplicação no modo Agente para qualquer lugar (saída), as chamadas de API de saída do agente para as sessões passam pelo gateway. Para evitar bloqueios de perímetro ou gateway:
    • Configure o gateway usando um modelo de conectividade de agente (AgentConnectivityTemplate) com vpcEgress definido como ALL_TRAFFIC e peering de DNS privado do Cloud para googleapis.com.. Para mais detalhes, consulte Conformidade do VPC Service Controls para o Gateway de Agente.
    • Registre e inclua na lista de permissões os endpoints regionais e mTLS Agent Platform API no Agent Registry para que seu agente possa chamar o endpoint Sessions (https://LOCATION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/sessions) e conceda à identidade do agente o papel de egresso do IAP (roles/iap.egressor). Para instruções detalhadas, consulte Rotear o tráfego do Agent Runtime pelo Gateway de Agente.

Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês)

Por padrão, o Google Cloud criptografa o estado da sessão e os eventos de conversa em repouso usando o Google-owned and Google-managed encryption keys. Para proteger os dados da sessão usando chaves gerenciadas no Cloud Key Management Service (Cloud KMS), especifique o encryption_spec (kms_key_name) ao criar a instância pai do Agent Runtime. Todas as sessões e eventos armazenados nessa instância herdam a configuração de CMEK dela. Para conferir as etapas gerais de configuração de projetos e chaves, consulte CMEK para a plataforma de agentes do Gemini Enterprise.

As seguintes limitações se aplicam ao usar CMEK com sessões:

  • Restrições de endpoint global e ambiente de execução implantado: não é possível usar CMEK quando as sessões estão configuradas para usar o endpoint global (location="global"), porque o Cloud Key Management Service exige que as chaves de criptografia residam em um limite geográfico de residência de dados. Para usar a CMEK, crie uma instância pai independente (sem implantar o código do ambiente de execução do agente) em uma região com disponibilidade regional ou multirregional com uma chave do Cloud KMS correspondente (para instâncias multirregionais, use uma chave us para us ou uma chave europe para eu). Se a instância pai também implantar um agente no Agent Runtime, use um local de região única, porque os ambientes de execução implantados não são compatíveis com CMEK em endpoints multirregionais (us ou eu).
  • Não é possível atualizar a chave de criptografia: depois que uma instância é criada com uma chave do Cloud KMS, não é possível alterar a chave dessa instância. Para usar uma chave diferente, crie uma nova instância.

A seguir