Pular para o conteúdo principal

Implementação de tarefas para o Agente de IA

  • Atualizado

Atenção: este conteúdo se refere ao AI Agent, que será descontinuado em 31 de outubro de 2026. A partir dessa data, os agentes baseados no AI Agent serão desativados automaticamente. Recomendamos iniciar a migração para o Blip 2.0 para uso do Studio o quanto antes — fale com o seu gerente de conta para construir o plano de migração.

 

1. Visão Geral

Este documento descreve a arquitetura e o protocolo de comunicação para a criação e execução de tasks (Tarefas) utilizadas por um AI Agent (Agente de IA). O objetivo é capacitar o Agente a interagir com sistemas externos (APIs, bancos de dados) para realizar tarefas concretas.

O fluxo se baseia em um modelo de chamada de ferramenta (tool call), onde o Agente identifica a necessidade de uma ação, solicita sua execução ao Chatbot Builder (Builder) e aguarda um resultado para formular a resposta final ao usuário.

2. Componentes Principais

  • AI Agent (Agente de IA): O núcleo de processamento de linguagem natural. Ele interpreta a intenção do usuário, gerencia o diálogo e orquestra a chamada das tasks quando necessário.

  • Task (Tarefa): Uma definição estruturada de uma capacidade ou ferramenta que o Agente pode utilizar. Cada task corresponde a uma tarefa específica que pode ser executada por um sistema externo.

  • Chatbot Builder (Builder): O ambiente de execução que recebe as solicitações de Task do Agente, processa a lógica de negócio (executando scripts, chamando APIs) e retorna o resultado para o Agente.

3. Estrutura de uma Task

Toda Task é definida por um conjunto de propriedades que guiam seu acionamento e execução.

  • name (string, obrigatório):

    • Descrição: Um identificador único, em formato snake_case, para a Task. Este nome é usado pelo Agente para solicitar a execução da ferramenta correta.

    • Exemplo: verificar_status_pedido, agendar_consulta_medica.

  • context (objeto, opcional):

    • Descrição: Define as pré-condições necessárias para que a Task seja considerada para execução. O Agente só utilizará a Task se as condições no contexto forem atendidas.

    • Exemplo: Para uma Task solicitar_reembolso, o contexto pode exigir que a variável pagamento_status seja igual a "confirmado".

  • parameters (objeto, opcional):

    • Descrição: Define o esquema de dados (schema) com as informações que o Agente precisa extrair da conversa para que a Task possa ser executada com sucesso. Se um parâmetro obrigatório não for fornecido pelo usuário, o Agente irá solicitá-lo explicitamente.

    • Exemplo (para agendar_consulta_medica):

{

    "type": "object",

    "required": [

        "nome",

        "sobrenome",

        "cpf",

        "email",

        "telefone",

        "endereco",

        "data",

        "horario"

    ],

    "properties": {

        "cpf": {

            "type": "string",

            "description": "CPF do usuário"

        },

        "data": {

            "type": "string",

            "description": "data da consulta"

        },

        "nome": {

            "type": "string",

            "description": "Nome do usuário"

        },

        "email": {

            "type": "string",

            "description": "Email do usuário"

        },

        "horario": {

            "type": "string",

            "description": "horario da consulta"

        },

        "endereco": {

            "type": "string",

            "description": "Endereço do usuário"

        },

        "telefone": {

            "type": "string",

            "description": "Telefone do usuário"

        },

        "sobrenome": {

            "type": "string",

            "description": "Sobrenome do usuário"

        }

    }

}

  • Exemplo (parâmetro vazio):

{}

  • Observação: Apesar do campo parameters ser opcional, é necessário passar algum valor, caso não vá usá-lo passar o parâmetro vazio conforme o exemplo acima. 

  • service (string, obrigatório):

    • Descrição: Especifica o endpoint ou serviço que efetivamente realizará a tarefa. No contexto do Builder, isso geralmente se refere a um fluxo ou script específico que será acionado.

    • Exemplo: api_verificacao_cliente.

