Práticas recomendadas e padrões

Este guia compartilha práticas recomendadas e padrões de design comprovados para otimizar e dimensionar seu aplicativo de agente. Esse conteúdo pode ajudar você a reduzir os custos de tempo de design, reduzir os custos de tempo de execução e melhorar a confiabilidade do agente.

Geral

Esta seção apresenta práticas recomendadas gerais para começar a desenvolver agentes e escrever instruções.

Comece de forma simples

Ao começar a criar seu aplicativo de agente, comece com casos de uso simples. Depois que os casos de uso simples estiverem funcionando, continue criando casos de uso mais complicados.

As instruções precisam ser específicas

As instruções para o agente precisam ser específicas e sem ambiguidade. As instruções precisam ser bem organizadas e agrupadas por temas. Evite espalhar instruções sobre temas específicos de maneira aleatória. As instruções também precisam ser fáceis de seguir para um humano.

Usar instruções estruturadas

Depois de escrever as instruções, use o recurso Reestruturar instruções para formatá-las. Nesse formato, seu agente será mais confiável.

Usar componentes modulares de várias modalidades e canais

Quando os agentes precisam responder de maneiras diferentes para diferentes modalidades (texto ou voz) ou canais (API, telefonia ou Web), use componentes modulares e verifique o canal e a modalidade em ferramentas e callbacks do Python.

Ferramentas

Esta seção oferece práticas recomendadas para definir e usar ferramentas, incluindo o encapsulamento de APIs externas e o encadeamento de chamadas de ferramentas.

Unir APIs com ferramentas Python

Os esquemas de API externa podem definir muitos parâmetros de entrada e saída que não são relevantes para seu agente. Se você usar ferramentas OpenAPI para casos como esse, poderá fornecer um contexto desnecessário ao modelo, o que pode reduzir a confiabilidade. Por exemplo, suponha que uma ferramenta de especificação OpenAPI receba três parâmetros como entrada e retorne um objeto JSON grande com 100 pares de chave-valor. O agente prevê os três argumentos de entrada para essa ferramenta e, quando ela retorna, ele vê o payload JSON completo com todos os 100 pares de chave-valor. Se apenas três desses pares forem relevantes para a conversa, os outros 97 serão dados irrelevantes que adicionam tokens ao histórico. Embora isso pareça inofensivo, pode criar confusão desnecessária para o agente, aumentar o tempo de raciocínio e a latência.

É uma prática recomendada usar ferramentas Python para encapsular chamadas de API. O encapsulamento permite ofuscar dados desnecessários do agente e do histórico de contexto. Você pode controlar o contexto exato que o agente vê retornando apenas os dados relevantes para ele naquele momento. Isso dá controle total sobre os parâmetros de entrada e saída definidos pela ferramenta, que são compartilhados com o modelo. Essa prática é uma forma de engenharia de contexto com ferramentas.

Exemplo de código:

def python_wrapper(arg_a: str, arg_b: str) -> dict:
  """
  Call the scheduling service to schedule an appointment,
  returning only relevant fields.
  """
  res = complicated_external_api_call(...)
  # Process result to extract only relevant key-value pairs.
  processed_res = {
      "appointment_time": res.json()["appointment_time"],
      "appointment_location": res.json()["appointment_location"],
      "confirmation_id": res.json()["confirmation_id"],
  }
  return processed_res

Usar ferramentas e callbacks para comportamento determinista

Em determinados cenários de conversa, talvez seja necessário um comportamento mais determinista do aplicativo do agente. Nesses casos, use ferramentas ou callbacks.

Os callbacks geralmente são a melhor opção para controle determinista completo. Os callbacks ocorrem fora do escopo do agente, portanto, ele não está envolvido na execução deles.

Os internos de uma ferramenta são totalmente deterministas, mas uma chamada de ferramenta orquestrada por um agente não é. O agente decide chamar uma ferramenta, prepara argumentos de entrada da ferramenta e interpreta os resultados dela. É possível que um agente alucine essa orquestração.

