Ferramentas HTTP para agentes de voz: como integrar APIs

Defina uma ação pequena e verificável

Comece pelo resultado que sua equipe precisa: consultar um pedido, verificar um horário ou registrar uma solicitação. Defina quais informações o cliente deve fornecer e o que confirma que a tarefa foi concluída. Consultar um endereço e alterá-lo são tarefas diferentes e podem exigir permissões diferentes.

HTTP é a forma de comunicação usada por muitas dessas conexões; API é a interface pela qual o sistema recebe o pedido e devolve uma resposta. No Tigy, a ferramenta precisa do endereço de acesso, do tipo de ação e dos dados necessários. Peça esses valores ao responsável pelo sistema externo; você não precisa inventá-los nem escrever um programa para definir a necessidade do atendimento.

Explique quando a ferramenta deve ser chamada

Um nome como consultar_pedido ajuda, mas a descrição precisa dizer que a consulta exige um número confirmado pela pessoa. A instrução do agente deve explicar como perguntar pelo dado e como apresentar o retorno.

Evite chamar a ferramenta com valores inventados. Se a pessoa corrigir um número, a próxima consulta deve usar o número corrigido, não o primeiro valor ouvido.

Planeje falhas e repetição

Diferencie resultado vazio, erro e ação concluída. Uma API indisponível deve produzir uma explicação honesta e uma alternativa definida, sem um status fictício.

Para operações que criam registros, a equipe responsável pela API deve tratar tentativas repetidas para evitar duplicações. Uma chamada interrompida pode deixar a conversa sem confirmação mesmo quando o sistema já executou a ação.

Confira a conversa e o sistema de destino

Peça à equipe uma conexão de teste com dados fictícios para ações que criam ou alteram registros. Teste informação ausente, resposta lenta, registro inexistente e correção durante a conversa. Confira o resultado recebido pelo agente e abra o sistema de destino para verificar o registro.

Publique um escopo limitado quando essas situações estiverem resolvidas. Acrescente novas ações a partir de necessidades reais do atendimento, com a mesma clareza de entrada e confirmação.

Teste uma consulta de pedido com sua equipe

Imagine uma loja fictícia. Um cliente fornece o número do pedido e pergunta quando ele chegará. A consulta pode encontrar o pedido em preparação, não encontrar um registro ou falhar porque o sistema está indisponível. Prepare uma resposta diferente para cada caso, sem transformar uma previsão em garantia.

Peça à equipe de integração que prepare esses três casos em um ambiente de teste. Você pode avaliar a conversa e conferir o pedido no sistema da loja. A equipe técnica verifica se os dados foram enviados corretamente e se o agente recebeu o resultado esperado.

Um sucesso HTTP não comprova a tarefa

Uma conexão pode responder que recebeu o pedido e ainda não ter concluído a tarefa. Combine com a equipe os resultados possíveis: registro encontrado, informação ausente, processamento pendente e solicitação recusada. Para uma criação, peça uma referência e um estado que permitam conferir o que realmente aconteceu.

Teste uma resposta parcial. Se o sistema fornece estado, mas não prazo, o agente deve explicar o estado sem inventar a previsão. Se exige aprovação humana, a fala deve descrever a pendência. O mesmo cuidado vale para resposta atrasada: ausência de retorno não prova que uma escrita deixou de acontecer.

Para impedir que uma tentativa repetida crie duas reservas ou dois chamados, a equipe de integração precisa identificar quando se trata do mesmo pedido e permitir consultar o resultado. Combine como testar essa proteção. Ela precisa ser preparada para o sistema conectado; não é uma garantia automática para qualquer integração no Tigy.

Valide comportamento, parâmetros e efeito

Crie casos com dados fictícios: consulta válida, registro ausente, campo inválido, acesso recusado e serviço indisponível. Registre a frase usada, a ferramenta acionada, os parâmetros e o resultado no destino. Para escrita, inclua correção e repetição do pedido.

Confira também quando a ferramenta não deve ser chamada. Uma pergunta sobre política geral pode ser respondida com documentos, sem consultar dados individuais. Uma frase citando um exemplo de cancelamento não necessariamente autoriza cancelar a compra do interlocutor.

No Tigy, configure a ferramenta, selecione-a no agente e salve antes de testar. Confira se as instruções correspondem às ações e resultados combinados com a equipe. Quando o sistema conectado mudar, peça uma revisão da configuração e repita os casos afetados. Uma conexão que continua respondendo pode ter passado a devolver informações com outro significado.

Desenhe uma ferramenta para uma tarefa reconhecível

