As ferramentas permitem conectar seus agentes de IA a APIs e sistemas externos, possibilitando consultar informações ou executar ações durante uma conversa com o cliente. Por exemplo, você pode configurar uma ferramenta para consultar o status de um pedido, verificar informações de cadastro ou buscar dados em um sistema interno. 

1. Para acessar vá em Zenvia Customer Cloud > Agentes de IA.

2. Clique em Ferramentas.

3. Selecione Criar ferramenta +. 

Configuração da ferramenta

Nesta etapa, você deverá informar os dados que identificam a ferramenta e explicam ao agente como utilizá-la.

1. Ref: Informe uma referência única para identificar a ferramenta. Esse identificador é utilizado pelo modelo de IA para chamar a ferramenta durante a conversa. Utilize um nome curto, sem espaços, preferencialmente em um dos seguintes padrões:

• kebab-case: consultar-pedido
• snake_case: consultar_pedido
• camelCase: consultarPedido
• PascalCase: ConsultarPedido

Exemplo: consultar-pedido

⚠️ Atenção:  A referência deve ser única dentro da organização e não pode ser igual à referência de uma ferramenta nativa da plataforma.

2. Nome: Informe um nome para identificar a ferramenta na plataforma. Prefira nomes objetivos, que indiquem claramente a finalidade da integração. Exemplo: Consultar pedido.

3. Descrição: Explique o que a ferramenta faz e em quais situações o agente deverá utilizá-la. Esse campo é importante porque orienta o modelo de IA sobre quando chamar a ferramenta.

Exemplo: "Consulta o status de um pedido utilizando o número informado pelo cliente. Utilize esta ferramenta sempre que o cliente quiser saber a situação de uma compra."

💡Dica: Escreva uma descrição clara e específica. Evite textos genéricos, pois o agente precisa entender em quais situações aquela ferramenta será necessária.

4. Argumentos: Clique em Adicionar argumento para incluir os parâmetros necessários. Configure os argumentos de acordo com as informações exigidas pela API que será integrada. Os argumentos são as informações que o agente deverá fornecer para executar a ferramenta. Por exemplo, para consultar um pedido, o agente precisa receber o número correspondente.

Exemplo: para uma ferramenta de consulta de pedidos, você pode utilizar:

• Argumeto: orderld.
• Finalidade: Número de identificação do pedido que será consultado. 

A descrição do argumento deve deixar claro qual informação o agente precisa obter do cliente ou de outra fonte. Os argumentos configurados ficam disponíveis na requisição por meio do namespace input. Por exemplo, para utilizar o número do pedido informado pelo agente, use: {{input.orderId}}.Se a ferramenta não precisar receber nenhum parâmetro, não é necessário adicionar argumentos. Nesse caso, o modelo poderá chamar a ferramenta sem informar parâmetros. 

5. Configuração da requisição: Defina como a plataforma enviará uma solicitação para a API externa. Antes de preencher os campos, consulte a documentação da API que deseja integrar para identificar o método, o endereço, os cabeçalhos e os parâmetros necessários.

5.1 Método: Selecione o método HTTP utilizado pela API. O método determina o tipo de operação que será realizada. Os métodos disponíveis incluem:

• GET: utilizado para consultar ou recuperar informações.
• POST: utilizado para enviar informações ou criar registros.

• PUT: utilizado para atualizar informações.

• DELETE: utilizado para excluir registros.

Exemplo: para consultar o status de um pedido, selecione GET.

5.2 URL: Informe o endereço do endpoint da API que será chamado pela ferramenta. O endpoint deve corresponder à operação que você deseja executar.

Exemplo: https://api.exemplo.com/pedidos/{{input.orderId}}. Nesse exemplo, a URL utiliza a variável {{input.orderId}} para inserir dinamicamente o número do pedido informado pelo agente. Assim, cada chamada poderá consultar um pedido diferente.

⚠️ Atenção:  Utilize a URL disponibilizada na documentação da API do sistema que será integrado.

5.3 Cabeçalhos: Os cabeçalhos (headers) permitem enviar informações adicionais na requisição, como dados de autenticação e o formato do conteúdo.

Para adicionar um cabeçalho:

1. Na seção Cabeçalhos, clique em Adicionar cabeçalho.

2. Informe o nome do cabeçalho.

3. Informe o respectivo valor.

Exemplo de autenticação:

Nesse exemplo, o token é utilizado para autenticar a comunicação com a API externa. Os cabeçalhos necessários variam conforme a documentação e as regras de autenticação de cada sistema. Informações confidenciais, como tokens de autenticação, são mascaradas após serem salvas.

5.4 Corpo: Este campo permite configurar as informações que serão enviadas no conteúdo da requisição. Ele é utilizado principalmente em métodos como POST e PUT, quando a API exige o envio de dados.

Exemplo:

{

  "orderId": "{{input.orderId}}"

}

Nesse exemplo, o número do pedido é enviado no corpo da requisição.

⚠️ Atenção:  Requisições GET não utilizam corpo. Para configurar um corpo, selecione um método HTTP compatível e consulte a documentação da API integrada.

5.5 Tempo limite (ms): Determina quanto tempo a plataforma aguardará pela resposta da API antes de encerrar a requisição. O campo é configurado em milissegundos (ms).

As configurações disponíveis são:

• Valor padrão: 15.000 ms (15 segundos).
• Valor máximo: 60.000 ms (60 segundos).

Exemplo: se você configurar o tempo limite como 10000, a plataforma aguardará até 10 segundos pela resposta da API. Considere o tempo médio de resposta do sistema integrado ao definir esse valor.

5.6 Marcadores encontrados na requisição: Apresenta as variáveis identificadas na configuração. Caso nenhum marcador seja encontrado, verifique se as variáveis foram informadas corretamente na URL, nos cabeçalhos ou no corpo.

💡Dica: Se precisar utilizar uma informação fornecida pelo cliente, configure o argumento correspondente e utilize a variável {{input.nomeDoArgumento}} na requisição.

Por fim, dê um Salvar. Após o cadastro, a ferramenta ficará disponível na organização para ser associada aos agentes.

⚠️ Atenção: Cadastrar uma ferramenta não significa que ela já esteja disponível para todos os agentes. Para utilizá-la, é necessário adicioná-la à configuração do agente e salvar uma nova versão.