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ídactool_2(arg_c)-> saídadtool_3(arg_d)-> saídae
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 extraiarg_c - Modelo -> O agente prevê
tool_2(arg_c) tool_2_response.json()é retornado- O agente interpreta
tool_2_response.json()e extraiarg_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:
- Verifique se há uma chamada de ferramenta
end_sessionna resposta do agente. - Crie a parte da ferramenta
post_call_logging. - Insira a chamada de ferramenta
post_call_loggingantes da chamada de ferramentaend_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.comprecisa receber explicitamente a permissãostorage.objects.getpara o bucket de destino do Cloud Storage. - Use o argumento de entrada
interruptablepara configurar se o áudio pré-gravado pode ser interrompido pelo usuário final. - Para reprodução de música, use o argumento de entrada
cancellablepara 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:
- Callback (determinístico): força a resposta de um callback, conforme mostrado no exemplo.
- Instruções (geradas pelo agente): peça ao agente para usar a ferramenta
customize_responsenas 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:
- Variáveis que podem ser usadas para controlar variações de comandos.
- Instruções que incluem referências a variáveis.
- Uma ferramenta que pode atualizar as variáveis com base nos detalhes da conversa.
- Um before_model_callback.
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)