Encadeamento de chamadas de ferramentas

Assim como encapsular chamadas de API com ferramentas, se várias ferramentas precisarem ser executadas durante uma troca de mensagens, instrua o agente a chamar uma ferramenta e implemente essa ferramenta para chamar as outras. Como alternativa, você pode instruir o agente a chamar a primeira ferramenta e definir um callback after_tool_callback para chamar as ferramentas restantes.

Padrão ruim para encadeamento de chamadas de ferramentas

É considerado um padrão ruim instruir o agente a chamar várias ferramentas durante uma conversa para alcançar um objetivo comum.

O modelo precisa prever cada chamada de ferramenta e cada parâmetro nessa chamada. Em seguida, ele precisa garantir que também está prevendo as chamadas de ferramentas em ordem. Isso significa que você está dependendo muito do modelo (que é inerentemente não determinista) para realizar uma tarefa determinista.

Por exemplo, considere a seguinte sequência de ferramentas:

  • tool_1(arg_a, arg_b) -> saída c
  • tool_2(arg_c) -> saída d
  • tool_3(arg_d) -> saída e

Se você definir instruções para essas três chamadas de função, vai ter uma sequência de eventos de tempo de execução como esta:

  • Entrada do usuário
  • Modelo -> O agente prevê tool_1(arg_a, arg_b)
  • tool_1_response.json() é devolvido
  • O agente interpreta tool_1_response.json() e extrai arg_c
  • Modelo -> O agente prevê tool_2(arg_c)
  • tool_2_response.json() é retornado
  • O agente interpreta tool_2_response.json() e extrai arg_d
  • Modelo -> O agente prevê tool_3(arg_d)
  • tool_3_response.json() é retornado
  • Modelo -> O agente fornece a resposta final

Há quatro chamadas de modelo, três previsões de ferramentas e quatro argumentos de entrada.

Bom padrão para encadeamento de chamadas de ferramentas

Quando você precisa chamar várias ferramentas, é considerado um bom padrão instruir o agente a chamar uma única ferramenta e implementar essa ferramenta para chamar as outras.

A ferramenta a seguir chama outras três:

def python_wrapper(arg_a: str, arg_b: str) -> dict:
  """Makes some sequential API calls."""
  res1 = tools.tool_1({"arg_a": arg_a, "arg_b": arg_b})
  res2 = tools.tool_2(res1.json())
  res3 = tools.tool_3(res2.json())

  return res3.json()

Considere a sequência de eventos para uma única chamada de função:

  • Entrada do usuário
  • Modelo -> O agente prevê python_wrapper(arg_a, arg_b)
  • python_wrapper_response.json() é retornado
  • Modelo -> O agente fornece a resposta final

Essa abordagem reduz os tokens e a probabilidade de alucinação.

Definições de ferramentas claras e distintas

Para definições de ferramentas, aplique as seguintes práticas recomendadas:

  • Ferramentas diferentes não devem ter nomes semelhantes. Dê nomes bem diferentes para cada ferramenta.
  • As ferramentas que não são usadas precisam ser removidas do nó do agente.
  • Para nomes de parâmetros, use snake case, nomes descritivos e evite abreviações incomuns.

    Exemplos adequados: first_name, phone_number, url.

    Exemplos ruins: i, arg1, fn, pnum, rqst.

  • Os parâmetros precisam usar estruturas simples em vez de aninhadas. Quanto mais aninhada for uma estrutura, mais você vai depender do modelo para prever pares de chave/valor e a tipagem adequada deles.

Fluxo de trabalho de desenvolvimento

Esta seção apresenta as práticas recomendadas para colaboração em equipe, controle de versões e testes durante o desenvolvimento de agentes.

Definir um processo de desenvolvimento para a colaboração de agentes

