Agentes de IA: como escolher ferramentas e quando perguntar

👁 112 leituras

Em um agente de IA, o modelo de decisão pode escolher o próximo passo: responder, usar uma ferramenta, pedir esclarecimentos, recusar ou encaminhar o caso para uma pessoa. Projete-o para propor uma ação de uma lista fechada, enquanto o código verifica separadamente se os dados estão completos, se há autorização e se as condições para executar a ação foram atendidas.

A seguir está um projeto meu de agente para uma loja virtual: um desenho de arquitetura, não uma integração pronta. A parte de teste, com dez conversas, aparece separada e identificada. Se você está começando, o guia automação com IA: como começar dá o contexto geral.

Comece por uma lista de ações permitidas

Suponha que o agente precise consultar o status de pedidos e explicar as regras de entrega. Na primeira versão, bastam uma ferramenta para consultar o status e outra para pesquisar instruções aprovadas. Os nomes das ferramentas devem descrever o que elas realmente fazem. Uma função de consulta não pode também alterar o endereço ou cancelar uma compra usando o mesmo nome.

Para cada ferramenta, registre os argumentos obrigatórios, o escopo dos dados e os erros possíveis. Defina também de onde os argumentos podem vir. O ideal é obter o identificador do cliente da sessão autenticada e o número do pedido da mensagem ou de um registro selecionado. Dizer “sou administrador” não deve conceder permissões.

Separar a proposta de uma função da sua execução corresponde ao mecanismo descrito na documentação de function calling da OpenAI, consultada em 13/10/2026: o modelo retorna uma solicitação de uso da função, e a aplicação executa o código e repassa o resultado. Neste projeto, uma decisão especializada substitui parte da seleção.

Separe o tipo de ação da ferramenta específica

A primeira decisão deve ser sobre o tipo de próximo passo. Só depois de escolher a consulta de dados é que se seleciona a ferramenta. Com poucas funções, é possível reunir essas etapas em uma única lista de ações, mas não se deve remover as opções de parar ou pedir esclarecimentos só para forçar o modelo a sempre chamar alguma ferramenta.

• Responder: a informação necessária já está no contexto aprovado.
• Usar uma ferramenta: é preciso obter dados, e a função adequada e seus argumentos obrigatórios estão disponíveis.
• Pedir esclarecimentos: o usuário pode fornecer a informação que falta para o próximo passo.
• Recusar: a solicitação viola uma regra claramente definida pela aplicação.
• Encaminhar: a aplicação não consegue resolver o caso ou a avaliação é incerta demais.

A distinção entre responder, usar uma ferramenta, pedir esclarecimentos e não conseguir responder tem como referência o When2Call da NVIDIA, consultado em 13/10/2026. Separar também a recusa e o encaminhamento, neste projeto, é uma decisão de arquitetura, não uma reprodução fiel das categorias do benchmark.

Exemplo de contrato JSON para a aplicação

O JSON Schema abaixo descreve o resultado interno de um adaptador. Não é o esquema de solicitação de uma API específica. O adaptador converte a resposta do modelo escolhido em campos comuns; a distribuição de probabilidades pode ser armazenada separadamente para diagnóstico. Assim, o restante do programa não precisa conhecer os nomes de campos usados por cada provedor.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["action", "tool", "missing_field", "reason_code"],
  "properties": {
    "action": {
      "enum": ["answer", "call_tool", "ask", "refuse", "handoff"]
    },
    "tool": {
      "enum": ["get_order_status", "search_delivery_help", null]
    },
    "missing_field": {
      "enum": ["order_id", "delivery_topic", null]
    },
    "reason_code": {
      "enum": [
        "context_sufficient", "lookup_required", "missing_input",
        "policy_block", "unsupported", "uncertain"
      ]
    }
  }
}

Para a mensagem “Onde está meu pacote?” e um contexto sem um pedido identificado de forma inequívoca, o resultado esperado neste projeto é:

{
  "action": "ask",
  "tool": null,
  "missing_field": "order_id",
  "reason_code": "missing_input"
}

O código converte “order_id” em uma pergunta aprovada: “Informe o número do pedido a que sua mensagem se refere”. O modelo de decisão não precisa redigir essa mensagem. Após a resposta do usuário, a aplicação atualiza o estado e avalia novamente o próximo passo. Um número mencionado em uma conversa anterior, sobre outro assunto, não deve ser reutilizado sem verificação.