4. Protocolo de Execução (Tool Call Redirect)

A comunicação entre o Agente e o Builder ocorre através de um redirecionamento (redirect) com um payload JSON bem definido.

Passo 1: Requisição do Agente para o Builder

Quando o Agente determina que uma Task deve ser executada, ele envia uma requisição (POST) para o endpoint do Builder com o seguinte payload (exemplo):

{

    "redirect": "tool_call_redirect",

    "user_message_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",

    "tool_call_id": "tcid_1a2b3c4d5e6f7g8h9i0j",

    "name": "checar_usuario_no_banco_de_dados",

    "parameters": {

        "cpf": "123.456.789-00"

    }

}

Passo 2: Manipulação dos Dados no Builder

Dentro do ambiente do Builder, os dados da requisição são automaticamente extraídos e disponibilizados através de variáveis de sistema. Isso elimina a necessidade de fazer o parse manual do JSON.

As variáveis disponíveis são:

Variável Tipo Descrição Exemplo de Valor
aiAgent.name string O nome da Task solicitada. "checar_usuario_no_banco_de_dados"
aiAgent.parameters objeto Um objeto contendo os parâmetros coletados. {"cpf": "123.456.789-00"}
aiAgent.parameters.cpf string Acesso direto a um parâmetro específico. "123.456.789-00"
aiAgent.message string O envelope de mensagem enviado pela IA

{

    "redirect": "tool_call_redirect",

    "user_message_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",

    "tool_call_id": "tcid_1a2b3c4d5e6f7g8h9i0j",

    "name": "checar_usuario_no_banco_de_dados",

    "parameters": {

        "cpf": "123.456.789-00"

    }

}

Exemplo de uso no Builder:

Para chamar uma API externa, você usaria a variável aiAgent.parameters.cpf para obter o CPF e passá-lo como parâmetro na sua requisição HTTP.

Passo 3: Resposta do Builder para o Agente

Após a execução da lógica de negócio (ex: consulta à API), o Builder deve retornar uma resposta ao Agente. A resposta é um array contendo um ou mais objetos tool, formatado da seguinte maneira (exemplo):

const run = (apiBodyResponse) => {

   

    return [

   {

       "content": `${apiBodyResponse}`,

       "role": "tool"

   }

]

}

  • content (string, obrigatório):

    • O resultado da execução da ferramenta. Recomenda-se que o conteúdo seja uma string JSON, pois isso facilita o processamento pelo Agente e a extração de múltiplos dados.

  • role (string, obrigatório):

    • tool: sinaliza ao Agente que a mensagem é um resultado de ferramenta e não uma resposta direta para o usuário.

    • assistant: resposta final do assistente.

    • user: resposta adicional do usuário, se aplicável. Esse campo contextualiza o agente de IA com a interação do usuário.

O Agente usará o content para formular uma resposta em linguagem natural para o usuário final.

5. Fluxo de Exemplo Completo

  1. Usuário: "Meu CPF é 123.456.789-00, meu cadastro está ativo?"
  1. Agente:
    • Identifica a intenção verificar_cadastro.
    • Encontra a Task checar_usuario_no_banco_de_dados.
    • Extrai o parâmetro cpf da mensagem do usuário.
    • Envia a requisição (tool_call_redirect) para o Builder.
  1. Builder:
    • Recebe a requisição.
    • Acessa o CPF via aiAgent.parameters.cpf.
    • Executa uma chamada a https://api.suaempresa.com/v1/clientes?cpf=12345678900.
    • A API retorna {"status_cliente": "ativo", "data_cadastro": "2023-10-26"}.
    • O Builder formata e envia a resposta tool para o Agente, usando o retorno da API como content.
  1. Agente:
    • Recebe o resultado da ferramenta.
    • Analisa o content: {"status_cliente": "ativo", ...}.
    • Formula a resposta final.
  1. Agente (para o usuário): "Sim, seu cadastro está ativo e foi realizado em 26 de outubro de 2023."

Artigos relacionados