Ao colaborar com uma equipe no desenvolvimento de aplicativos de agente, defina um processo de desenvolvimento. Confira alguns exemplos de práticas de colaboração:

  • Usar controle de versão de terceiros: use a importação e a restauração para sincronizar as mudanças com seu sistema de controle de versões de terceiros. Concorde com o processo de sincronização, revisão e fusão. Defina responsáveis e etapas claras para aceitar mudanças (por exemplo, ter resultados de avaliação).
  • Use o controle de versão integrado: configure um processo para usar o controle de versão integrado. Concorde em como usar snapshots para controle de versões. Por exemplo, é possível exigir um snapshot quando um marco é alcançado (um conjunto de avaliações é aprovado) ou antes de um novo desenvolvimento de recursos. Concorde com o processo de sincronização, revisão e mesclagem de mudanças.

Usar versões para salvar o estado do agente

Com as versões, você pode registrar o trabalho ou as mudanças feitas no aplicativo do agente. Depois de fazer mudanças nas instruções, ferramentas, variáveis e outros itens, você pode salvar esse estado antes de fazer outras mudanças. As versões são snapshots imutáveis do agente em um determinado momento. Crie uma versão quando estiver satisfeito com algumas mudanças e o aplicativo do agente estiver funcionando como você o projetou, principalmente depois de validar as mudanças com avaliações. Depois de criar uma versão, é possível reverter para ela a qualquer momento.

Crie versões com frequência, talvez depois de cada 10 a 15 mudanças importantes. Também é útil nomear as versões semanticamente. Decida com sua equipe de desenvolvimento a convenção de nomenclatura a ser usada. Por exemplo, nomes descritivos como pre-prod-instruction-changes ou prod-ready-for-testing. Você também pode usar padrões como o Controle de versões semântico, usando nomes como v1.0.0, v1.0.1 etc. As versões também têm um campo de descrição que permite adicionar mais detalhes, semelhante ao corpo de uma mensagem de commit. O nome e a descrição da versão precisam ser curtos, significativos e fáceis de entender caso seja necessário fazer o rollback para essa versão.

Realizar testes de ponta a ponta

O processo de desenvolvimento de aplicativos de agente precisa incluir testes de ponta a ponta para verificar integrações com sistemas externos.

Avaliações

Nesta seção, você vai conhecer as práticas recomendadas para usar avaliações e garantir a confiabilidade do agente.

Usar avaliações

As avaliações ajudam a manter a confiabilidade dos agentes. Use-os para definir as expectativas dos seus agentes e das APIs chamadas por eles.

Processamento de sessões

Esta seção fornece padrões para gerenciar o ciclo de vida da sessão.

Saudações deterministas e latência reduzida com respostas estáticas

É possível configurar o agente para falar uma resposta determinística quando uma sessão é iniciada. Essa abordagem pode economizar chamadas e tokens do modelo e reduzir a latência.

Usar o before_model_callback permite interceptar a entrada recebida e responder com uma mensagem de saudação estática.

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  for part in callback_context.get_last_user_input():
    # Or other events or texts
    if part.text == "<event>session start</event>":
      return LlmResponse.from_parts(parts=[
          Part.from_text(text="Hello how can I help you today?")
      ])
  return None

Responda rapidamente com mensagens de prefixo enquanto o modelo está trabalhando

Quando uma sessão começa, evite forçar o usuário a esperar pela geração do modelo. Você pode adicionar um prefixo às respostas para que o agente possa dar uma saudação amigável e personalizada rapidamente (por exemplo, "Olá, sou o Gemini, seu assistente pessoal"), enquanto o modelo processa simultaneamente a solicitação principal do usuário em segundo plano.

Isso depende da configuração partial = True. Normalmente, uma resposta que não é FuctionCall é considerada uma resposta terminal. Usar partial = True força o agente a continuar o processamento após a resposta.

No exemplo a seguir, o aplicativo do agente entrega a mensagem de boas-vindas rapidamente e continua processando a solicitação principal. Isso elimina a pausa desconfortável da digitação, fazendo com que o agente pareça responsivo.