Uma ferramenta deve representar uma ação que o agente consegue distinguir durante a conversa. “Consultar situação de pedido” informa melhor o propósito do que “executar API”. Nome, descrição e parâmetros ajudam o modelo a decidir quando chamar a ferramenta. A documentação do Tigy destaca essa relação: a escolha acontece a partir das instruções do agente e da definição da ferramenta.

Comece pelo contrato de atendimento. Em que momento a consulta é permitida? Que informação falta antes da chamada? Qual dado identifica o pedido e qual verifica o acesso? O modelo pode coletar parâmetros, mas o servidor responsável precisa conferir autorização e validade. Um cliente citar um identificador não prova que tem direito de consultar o registro.

Evite expor uma ferramenta universal que aceita qualquer caminho ou método solicitado pela conversa. Uma ferramenta com escopo pequeno facilita a avaliação e restringe os efeitos possíveis. Se houver leitura e alteração, use definições que deixem essa diferença clara. “Consultar endereço” e “alterar endereço” exigem condições distintas e não devem ser confundidas por uma descrição vaga.

Explique o significado dos dados pedidos pela ferramenta. Um campo chamado “código” pode identificar cliente, contrato ou pedido. A descrição deve informar qual número usar, como confirmá-lo e o que fazer quando faltar. Combine também como tratar campos opcionais: deixar uma informação em branco não deve fazê-la ser interpretada como outro valor.

Imagine uma empresa fictícia que permite consulta de pedido por código confirmado. A pessoa corrige o último dígito antes do envio. O teste deve mostrar o parâmetro corrigido na chamada e uma resposta compatível com o registro consultado. Uma resposta bem escrita não comprova que a ferramenta recebeu o valor correto. A evidência da integração faz parte da revisão.

Devolva respostas que expliquem o estado da operação

Um retorno de ferramenta precisa permitir distinguir sucesso, ausência de registro, falta de permissão e indisponibilidade. Se todos esses estados aparecem como “erro”, a conversa perde capacidade de explicar o próximo passo. O contrato da API deve oferecer uma interpretação consistente, sem expor detalhes internos ou informação sensível desnecessária.

Para uma consulta, diferencie “pedido não localizado” de “serviço não respondeu”. O primeiro pode pedir uma conferência do código. O segundo pode exigir esperar ou seguir para outro canal. Pedir ao cliente que repita o número quando o servidor está indisponível atribui o problema à pessoa e prolonga a chamada sem necessidade.

Para escrita, o retorno deve indicar se a operação foi confirmada ou ainda precisa de investigação. A conversa só deve anunciar “criado” ou “atualizado” quando houver evidência suficiente. Uma resposta de aceitação pode representar apenas recebimento para processamento posterior. Se essa for a regra do sistema, o agente deve explicar que a solicitação foi recebida, e não que o resultado final já ocorreu.

Planeje a incerteza de uma chamada sem resposta. Uma operação pode ter sido aplicada antes de a conexão interromper. Repetir imediatamente uma criação pode produzir duplicidade. O servidor precisa de um mecanismo para reconhecer a mesma solicitação ou permitir consulta do resultado. A instrução conversacional deve acompanhar esse contrato, incluindo a frase adequada quando não há confirmação.

Limite o tamanho e a relevância do retorno. O agente que precisa explicar um estado de entrega não precisa receber o histórico completo de todos os pedidos do cliente. Além de ampliar exposição, informação irrelevante dificulta interpretar o resultado. Projete uma resposta com o necessário para a tarefa e deixe decisões de autorização no sistema integrado.

Teste também respostas com texto inesperado. Informações vindas de uma integração são dados, não novas instruções para ignorar o escopo. Uma descrição de pedido que contém uma frase imperativa não deve mudar as permissões do agente. A operação seguinte continua sujeita às instruções e ao controle do servidor.

Investigue a integração em camadas

Quando uma ferramenta falhar, confira quatro pontos: o agente escolheu a ação certa, enviou os dados confirmados, recebeu o resultado esperado e explicou esse resultado corretamente? Essa sequência ajuda a separar um problema de conversa de um problema na conexão. Uma chave de acesso recusada, por exemplo, não será corrigida apenas mudando as instruções.

No Tigy, confira se a ferramenta está associada ao agente testado. Peça ao responsável pela integração que revise o endereço, o tipo de ação e a chave de acesso usados na conexão. Utilize um ambiente de teste, principalmente quando a ação cria registros ou envia mensagens. Salvar uma ferramenta não basta se ela não estiver selecionada no agente.

Mantenha exemplos de sucesso, dado ausente, correção do usuário, acesso negado e falha temporária. A integração está pronta quando a operação permitida funciona e as demais condições produzem respostas honestas. Depois de alterar o contrato, repita o conjunto: uma mudança de campo pode manter a chamada tecnicamente válida e alterar o significado comercial do registro.