Ir para o conteúdo
TokIQ
Agentes

Tool calling em LLMs: function calling e agentes de IA

Como funciona o tool calling em LLMs, como escrever descrições de ferramentas que o modelo usa bem, como os loops de agentes rodam e param e as falhas a prever.

TokIQ Editorial6 min de leitura
Neste artigo
  1. Como é a definição de uma ferramenta?
  2. Como escrever descrições de ferramentas que o modelo usa corretamente?
  3. Como funciona o loop de um agente?
  4. Como um agente deve decidir quando parar?
  5. Quais são as falhas mais comuns de agentes?
  6. E a segurança?
  7. Você realmente precisa de um agente?
  8. Onde entra o MCP?

O tool calling (ou function calling) permite que um modelo de linguagem peça à sua aplicação que execute uma função: você descreve as ferramentas disponíveis com nomes, descrições e schemas de parâmetros, o modelo responde com uma chamada estruturada como get_order_status(order_id="A-1042"), seu código a executa e o resultado volta ao modelo. Um agente é esse mesmo mecanismo em loop, em que o modelo continua escolhendo ferramentas e lendo resultados até decidir que a tarefa terminou.

O modelo nunca executa nada por conta própria. Ele produz um texto que, por acaso, é um pedido bem formado. Tenha isso em mente e a maioria das decisões de projeto sobre agentes fica mais clara, principalmente as de segurança.

Como é a definição de uma ferramenta?

Entre OpenAI, Anthropic e Google os formatos de requisição diferem um pouco, mas toda definição de ferramenta tem as mesmas três partes: um nome, uma descrição em linguagem natural e um JSON Schema para os parâmetros.

Uma definição fraca:

{
  "name": "search",
  "description": "Busca coisas.",
  "parameters": {
    "type": "object",
    "properties": { "q": { "type": "string" } }
  }
}

Uma melhor:

{
  "name": "search_help_center",
  "description": "Busca em texto completo nos artigos públicos da central de ajuda do app Ledgerly. Use quando o usuário perguntar como um recurso funciona ou como resolver um problema. Não busca nos dados da conta do usuário; para isso use get_account_summary. Devolve até 5 artigos com título, URL e um trecho curto.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Uma frase de busca curta em inglês, por exemplo 'export invoices to CSV'. Reformule a pergunta do usuário em palavras-chave em vez de passá-la literalmente."
      }
    },
    "required": ["query"]
  }
}

A descrição é um prompt. O modelo a lê para decidir quando usar a ferramenta, o que passar e o que esperar de volta. A documentação de tool use da Anthropic ressalta que descrições detalhadas são o fator mais importante para o desempenho de uma ferramenta, e isso bate com o que se vê na prática.

Como escrever descrições de ferramentas que o modelo usa corretamente?

Responda às perguntas que um desenvolvedor novo faria antes de chamar uma API desconhecida:

  • O que ela faz e o que não faz? "Não busca nos dados da conta do usuário" evita uma classe inteira de chamadas erradas.
  • Quando usá-la no lugar de uma ferramenta parecida? Ferramentas sobrepostas são a principal causa de escolha errada. Se duas ferramentas poderiam tratar um pedido, diga qual vence.
  • O que significam os parâmetros, com exemplos? Formatos (datas ISO, centavos vs reais, IDs com ou sem prefixo) e um valor de exemplo para tudo que for ambíguo.
  • O que ela devolve? Inclusive o que significa um resultado vazio.
  • Ela tem efeitos colaterais? "Envia o e-mail imediatamente; não pode ser desfeito" muda o comportamento de um modelo cuidadoso e deve mudar a forma como seu app a controla.

Dê nomes às ferramentas que fiquem claros lado a lado: search_help_center, get_account_summary, create_support_ticket. Evite nomes genéricos como search ou run, que convidam ao uso incorreto.

Devolva também erros úteis. Se uma chamada falha, um resultado de ferramenta como "error": "order_id must look like A-1234; got 1234" permite que o modelo corrija a própria chamada no passo seguinte. Um 500 seco não permite.

Como funciona o loop de um agente?

O loop básico, que a maioria dos frameworks de agentes implementa com variações:

  1. Envie ao modelo a conversa, o prompt de sistema e as definições das ferramentas.
  2. Se o modelo responder só com texto, o turno terminou.
  3. Se responder com uma ou mais chamadas de ferramenta, seu código as valida e executa.
  4. Acrescente os resultados à conversa como resultados de ferramenta.
  5. Volte ao passo 1.

Esse padrão, que intercala raciocínio com ações e observações, foi descrito no artigo do ReAct (Yao et al., 2022) e é a base da maioria dos agentes criados desde então. As APIs modernas o suportam nativamente, inclusive com várias chamadas de ferramenta em um único turno.

O loop é simples. Fazê-lo se comportar bem é onde está o trabalho.

Como um agente deve decidir quando parar?

Dois tipos de condição de parada, e você precisa dos dois.

No nível da tarefa, no prompt. Diga ao agente o que significa "pronto":

Você terminou quando a pergunta do usuário estiver respondida ou quando
tiver determinado que ela não pode ser respondida com as ferramentas
disponíveis. Se, depois de duas buscas, você não tiver encontrado artigos
relevantes, pare de buscar e diga ao usuário o que tentou.
Faça uma pergunta de esclarecimento ao usuário em vez de adivinhar quando
o pedido puder se referir a mais de uma conta ou fatura.

Sem uma orientação assim, os agentes tendem a parar cedo demais (respondendo com o próprio conhecimento, sem buscar) ou a não parar (repetindo a busca com pequenas variações, na esperança de um resultado melhor).

