Phase 14 - Lesson 06

Uso de Ferramentas e Chamada de Função

O Toolformer (Schick et al., 2023) iniciou a anotação autossupervisionada de ferramentas. O Berkeley Function Calling Leaderboard V4 (Patil et al., 2025) define a régua para 2026: 40% agentic, 30% multi-turn, 10% live, 10% non-live, 10% hallucination. Chamadas de turno único (single-turn) estão resolvidas. Memória, tomada de decisão dinâmica e cadeias de ferramentas de longo horizonte (long-horizon tool chains) não estão.

Tipo: Construção Linguagens: Python (stdlib) Pré-requisitos: Phase 14 · 01 (Agent Loop), Phase 13 · 01 (Function Calling Deep Dive) Tempo: ~60 minutos

Objetivos de Aprendizado

• Explicar o sinal de treinamento autossupervisionado do Toolformer: manter as anotações de ferramentas apenas quando a execução reduzir a perda do próximo token (next-token loss).
• Nomear as cinco categorias de avaliação do BFCL V4 e o que cada uma mede.
• Implementar um registro de ferramentas em stdlib com validação de esquema (schema validation), coerção de argumentos (argument coercion) e sandbox de execução.
• Diagnosticar os três problemas em aberto de 2026: encadeamento de ferramentas de longo horizonte (long-horizon tool chaining), tomada de decisão dinâmica e memória.

O Problema

O uso primitivo de ferramentas perguntava: o modelo consegue prever uma chamada de função correta? O uso moderno de ferramentas pergunta: o modelo consegue encadear ferramentas ao longo de 40 passos, com memória, com observabilidade parcial, com recuperação de falhas de ferramentas, sem alucinar ferramentas que não existem?

O Toolformer estabeleceu a linha de base: os modelos podem aprender quando chamar ferramentas com autossupervisão. O BFCL V4 define a meta de avaliação de 2026. A lacuna entre eles é o espaço onde os agentes em produção vivem.

O Conceito

Toolformer (Schick et al., NeurIPS 2023)

Ideia: permitir que o modelo anote seu próprio corpus de pré-treinamento com chamadas candidatas de API. Para cada candidata, execute-a. Mantenha a anotação apenas se a inclusão do resultado da ferramenta reduzir a perda no próximo token. Ajuste fino (fine-tune) no corpus filtrado.

Ferramentas cobertas: calculadora, sistema de perguntas e respostas (QA), motores de busca, tradutor, calendário. O sinal de autossupervisão diz respeito puramente a se a ferramenta ajuda a prever o texto — sem rótulos humanos.

Resultado de escala: o uso de ferramentas surge em escala. Modelos menores são prejudicados pelas anotações de ferramentas; modelos maiores se beneficiam. É por isso que os modelos de fronteira de 2026 vêm com um forte uso de ferramentas integrado, enquanto a maioria dos modelos de 7B precisa de ajuste fino explícito de uso de ferramentas para ser confiável.

Berkeley Function Calling Leaderboard V4 (Patil et al., ICML 2025)

O BFCL é a avaliação de fato de 2026. Composição do V4:

• Agentic (40%) — trajetórias completas do agente: memória, multi-turn, decisões dinâmicas.
• Multi-Turn (30%) — conversas interativas com cadeias de ferramentas.
• Live (10%) — prompts reais enviados por usuários (distribuição mais difícil).
• Non-Live (10%) — casos de teste sintéticos.
• Hallucination (10%) — detectar quando nenhuma ferramenta deve ser chamada.

O V3 introduziu a avaliação baseada em estado: após uma sequência de ferramentas, verifica-se o estado real da API (por exemplo, "o arquivo foi criado?") em vez de corresponder à AST das chamadas de ferramentas. O V4 adicionou busca na web, memória e categorias de sensibilidade ao formato.

Principal descoberta de 2026: a chamada de função em turno único (single-turn) está quase resolvida. As falhas se concentram em memória (carregar o contexto entre os turnos), tomada de decisão dinâmica (escolher ferramentas com base em resultados anteriores), cadeias de longo horizonte (desvio após mais de 20 passos) e detecção de alucinação (recusar a chamada quando nenhuma ferramenta se adequa).

Esquema de ferramentas (Tool schema)

Cada provedor possui um esquema. Eles diferem nos detalhes, mas compartilham o mesmo formato:

name: string
description: string (what it does, when to use it)
input_schema: JSON Schema (properties, required, types, enums)