def before_model_callback(callback_context: CallbackContext, llm_request: LlmRequest) -> Optional[LlmResponse]:
  for part in callback_context.get_last_user_input():
    if part.text == "<event>session start</event>":
      response = LlmResponse.from_parts([Part.from_text("Hello, I'm Gemini, your personal AI assistant.")])
      response.partial = True
      return response
  return None

Verificar e aplicar conteúdo obrigatório

Em alguns casos, talvez seja necessário instruir o agente a fornecer conteúdo obrigatório específico (como uma exoneração de responsabilidade legal) e verificar se ele realmente incluiu esse conteúdo. Esse padrão permite que você confie na geração natural do modelo quando ela funciona, mas aplique o conteúdo de forma determinística quando ela falha.

É possível usar um after_model_callback para verificar a saída do modelo. Se o conteúdo obrigatório estiver presente, o callback vai retornar None, permitindo que a resposta do modelo seja transmitida. Se estiver faltando, o callback vai construir uma nova resposta com o conteúdo obrigatório.

Exemplos de variáveis:

Nome da variável Valor padrão
first_turn Verdadeiro
DISCLAIMER = "THIS CONVERSATION MAY BE RECORDED FOR LEGAL PURPOSES."

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  if callback_context.variables.get("first_turn"):
    callback_context.variables["first_turn"] = False

    # Check if the agent's response already contains the disclaimer.
    # The agent might have produced it based on instructions.
    for part in callback_context.get_last_agent_output():
      if part.text and DISCLAIMER in part.text:
        return None

    # If the agent failed to produce the disclaimer, force it.
    return LlmResponse.from_parts(parts=[
        Part.from_text(DISCLAIMER),
        *llm_response.content.parts
    ])

  return None

Chamar ferramenta personalizada no fim da sessão

Você pode configurar o agente para chamar uma ferramenta específica quando uma sessão termina. Isso pode ser útil para eventos de encerramento pós-chamada, como sincronizar dados na saída, enviar dados para uma API externa, conclusão de tarefas de back-end ou registrar metadados de chamadas.

Por exemplo, suponha que você tenha uma ferramenta como post_call_logging que você quer chamar pouco antes do fim da sessão:

def post_call_logging(session_id: str) -> dict:
  """Logs the session ID to external API."""
  API_URL = "https://api.example.com"
  response = ces_requests.post(
    url=API_URL,
    data={"session_id": session_id}
  )

  return response.json()

Você pode usar o after_model_callback para realizar a seguinte sequência:

  1. Verifique se há uma chamada de ferramenta end_session na resposta do agente.
  2. Crie a parte da ferramenta post_call_logging.
  3. Insira a chamada de ferramenta post_call_logging antes da chamada de ferramenta end_session.

Isso garante que o agente execute a ferramenta de geração de registros antes de encerrar a sessão.

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  for index, part in enumerate(llm_response.content.parts):
    if part.has_function_call('end_session'):
      # Add an additional "post_call_logging" function call before "end_session",
      # so the agent will execute the tool before ending the session.
      tool_call = Part.from_function_call(
          name="post_call_logging",
          args={"sessionId": callback_context.session_id}
      )
      return LlmResponse.from_parts(
          parts=llm_response.content.parts[:index] + [tool_call] + llm_response.content.parts[index:]
      )
  return None

Como usar respostas parciais para atualizações da interface do usuário em tempo real

Quando um agente executa uma ação (por exemplo, atualizar o status do pedido), pode haver um atraso enquanto o modelo processa a resposta final. Com as respostas parciais, é possível enviar notificações para a interface do usuário do cliente quando uma ferramenta termina a execução, desvinculando a atualização visual da geração de texto do modelo.

Sua interface do usuário pode atualizar barras de status, rastreadores ou recibos em tempo real.

Isso depende da configuração partial = True. Normalmente, uma resposta que não é FuctionCall é considerada uma resposta terminal. Usar partial = True força o agente a continuar o processamento após a resposta.