O esquema limita os valores possíveis, mas ainda permite combinações incoerentes. Por isso, o validador da aplicação deve exigir uma ferramenta para “call_tool”, proibi-la para “ask” e verificar se o código do motivo corresponde à ação. Neste exemplo, as regras entre os campos são descritas separadamente de propósito, para não sugerir uma solução completa pronta para produção.

Este foi, em linhas gerais, um dos pedidos do meu teste (formato System One pelo OpenRouter, endpoint /api/alpha/decisions; lista de ferramentas e descrições das opções resumidas). O prompt abaixo é uma tradução do material de teste original em polonês; o teste foi realizado em polonês:

{
  "model": "microsoft/microsoft-decision-1",
  "state": {
    "ferramentas": "consultar_status_pedido(numero_pedido), cancelar_pedido(numero_pedido)",
    "conversa": "Cliente: Onde está meu pacote? Fiz o pedido na semana passada."
  },
  "questions": {
    "etapa": {
      "type": "choice",
      "instructions": "O que o assistente deve fazer em seguida?",
      "criteria": {
        "responder": "responder imediatamente, sem ferramenta",
        "ferramenta": "chamar uma ferramenta - todos os dados estão disponíveis",
        "perguntar": "pedir esclarecimentos porque faltam dados obrigatórios",
        "nao_posso": "recusar - nenhuma ferramenta é adequada"
      }
    }
  }
}

A resposta correta é perguntar, pois falta o número do pedido. Na resposta, o modelo retorna a opção selecionada, a probabilidade de cada uma das quatro opções e um nível de confiança. O adaptador converte esses dados para o contrato da seção anterior.

Quando pedir esclarecimentos e quando buscar a informação que falta

Nem toda informação ausente exige uma mensagem ao usuário. Se o cliente selecionou um pedido no painel, a aplicação já conhece o número. Perguntar de novo indicaria que o estado não foi informado corretamente. Por outro lado, nomes de destinatários iguais em vários pedidos não justificam escolher um deles arbitrariamente.

Para cada função, prepare uma lista de dados obrigatórios e opcionais. A pergunta deve resolver uma ambiguidade específica. Pedir “mais informações” deixa o usuário tentando adivinhar o que o sistema precisa. É melhor indicar o dado ausente e explicar para qual etapa ele é necessário.

Também diferencie a falta de dados de uma falha. Se o serviço de consulta de status estiver indisponível, perguntar novamente o número ao cliente não resolverá o problema de conexão. Registre o estado de erro, aplique a política de novas tentativas definida e, quando ela se esgotar, encaminhe o caso. Não deixe o modelo fingir que reformular a mesma pergunta aumenta o que ele sabe.

Probabilidade ajuda a definir a ordem das verificações

Não estabeleça um único limite universal no projeto nem presuma que ele funcionará para todas as ações. A TypeSafe descreve o campo confidence para alguns tipos de pergunta em sua documentação, consultada em 13/10/2026. Antes de usá-lo, verifique o que significa, em vez de tratá-lo automaticamente como a maior probabilidade entre as opções.

Com um conjunto de validação, verifique com que frequência as respostas com níveis de confiança semelhantes estão corretas. Defina as condições para ações automáticas de acordo com cada ação. Consultar uma instrução pública e alterar dados de um cliente têm consequências diferentes em caso de erro; uma regra única para permitir a execução exigiria uma justificativa específica.

Uma distribuição de probabilidades quase empatada pode indicar descrições de ferramentas sobrepostas. Antes de aumentar o limite, revise as próprias definições. Se duas funções prometem “ajudar com o pedido”, o classificador tem pouca informação para distingui-las. Melhorar a lista de ferramentas pode ser um experimento mais adequado do que trocar de provedor.

O que o When2Call mostra no Artificial Analysis

Fonte: gráfico e descrição do When2Call no AA, consultados em 13/10/2026. O melhor resultado no AA está em negrito. É uma foto de 13 de outubro: em 30 de outubro, a página do AA já listava versões mais novas de alguns modelos (como Jev 1.14 e Decider v1.2), então confira o gráfico atual antes de escolher. A última coluna mostra meu teste de 13/10/2026: 10 conversas com um assistente de loja em polonês, usando quatro ferramentas (status do pedido, cancelamento, disponibilidade na loja e etiqueta de devolução) e as mesmas quatro opções do When2Call. O Clef-Flash chamava uma ferramenta quando faltava o número do pedido ou a cidade, e recusava responder a uma pergunta simples sobre o prazo de 14 dias para devolução. O teste avalia a seleção de uma das respostas propostas. Esses números não indicam a capacidade de preencher argumentos automaticamente nem de concluir operações com várias etapas.