Limites rígidos, no código. Um número máximo de iterações, um orçamento de tokens ou de custo e um timeout de relógio. Quando um limite é atingido, encerre com elegância: devolva o que foi encontrado até ali e diga que a tarefa não foi concluída. Nunca dependa só do modelo para parar um loop que gasta dinheiro.

Quais são as falhas mais comuns de agentes?

Escolha errada de ferramenta. Em geral causada por ferramentas sobrepostas ou descrições vagas. Conserte primeiro as descrições; se não bastar, reduza o número de ferramentas disponíveis para essa tarefa.

Argumentos alucinados. O modelo inventa um ID de pedido porque o usuário disse "meu último pedido". Instrua-o a procurar IDs com uma ferramenta ou perguntar ao usuário e valide os argumentos no código antes de executar.

Looping. O agente repete uma chamada que falha com pequenas variações. Detecte chamadas idênticas ou quase idênticas repetidas no seu loop e interrompa, e faça os erros das ferramentas serem informativos o bastante para permitir a correção.

Sucesso prematuro. O agente informa "Pronto, atualizei o registro" quando a chamada de atualização na verdade falhou. Faça os resultados das ferramentas serem explícitos sobre sucesso ou falha e, em tarefas importantes, verifique o resultado com uma chamada de leitura separada.

Inchaço de contexto. Os resultados de ferramentas podem ser enormes (uma página web inteira, uma consulta de 2,000 linhas). Loops longos enchem o contexto com saídas antigas e o modelo perde de vista o objetivo original. Reduza ou resuma os resultados das ferramentas antes de devolvê-los e retorne apenas os campos de que o modelo precisa.

Ferramentas demais. A precisão tende a cair conforme você adiciona ferramentas, sobretudo parecidas. Dê a cada tarefa o menor conjunto útil ou carregue as ferramentas dinamicamente conforme o pedido.

E a segurança?

Cada ferramenta é uma capacidade que um prompt injection pode tomar emprestada. Se o seu agente lê páginas web ou e-mails e também tem uma ferramenta que envia mensagens, um atacante que escreva o texto certo em uma página pode conseguir que ele envie mensagens.

Regras práticas:

  • Autorize no código, não no prompt. A ferramenta deve rodar com as permissões do usuário final, para que um modelo enganado não alcance dados que o usuário não alcançaria.
  • Confirme as ações importantes. Pagamentos, exclusões, mensagens de saída, mudanças de permissão: mostre ao usuário exatamente o que vai acontecer e exija aprovação.
  • Valide os argumentos. Validação de schema mais regras de negócio (limites de valor, destinatários permitidos) antes de executar.
  • Separe ferramentas de leitura e de escrita. Uma etapa de pesquisa que só tem ferramentas de leitura não consegue causar dano, por mais confuso que o modelo fique.

Você realmente precisa de um agente?

Muitas vezes não. Se os passos são conhecidos de antemão (recuperar, depois resumir, depois formatar), um pipeline fixo de chamadas individuais ao modelo é mais barato, mais rápido, mais fácil de testar e de depurar. Os agentes justificam sua complexidade quando o caminho depende de fato de resultados intermediários: o modelo precisa consultar algo para saber o que consultar em seguida.

Uma progressão razoável: comece com um único prompt; adicione recuperação se precisar de fatos (o que é RAG); adicione uma única chamada de ferramenta para uma ação; só então monte um loop.

Onde entra o MCP?

O Model Context Protocol, apresentado pela Anthropic no final de 2024 e adotado desde então por outros fornecedores e ferramentas, padroniza como as aplicações expõem ferramentas e dados aos modelos. Ele resolve a parte da infraestrutura: uma definição de servidor utilizável por muitos clientes. Não muda nenhum dos conselhos acima. Uma ferramenta mal descrita é igualmente confusa via MCP, e conectar muitos servidores de terceiros acrescenta tanto capacidades quanto superfície de ataque.

Para o lado da saída das chamadas de ferramenta (schemas, modos estritos, validação), veja como obter JSON confiável de LLMs. O tópico de ferramentas e agentes transforma essas decisões de projeto em questões de prática.

Perguntas frequentes

O que é tool calling em LLMs?

Tool calling, também chamado de function calling, permite que um modelo responda com um pedido estruturado para executar uma função que você definiu, como consultar um banco de dados ou enviar um e-mail. Seu código executa a função e devolve o resultado ao modelo, que então continua.

O modelo executa a ferramenta por conta própria?

Não. O modelo apenas gera o nome da ferramenta e os argumentos. Sua aplicação decide se vai executá-la, executa e devolve o resultado, e é por isso que as verificações de permissão pertencem ao seu código.

Qual é a diferença entre tool calling e um agente de IA?

Tool calling é uma única capacidade: o modelo pede que uma função seja executada. Um agente é um loop em que o modelo decide repetidamente qual ferramenta chamar em seguida, observa os resultados e continua até a tarefa terminar ou um limite ser atingido.

Quantas ferramentas posso dar a um agente?

Não há um limite fixo, mas a precisão tende a cair à medida que as listas de ferramentas crescem e elas se sobrepõem. Mantenha o conjunto pequeno e distinto para cada tarefa ou carregue as ferramentas relevantes de forma dinâmica.

  • #tool calling
  • #function calling
  • #agentes de IA
  • #loop de agente
  • #MCP

Agora pratique

O TokIQ transforma prompt engineering em quizzes curtos, com uma explicação para cada resposta.

Em breve naApp StoreDisponível noGoogle Play

Escreva prompts melhores, com algumas questões por dia.

Quizzes curtos sobre decisões reais de prompting, com uma explicação para cada resposta. Grátis para começar no iPhone e no Android.

Em breve naApp StoreDisponível noGoogle Play