O payload JSON não será enviado ao modelo. Assim, o agente não vai saber da existência do payload durante a geração de respostas.

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  if  llm_request.contents[-1].parts[-1].has_function_response('update_order'):
    order_state =  llm_request.contents[-1].parts[-1].function_response.response['result']['order_state']
    # Return a custom JSON payload before calling the model to generate the final agent response.
    response = LlmResponse.from_parts([Part.from_json(data=json.dumps(order_state))])
    response.partial = True
    return response
  return None

Integração no lado do cliente

Esta seção fornece padrões para integração com aplicativos do lado do cliente.

Usar payloads personalizados para impulsionar sua interface do usuário

Os usuários esperam uma interface dinâmica e interativa. É possível usar payloads personalizados para gerar renderização do lado do cliente, preenchendo a lacuna entre o agente e um aplicativo refinado. Em vez de oferecer opções de texto simples, configure o agente para detectar padrões específicos em uma resposta (por exemplo, uma lista de opções) e transformá-los em elementos de interface do usuário interativos e de alta conversão, como ícones ou botões clicáveis.

Use um after_model_callback para verificar se há gatilhos específicos nas respostas do agente. Por exemplo, se a saída do modelo for: "As opções disponíveis são: reembolso, rastrear pedido, falar com um agente", o callback a seguir intercepta e extrai essas opções como um payload JSON, que pode ser usado para renderização da interface do usuário.

import json

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  prefix = 'Available options are:'
  payload = {}
  for part in llm_response.content.parts:
    if part.text is not None and part.text.startswith(prefix):
      # Return available options as chip list
      payload['chips'] = part.text[len(prefix):].split(',')
      break

  new_parts = []
  # Keep the original agent response part, as the custom payload won't be sent
  # back to the model in the next turn.
  new_parts.extend(llm_response.content.parts)
  new_parts.append(Part.from_json(data=json.dumps(payload)))
  return LlmResponse.from_parts(parts=new_parts)

Mostrar Markdown e HTML

Se a interface conversacional for compatível com Markdown e HTML para respostas do agente, use o simulador para testar essas respostas, já que ele também é compatível com Markdown e HTML.

Exemplos de instruções:

<role>
    You are a "Markdown Display Assistant," an AI agent designed to demonstrate
    various rich content formatting options like images, videos, and deep links
    using HTML-style markdown. Your purpose is to generate and display this
    content directly to the user based on their requests.
</role>
<persona>
    Your primary goal is to showcase the rich content rendering capabilities of
    the platform by generating HTML markdown for elements like images, videos,
    and hyperlinks. You are a helpful and direct assistant. When asked to show
    something, you generate the markdown for it and present it.
    You should not engage in conversations outside the scope of generating and
    displaying markdown. If the user asks for something unrelated, politely
    state that you can only help with displaying rich content. Adhere strictly
    to the defined constraints and task flow.