A Anthropic usa input_schema diretamente. A OpenAI usa function.parameters. Ambas aceitam JSON Schema. As descrições são cruciais (load-bearing) — o modelo as lê para escolher a ferramenta correta. Descrições ruins de ferramentas são a causa raiz número 1 de falhas por escolha da ferramenta errada.

Validação de argumentos

Não confie em nenhuma chamada de ferramenta. Valide:

1. Coerção de tipo. O modelo pode retornar uma string "5" onde o esquema define int. Coerça se não for ambíguo; rejeite caso contrário.
2. Validação de enum. Se o esquema diz status in {"open", "closed"} e o modelo emite "in_progress", rejeite com um erro descritivo.
3. Campos obrigatórios. Campo obrigatório ausente -> observação de erro imediata de volta para o modelo, não uma falha do sistema (crash).
4. Validação de formato. Datas, emails, URLs — valide com analisadores (parsers) concretos, não regex.

Toda falha de validação deve retornar uma observação estruturada para que o modelo possa tentar novamente com o formato correto.

Chamadas paralelas de ferramentas

Provedores modernos suportam chamadas paralelas de ferramentas em um único turno do assistente. O loop:

1. O modelo emite 3 chamadas de ferramentas com tool_use_ids distintos.
2. O runtime executa-as (em paralelo, se independentes).
3. Cada resultado retorna como um bloco tool_result correlacionado pelo tool_use_id.

Regra de engenharia: trate IDs de correlação como essenciais (load-bearing). Troque-os e você terá um roteamento de resultado incorreto para a ferramenta errada.

Sandboxing

A execução da ferramenta é o limite do sandbox. Veja a Lição 09 para detalhes. Versão curta: cada ferramenta deve especificar a superfície de leitura/escrita, acesso à rede, limite de tempo (timeout) e limite de memória. Um run_shell(cmd) genérico é um sinal de alerta; um git_status() específico é mais seguro.

Construa

code/main.py implementa um registro de ferramentas com formato de produção:

• Validador de subconjunto de JSON Schema (apenas stdlib).
• Registro de ferramentas com descrição, esquema de entrada, timeout e executor.
• Coerção de argumentos e validação de enums.
• Despacho paralelo de ferramentas com IDs de correlação.
• Observações de erro como strings estruturadas.

Execute:

python3 code/main.py

O rastreamento (trace) mostra um mini agente chamando três ferramentas em um turno, com uma chamada deliberadamente malformada que é rejeitada com um erro descritivo sobre o qual o modelo pode agir.

Use

Cada provedor tem seu próprio esquema de ferramentas — Anthropic, OpenAI, Gemini, Bedrock. Use uma camada de tradução (OpenAI Agents SDK, Vercel AI SDK, adaptador de ferramentas LangChain) se precisar de múltiplos provedores. O BFCL é o benchmark de referência — execute-o contra o seu agente antes do envio se o uso de ferramentas for central para o produto.

Envie

outputs/skill-tool-registry.md gera um catálogo de ferramentas, esquema e registro para um determinado domínio de tarefa. Inclui verificações de qualidade da descrição (a descrição de cada ferramenta informa ao modelo quando usá-la?).

Exercícios

1. Adicione uma ferramenta "no-op" que permite ao modelo recusar explicitamente o uso de qualquer outra ferramenta. Meça em um teste de alucinação semelhante ao BFCL.
2. Implemente a coerção de argumentos para int-como-string e float-como-string. Onde a coerção começa a ocultar bugs reais?
3. Adicione um timeout por ferramenta e um disjuntor (circuit breaker - recuse a ferramenta por 60s após 3 falhas consecutivas). O que isso altera sobre como o modelo se recupera?
4. Leia a descrição do BFCL V4. Escolha uma categoria (por exemplo, "multi-turn") e execute 10 prompts de exemplo no seu agente. Relate a taxa de aprovação.
5. Portar o validador stdlib para Pydantic ou Zod. O que o Pydantic/Zod detectou que a implementação de brinquedo deixou passar?

Termos-Chave

Leituras Adicionais

• Schick et al., Toolformer (arXiv:2302.04761) — anotação autossupervisionada de ferramentas
• Berkeley Function Calling Leaderboard (V4) — benchmark de avaliação de 2026
• Anthropic, Documentação de uso de ferramentas — esquema de ferramentas em produção no Claude Agent SDK
• OpenAI Agents SDK docs — tipo de ferramenta de função e Guardrails