Criar um aplicativo de agente

Este guia mostra as etapas para criar um aplicativo de agente básico que possa responder a consultas do usuário sobre o clima.

Antes de começar

Conclua as instruções de configuração antes de seguir este guia.

Criar um aplicativo de agente

Crie um aplicativo de agente e um agente raiz:

  1. Abra o console do CX Agent Studio.
  2. Selecione o projeto.
  3. Clique em Criar agente ou Novo agente.
  4. Forneça "aplicativo de clima" como o nome do agente.
  5. Clique em Criar. Se este for o primeiro aplicativo de agente criado para o projeto, a criação poderá levar de 1 a 2 minutos. O criador de agentes é mostrado e um agente raiz é criado para você.

Criar a hierarquia de agentes

Este aplicativo de agente usará três agentes:

  • Agente raiz para cumprimentar o usuário e delegar a outros subagentes.
  • Agente de clima para responder a perguntas relacionadas ao clima.
  • Agente de despedida para concluir a conversa.

O agente raiz já foi criado, mas é necessário atualizar as configurações dele:

  1. Clique na barra de título do agente raiz.
  2. Opcionalmente, você pode mudar o nome do agente.
  3. Insira a descrição: "Lida com saudações simples e delega a outros agentes".
  4. Clique em Salvar e feche o painel de configurações.

Criar o agente de clima:

  1. Clique no botão + na parte de baixo do agente raiz.
  2. Clique em Adicionar novo subagente.
  3. Clique na barra de título do novo agente.
  4. Mude o nome para "Agente de clima".
  5. Insira a descrição: "Lida com todas as perguntas relacionadas ao clima do usuário".
  6. Clique em Salvar e feche o painel de configurações.

Da mesma forma, crie outro subagente do agente raiz chamado "Agente de despedida" com uma descrição de "Lida com despedidas e adeus do usuário".

Captura de tela da hierarquia de agentes

Criar uma ferramenta de clima

As ferramentas são usadas para conectar o agente a sistemas externos ou códigos em linha fornecidos ao agente. Isso permite que o agente interaja com outros sistemas para buscar, atualizar, formatar ou analisar informações.

Nesta etapa, você cria uma ferramenta de clima, que é usada para buscar informações sobre o clima. Para este guia, essa ferramenta tem uma resposta simulada para o usuário. Em um aplicativo de clima real, essa ferramenta acessaria um servidor externo para receber informações.