</persona>
<constraints>
    1.  **Scope Limitation:** Only handle requests related to displaying
        markdown content (images, videos, links, etc.). Do not answer general
        knowledge questions or perform other tasks.
    2.  **Tool Interaction Protocol:** You must use the \`display_markdown\`
        tool to generate the formatted content string.
    3.  **Direct Output:** Your final response to the user must be the raw
        markdown string returned by the \`display_markdown\` tool. Do not add
        any conversational text around it unless the tool returns an error.
        For example, if the tool returns \`"<img src='...'>"\`, your response
        should be exactly \`"<img src='...'>"\`.
    4.  **Clarity and Defaults:** If a user's request is vague (e.g., "show me
        an image"), use the tool's default values to generate a response. There
        is no need to ask for clarification.
    5.  **Error Handling:** If the tool call fails or returns an error, inform
        the user about the issue in a conversational manner.
</constraints>
<taskflow>
    These define the conversational subtasks that you can take. Each subtask
    has a sequence of steps that should be taken in order.
    <subtask name="Generate and Display Markdown">
        <step name="Parse Request and Call Tool">
            <trigger>
                User initiates a request to see any form of rich content (image,
                video, link, etc.).
            </trigger>
            <action>
                1.  Identify the types of content the user wants to see (e.g.,
                    image, video, deep link).
                2.  Call the \`display_markdown\` tool. Set the corresponding
                    boolean arguments to \`True\` based on the user's request.
                    For example, if the user asks for a video and a link, call
                    \`display_markdown(show_video=True, show_deep_link=True)\`.
                3.  If the user makes a general request like "show me something
                    cool", you can enable all flags.
            </action>
        </step>
        <step name="Output Tool Response">
            <trigger>
                The \`display_markdown\` tool returns a successful response
                containing a \`markdown_string\`.
            </trigger>
            <action>
                1.  Extract the value of the \`markdown_string\` key from the
                    tool's output.
                2.  Use this value as your direct and final response to the
                    user, without any additional text or formatting.
            </action>
        </step>
    </subtask>
</taskflow>

Exemplo de ferramenta em Python:

from typing import Any

def display_markdown(show_image: bool, show_video: bool, show_deep_link: bool) -> dict[str, Any]:
    """
    Constructs a markdown string containing HTML for various rich media elements.

    This function generates an HTML-formatted string based on the boolean flags provided.
    It can include an image, a video, and a hyperlink (deep link). The content for
    these elements is pre-defined.

    Args:
        show_image (bool): If True, an <img> tag will be included in the output.
        show_video (bool): If True, a <video> tag will be included in the output.
        show_deep_link (bool): If True, an <a> tag will be included in the output.

    Returns:
        dict[str, Any]: A dictionary with a single key 'markdown_string' containing the
                        generated HTML markdown. If no flags are set, it returns a
                        message indicating nothing was requested.
    """
    # MOCK: This is a mock implementation. It does not fetch any dynamic content.
    # It assembles a markdown string from hardcoded HTML snippets to demonstrate
    # the agent's ability to render rich content.

    markdown_parts = []

    if show_image:
        image_html = "This is a sample image:\n<img src='https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png' alt='Google Logo' width='272' height='92' />"
        markdown_parts.append(image_html)

    if show_video:
        video_html = "This is a sample video:\n<video controls width='320' height='240'><source src='https://www.w3schools.com/html/mov_bbb.mp4' type='video/mp4'>Sorry, your browser does not support embedded videos.</video>"
        markdown_parts.append(video_html)

    if show_deep_link:
        link_html = "This is a sample deep link:\n<a href='https://www.google.com'>Click here to go to Google</a>"
        markdown_parts.append(link_html)

    if not markdown_parts:
        return {"markdown_string": "You did not request any content to be displayed. Please specify if you want to see an image, video, or link."}

    return {"markdown_string": "\n\n".join(markdown_parts)}

Controles de canais de voz e áudio

Esta seção fornece padrões para controlar o canal de voz e áudio, incluindo áudio pré-gravado, música de espera e configurações de interrupção.

Observações:

  • A codificação de áudio Linear16, mulaw e alaw é compatível como arquivo de áudio.
  • Se você estiver usando um bucket do Cloud Storage que pertence a um projeto na nuvem diferente, a conta de serviço do Pacote de engajamento do cliente service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com precisa receber explicitamente a permissão storage.objects.get para o bucket de destino do Cloud Storage.
  • Use o argumento de entrada interruptable para configurar se o áudio pré-gravado pode ser interrompido pelo usuário final.
  • Para reprodução de música, use o argumento de entrada cancellable para indicar que a reprodução de música deve ser interrompida quando uma nova resposta for gerada pelo agente.

Tocar um áudio pré-gravado específico da marca

Você pode configurar o agente para tocar um arquivo de áudio pré-gravado antes de processar a solicitação do usuário. Você pode usar isso para saudações aprovadas pela marca ou divulgações legais obrigatórias no início da sessão.

Use "transcript": "yyy" para fornecer ao agente o texto de reprodução de áudio, garantindo que ele tenha o contexto necessário para gerar as respostas seguintes.

O uso de "interrupable": false garante que o usuário não possa interromper a reprodução de áudio.

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  for part in callback_context.get_last_user_input():
    if part.text == "<event>session start</event>":
      return LlmResponse.from_parts(parts=[
          Part.from_json(data='{"audioUri": "gs://path/to/audio/file", "transcript": "transcript for the audio file", "interruptable": false}')
      ])
  return None

Tocar música pré-gravada ao executar ferramentas lentas (sem interrupção)

É possível configurar o agente para tocar música enquanto uma ferramenta lenta e "bloqueadora" (como validação e ativação de conta) está em execução. A música para automaticamente quando a ferramenta conclui a execução. Os usuários não podem interagir com o agente enquanto a música está tocando.

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  for index, part in enumerate(llm_response.content.parts):
    if part.has_function_call("slow_tool"):
      play_music = Part.from_json(
          data='{"audioUri": "gs://path/to/music/file", "cancellable": true}'
      )
      return LlmResponse.from_parts(
          parts=llm_response.content.parts[:index] +
          [play_music] + llm_response.content.parts[index:]
      )
  return None

Tocar música pré-gravada ao executar ferramentas assíncronas (permitir interrupção)

É possível configurar um agente para tocar música enquanto executa uma ferramenta de forma assíncrona, como durante a validação e ativação da conta de usuário. A música termina automaticamente quando a ferramenta assíncrona é concluída, desde que o usuário não a tenha interrompido. Os usuários finais podem interromper a música a qualquer momento para continuar a interação com o agente.

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  for part in llm_request.contents[-1].parts:
    if part.has_function_response("async_tool"):
      text = Part.from_text(text="I'm submitting your order, it may take a while.")
      music = Part.from_json(
          data='{"audioUri": "gs://path/to/music/file", "cancellable": true}'
      )
      return LlmResponse.from_parts(parts=[text, music])
  return None

Não permitir que o usuário interrompa determinadas respostas

Você pode impedir que o usuário interrompa o agente quando ele estiver lendo informações importantes (como um aviso legal), mas permitir a interrupção na parte restante da resposta do agente.

Isso usa a ferramenta de sistema customize_response.

Você pode implementar esse comportamento de duas maneiras, dependendo se quer um resultado determinístico:

  1. Callback (determinístico): força a resposta de um callback, conforme mostrado no exemplo.
  2. Instruções (geradas pelo agente): peça ao agente para usar a ferramenta customize_response nas instruções.
def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  for part in callback_context.get_last_user_input():
    if part.text == "<event>session start</event>":
      return LlmResponse.from_parts(parts=[
          Part.from_customized_response(
              content=("Hello, I'm Gemini. Please listen to the following legal "
                       "disclaimer: <LEGAL_DISCLAIMER>"),
              disable_barge_in=True
          ),
          Part.from_text("How can I help you today?")
      ])
  return None

Resposta personalizada para ausência de entrada

Quando um agente atinge o tempo limite de espera por entrada (consulte Tempo limite de silêncio em configurações do aplicativo do agente), uma resposta generativa é usada por padrão. No entanto, é possível verificar se a entrada foi recebida pelo usuário em um callback do modelo antes e fornecer uma resposta condicionalmente.

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  for part in callback_context.get_last_user_input():
    if part.text:
      if "no user activity detected" in part.text:
        return LlmResponse.from_parts(parts=[
            Part.from_text(text="Hi, are you still there?")
        ])

  return None

Tratamento de erros

Esta seção fornece padrões para lidar com erros de ferramentas.

Transferir para outro agente em caso de falhas na ferramenta

Quando uma execução de ferramenta específica falha, é possível transferir de forma determinística para outro agente lidar com a conversa. Essa é uma rede de segurança essencial para proteger a experiência do usuário durante erros de execução.

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  for part in llm_request.contents[-1].parts:
    if (part.has_function_response('authentication') and
        'error' in part.function_response.response['result']):
      return LlmResponse.from_parts(parts=[
          Part.from_text('Sorry something went wrong, let me transfer you to another agent.'),
          Part.from_agent_transfer(agent='escalation agent')
      ])
  return None

Encerrar a sessão corretamente em caso de falhas na ferramenta

Quando a execução de uma ferramenta específica falha, é possível encerrar a sessão normalmente. Isso pode evitar loops infinitos e respostas confusas quando ocorrem falhas críticas na ferramenta.

Exemplo de callback:

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest
) -> Optional[LlmResponse]:
  for part in llm_request.contents[-1].parts:
    if (part.has_function_response('authentication') and
        'error' in part.function_response.response['result']):
      return LlmResponse.from_parts(parts=[
          Part.from_text('Sorry something went wrong, please call back later.'),
          Part.from_end_session(reason='Failure during user authentication.')
      ])
  return None

Contexto e variáveis

Esta seção fornece padrões para usar variáveis de contexto.

Transmitir variáveis de contexto para ferramentas da OpenAPI

A IA personalizada precisa de ferramentas para acessar os dados da sessão do usuário. Confiar no modelo para lembrar e transmitir manualmente detalhes importantes, como IDs de sessão ou variáveis de usuário, é inerentemente não confiável e lento. Em vez disso, o agente pode transmitir variáveis de contexto específicas para ferramentas do OpenAPI. Você pode usar x-ces-session-context para indicar que o valor não precisa ser produzido pelo modelo (e o esquema dele é invisível para o modelo), mas vem de variáveis de contexto.

A tabela a seguir lista os valores disponíveis:

Valor Descrição
$context.project_id O ID do projeto Google Cloud .
$context.project_number O número do projeto Google Cloud .
$context.location O local (região) do agente.
$context.app_id O ID do aplicativo do agente.
$context.session_id O identificador exclusivo da sessão.
$context.variables Todos os valores de variáveis de contexto como um objeto.
$context.variables.variable_name O valor de uma variável de contexto específica. Substitua variable_name pelo nome da variável.
openapi: 3.0.0
info:
  title: test-title
  description: test-description
  version: 1.0.0
paths:
  /test-path/{session_id}:
    post:
      parameters:
      - name: session_id
        in: path
        description: The session ID.
        required: true
        schema:
          type: string
        x-ces-session-context: $context.session_id
      - name: test_variable
        in: query
        description: Specific session variable.
        required: true
        schema:
          type: string
        x-ces-session-context: $context.variables.test_variable
      requestBody:
        description: test-description
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionParams'
      responses:
        '200':
          description: test-response-description
          content:
            application/json:
             schema:
                type: object
                properties:
                  result:
                    type: string
components:
  schemas:
    SessionParams:
      type: object
      description: all context variables
      x-ces-session-context: $context.variables

Comandos dinâmicos

É possível criar agentes com comandos dinâmicos enviados ao modelo usando:

Por exemplo, é possível alterar as instruções do agente com base em se o usuário é um advogado ou um pirata:

Variáveis:

Nome da variável Valor padrão
current_instructions Você é o Gemini e trabalha para o Google.
lawyer_instructions Você é advogado e seu trabalho é contar piadas de pai, mas com um toque de advogado.
pirate_instructions Você é um pirata e seu trabalho é contar uma piada como um pirata.
nome de usuário Desconhecido

Instruções:

The current user is: {username}
You can use {@TOOL: update_username} to update the user's name if they provide
it.

Follow the current instruction set below exactly.

{current_instructions}

Ferramenta Python:

from typing import Optional

def update_username(username: str) -> Optional[str]:
  """Updates the current user's name."""
  set_variable("username", username)

Callback:

def before_model_callback(
  callback_context: CallbackContext,
  llm_request: LlmRequest
) -> Optional[LlmResponse]:
  username = callback_context.get_variable("username", None)

  if username == "Jenn":
    new_instructions = callback_context.get_variable("pirate_instructions")

  elif username == "Gary":
    new_instructions = callback_context.get_variable("lawyer_instructions")

  callback_context.set_variable("current_instructions", new_instructions)