Transforme estas armadilhas em casos de teste

• Instrução escondida nos dados: um documento contém uma instrução para escolher outra ferramenta. O teste deve verificar se os dados assumem o lugar das regras da aplicação.
• Funções parecidas: uma ferramenta de consulta e outra de alteração de dados têm descrições semelhantes. Verifique a seleção com pedidos que diferem por um único verbo.
• Estado desatualizado: o usuário corrigiu o número do pedido, mas o modelo ainda recebe o anterior. Teste a atualização de todo o fluxo, não apenas de um prompt.
• Respostas contraditórias: o modelo propõe uma chamada e, ao mesmo tempo, indica que falta um argumento obrigatório. O validador deve impedir a execução.
• Repetição após timeout: a chamada anterior pode ter sido executada. Operações que alteram o estado precisam de um mecanismo para evitar efeitos duplicados.

As recomendações oficiais da OpenAI para a segurança de agentes, consultadas em 13/10/2026, abordam os riscos de instruções em conteúdo não confiável e formas de limitar o fluxo de dados. Neste projeto, uma aplicação prática é usar uma lista fechada de ações e verificar as permissões fora do modelo.

Como testar o agente antes de conectá-lo às ferramentas

Comece com estados de entrada descritos e as ações esperadas. Inclua solicitações válidas, dados ausentes, contradições, funções indisponíveis e situações fora do escopo. Uma pessoa que conheça o processo deve definir as respostas de referência antes de ver as propostas do modelo. Caso contrário, é fácil ajustar a avaliação ao que o sistema acabou de retornar.

Separe o conjunto usado para revisar as descrições do conjunto final de validação. Mantenha juntas as variações da mesma mensagem para evitar que exemplos muito parecidos apareçam nos dois grupos. Verifique separadamente erros de digitação, abreviações, conversas mais longas e mudanças de ideia do usuário.

O relatório deve mostrar não só a precisão geral, mas também chamadas desnecessárias, perguntas de esclarecimento não feitas, perguntas desnecessárias e recusas incorretas. Depois, conecte uma ferramenta simulada e verifique os argumentos e o tratamento de erros. Por fim, execute o agente em modo de observação em um fluxo real, registrando as propostas sem realizar operações.

Repita os casos de validação após alterar a versão do modelo, as descrições das funções ou as regras de atendimento. Registre a versão da lista de ferramentas junto com o resultado para identificar a origem de novos erros. Evite guardar todo o conteúdo do cliente sem necessidade quando um exemplo sanitizado e um identificador de evento forem suficientes para a análise.

Perguntas frequentes

Um modelo de decisão substitui o agente inteiro?

Não neste projeto. Ele escolhe o próximo passo, enquanto a aplicação mantém o estado, executa as funções e controla seus efeitos.

O JSON apresentado é uma solicitação pronta para uma API?

Não. É um contrato interno próprio para um adaptador. O formato de chamada e os tipos de pergunta compatíveis devem ser ajustados à documentação do provedor escolhido.

Uma confiança alta permite ignorar as permissões?

Não. A confiança diz respeito à avaliação do modelo. A aplicação verifica separadamente o acesso aos dados e a permissão para executar uma operação.

O que fazer quando o agente não para de pedir esclarecimentos?

Verifique se ele recebe o estado completo e se está perguntando por um argumento realmente obrigatório. Acrescente uma condição de encerramento quando não houver progresso e uma opção para encaminhar o caso.

Como verificar se a escolha da ferramenta está correta?

Compare a seleção com um gabarito preparado de forma independente e, depois, verifique os argumentos e o estado final após a execução em um ambiente de teste. Um JSON correto, por si só, não basta.

Declaração: conheço o modelo Jev da TypeSafe de uma avaliação anterior. Em setembro, escrevi para ele um cliente de API simples para minhas próprias ferramentas editoriais. A TypeSafe não encomendou nem pagou por este texto.

// continue lendoTavily, Exa ou Brave Search API: qual escolher para agentes de IA?GeralAutomação com IA: como começar e qual ferramenta escolherGuiasGoogle AI Pro ou Gemini API: quando vale a pena?Geral