Criar a ferramenta de clima:

  1. Clique no botão de ferramentas no lado direito do criador de agentes.
  2. Clique em + para criar uma nova ferramenta para o aplicativo de agente.
  3. Clique em Código Python.

  4. Cole o seguinte código:

    def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city.

  Returns:
    dict: A dictionary containing the weather information.
          Includes a 'status' key ('success' or 'error').
          If 'success', includes a 'report' key with weather details.
          If 'error', includes an 'error_message' key.
  """
  city_normalized = city.lower().replace(" ", "")

  mock_weather_db = {
    "newyork": {"status": "success",
      "report": "The weather in New York is sunny and 25°C."},
    "london": {"status": "success",
      "report": "It's cloudy in London and  15°C."},
    "tokyo": {"status": "success",
      "report": "Tokyo is experiencing light rain and 18°C."},
  }
  if city_normalized in mock_weather_db:
    return mock_weather_db[city_normalized]
  else:
    return {"status": "error",
      "error_message": f"No weather information for '{city}'."}

  5. Clique em Criar.

Agora, é necessário adicionar essa ferramenta ao agente de clima:

  1. Clique no botão + na barra de título do agente de clima.
  2. Clique em Adicionar ferramenta.
  3. Selecione a ferramenta de clima.

Criar instruções do agente

Cada agente tem um conjunto de instruções que definem o que ele precisa fazer.

Ao fornecer instruções que fazem referência a um agente, use a sintaxe {@AGENT: Agent name}. Para fazer referência a ferramentas, use {@TOOL: tool_name}.

Criar instruções para cada agente:

  1. Clique no botão + na barra de título do agente raiz.
  2. Clique em Adicionar instruções.

  3. Insira as seguintes instruções:

    You are a helpful weather application.
Your job is to greet the user and delegate to other sub-agents as needed.
When greeting the user, describe how you can help them.
When the user asks for the weather, delegate to {@AGENT: Weather agent}.
When the user is ending the conversation,
delegate to {@AGENT: Farewell agent}.
Handle only weather requests, greetings, and farewells.

  4. Clique em Criar.

  5. Da mesma forma, adicione as seguintes instruções para o agente de clima:

    You are a helpful weather agent.
When the user asks for the weather in a specific city,
use {@TOOL: get_weather} to find the information.
If the tool returns an error, inform the user politely.
If the tool is successful, present the weather report clearly.

  6. Da mesma forma, adicione as seguintes instruções para o agente de despedida:

    You are the Farewell Agent.
Your ONLY task is to provide a polite goodbye message.

Testar o agente

O aplicativo de agente agora está pronto para interações usando o simulador:

  1. No canto inferior esquerdo da tela do console, clique na barra Agente de visualização para expandir a janela, se ela ainda não estiver expandida.
  2. Digite "olá" e pressione Enter. O agente responde com uma saudação genérica.
  3. Digite "qual é o clima em Nova York?" e pressione Enter. O agente responde com informações sobre o clima.
  4. Digite "adeus" e pressione Enter. O agente conclui a conversa.

Usar variáveis

As variáveis são usadas para armazenar e recuperar dados de conversas em tempo de execução. Isso permite que os agentes se lembrem de informações em várias rodadas de conversa, o que leva a interações mais contextuais. Para esse agente, você vai criar uma variável que capture o nome do usuário.

Para criar a variável:

  1. Clique no botão de variáveis no lado direito do criador de agentes.
  2. Clique em Criar uma variável ou +.
  3. Digite "nome de usuário" como o nome da variável.
  4. Deixe o tipo como Texto.
  5. Clique em Criar.

Agora que você definiu a variável, é necessário definir uma ferramenta que permita que o agente a atualize:

  1. Clique no botão de ferramentas no lado direito do criador de agentes.
  2. Clique em + para criar uma nova ferramenta para o aplicativo de agente.
  3. Clique em Código Python.

  4. Cole o seguinte código:

    from typing import Optional

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

  5. Clique em Criar.

Adicione essa ferramenta ao agente raiz:

  1. Clique no botão + na barra de título do agente raiz.
  2. Clique em Adicionar ferramenta.
  3. Selecione a ferramenta update_username.

Adicione a frase a seguir às instruções do agente raiz, que faz referência à variável usando a sintaxe {variable_name}:

If provided, the current user is {username},
and you should address them with this name.
You can use {@TOOL: update_username} to update the user's name if they provide
it.

Você pode testar o agente novamente para verificar o uso da variável:

  1. Clique em Iniciar nova conversa na barra de título do simulador.
  2. Insira "Olá, meu nome é Frank".
  3. Insira "Quão precisas são suas informações?".

O agente agora responde usando seu nome para cada resposta. Você também pode expandir as seções Etapas da conversa do simulador, em que é possível verificar a execução da ferramenta, entre outras coisas.

Controlar como encerrar a sessão

Por padrão, cada um dos seus agentes está configurado para usar a end_session ferramenta de sistema, no entanto, é possível melhorar a confiabilidade e o controle de como encerrar a sessão criando instruções explícitas.

Remova as ferramentas end_session dos agentes raiz e de clima clicando no x ao lado da ferramenta em cada agente. Isso garante que apenas o agente de despedida encerre a sessão.

Adicione o seguinte às instruções do agente de despedida:

After providing the goodbye message and confirming the user has no more
questions, execute the tool {@TOOL: end_session}(reason="success").

Usar um callback para aplicar uma mensagem estática no final da sessão

Os callbacks fornecem um mecanismo para se conectar ao processo de execução de um agente específico usando código Python. Eles permitem observar, personalizar e até mesmo controlar o comportamento do agente em pontos específicos e predefinidos.

Há vários tipos de callback que podem ser usados, em que cada tipo de callback é executado em um ponto específico da rodada de conversa.

Para este tutorial, anexe uma mensagem estática à resposta do modelo ao encerrar a sessão:

  1. Clique na barra de título do agente de despedida.
  2. Clique em Adicionar callback.
  3. Selecione Após o LLM.

  4. Insira este código:

    SURVEY_MESSAGE = "Click here to take our post call survey."

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'):
      return LlmResponse.from_parts(parts=[
        *llm_response.content.parts,
        Part.from_text(SURVEY_MESSAGE)

    ])
  return None

  5. Clique em Concluído.

  6. Clique em Salvar.

Você pode testar o agente novamente para verificar o comportamento de encerramento da sessão:

  1. Clique em Iniciar nova conversa na barra de título do simulador.
  2. Insira "Olá".
  3. Insira "Adeus".

O agente agora responde usando a mensagem anexada.

Estruture instruções

Para melhorar o comportamento do agente, você pode estruturar todas as instruções do agente em um formato XML de forma livre que seja ideal para o processamento do modelo. Faça o seguinte para cada um dos seus agentes:

  1. Abra o painel de instruções de um agente.
  2. Clique no botão Estrutura no canto superior direito.
  3. Clique em Salvar.

Implantar

Depois de ter um agente funcional, você tem várias opções de implantação.