Criar um aplicativo de agente

Este guia mostra as etapas para criar um aplicativo de agente básico que pode responder a consultas de usuários 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 ou crie seu projeto.
  3. Clique em Crie seu primeiro agente de IA ou Criar agente.
  4. Insira "app de clima" como o nome do agente.
  5. Clique em Criar. Se este for o primeiro aplicativo de agente que você criou para o projeto, a criação pode 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 vai usar três agentes:

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

O agente raiz já foi criado, mas você precisa atualizar as configurações dele:

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

Crie 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: "Handles any weather related questions from the user".
  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 a descrição "Lida com as despedidas 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 ao código inline fornecido ao agente. Com as ferramentas, seu agente interage com outros sistemas para buscar, atualizar, formatar ou analisar informações.

Nesta etapa, você vai criar uma ferramenta de clima, que é usada para buscar informações meteorológicas. Para os fins deste 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.

Crie a ferramenta de clima:

  1. Clique no botão de ferramentas no lado direito do criador de agentes.
  2. Clique em + para criar uma ferramenta para o aplicativo do 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, adicione 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 deve fazer.

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

Crie 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

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

  1. No canto inferior esquerdo da tela do console, clique na barra Prévia do agente 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 "como está o tempo em Nova York?" e pressione Enter. O agente responde com informações sobre o clima.
  4. Digite "goodbye" e pressione Enter. O agente encerra 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 captura 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 em +.
  3. Digite "username" como o nome da variável.
  4. Deixe o tipo como Texto.
  5. Clique em Criar.

Agora que você definiu a variável, precisa definir uma ferramenta que permita ao agente atualizar a variável:

  1. Clique no botão de ferramentas no lado direito do criador de agentes.
  2. Clique em + para criar uma ferramenta para o aplicativo do 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 esta 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 seguinte frase à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.

Teste 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 "Hello, my name is Frank".
  3. Insira "Qual é o nível de precisão das suas informações?".

Observe que o agente agora responde usando seu nome em cada resposta. Também é possível abrir 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 é configurado para usar a ferramenta do sistema end_session. 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 você pode usar, em que cada tipo é executado em um ponto específico da conversa.

Neste tutorial, adicione 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 Depois do 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.

Teste 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 "Até mais".

Observe que o agente agora responde usando a mensagem anexada.

Estruture instruções

Para melhorar o comportamento do agente, você pode estruturar todas as instruções dele em um formato XML livre, que é 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 em funcionamento, você tem várias opções de implantação.