🔧 Conceito de Tool Use
Tool use (ou function calling) e o paradigma onde o LLM nao apenas gera texto, mas decide quando e qual ferramenta externa chamar para resolver a tarefa do usuario. O modelo analisa a intencao, seleciona a funcao apropriada, gera os argumentos e interpreta o resultado.
🔄 Fluxo de Tool Use
📊 APIs de Tool Use por Provedor
-
•
OpenAI:
toolsparameter comtype: "function"— suporta chamadas paralelas -
•
Anthropic:
toolsarray cominput_schemaem JSON Schema — suporta tool_choice -
•
Google:
function_declarationscom suporte a grounding e code execution
📐 Function Calling Schema
O schema da funcao e o contrato que diz ao modelo o que a ferramenta faz e quais parametros aceita. Um schema bem definido e a diferenca entre o modelo usar a tool corretamente ou gerar chamadas invalidas.
📝 Estrutura de um Schema
{
"name": "get_weather",
"description": "Obtem a previsao do tempo atual para uma cidade",
"parameters": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "Nome da cidade" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["city"]
}
}
💡 Boas Praticas de Schema
-
•
Nomes descritivos:
search_productsem vez desp - • Descricoes ricas: Explique quando usar, nao apenas o que faz
- • Enums quando possivel: Restrinja valores validos para evitar erros
- • Required explicito: Marque campos obrigatorios para evitar chamadas incompletas
📝 Descricao de Ferramentas
A descricao da ferramenta e o fator mais critico para o modelo decidir quando usa-la. Descricoes vagas levam a chamadas incorretas ou a ferramentas sendo ignoradas quando deveriam ser usadas.
✗ Descricoes Ruins
- ✗ "Busca dados" — vago demais, quando usar?
- ✗ "Funcao de calculo" — qual tipo de calculo?
- ✗ "Processa input" — nao diz o que retorna
- ✗ Descricao identica para tools diferentes
✓ Descricoes Boas
- ✓ "Busca produtos no catalogo por nome, categoria ou faixa de preco"
- ✓ "Calcula frete com base em CEP de origem, destino e peso em kg"
- ✓ "Converte moedas usando taxa de cambio em tempo real"
- ✓ Cada tool com escopo claro e distinto
🎯 Disambiguation
Quando voce tem tools parecidas, a descricao deve deixar claro quando usar cada uma:
- • search_products: "Use quando o usuario quer encontrar ou comparar produtos. NAO use para verificar status de pedido."
- • get_order_status: "Use quando o usuario pergunta sobre um pedido existente (envio, entrega, rastreamento). Requer order_id."
🔄 Orquestracao de Chamadas
Em cenarios reais, uma unica interacao pode exigir multiplas chamadas de ferramentas. Orquestrar essas chamadas — decidir a ordem, gerenciar dependencias e manter o estado — e essencial para construir aplicacoes robustas.
Chamadas Sequenciais
O resultado de uma chamada alimenta a proxima. Ex.: buscar usuario → buscar pedidos do usuario → calcular frete.
Quando usar: Quando ha dependencia de dados entre as chamadas.
Chamadas Paralelas
Multiplas chamadas independentes ao mesmo tempo. Ex.: buscar clima + buscar noticias + buscar cotacao — tudo simultaneamente.
Quando usar: Quando as chamadas nao dependem umas das outras. Reduz latencia significativamente.
Chamadas Condicionais
O modelo decide se precisa chamar outra tool com base no resultado anterior. Ex.: se produto esta em estoque, calcular frete; senao, sugerir alternativas.
Quando usar: Quando o fluxo depende de condicoes dinamicas.
⚠️ Cuidado com Context Window
Cada chamada de ferramenta e seu resultado consomem tokens da janela de contexto. Em fluxos complexos com muitas chamadas, voce pode atingir o limite. Estrategias: resumir resultados intermediarios, limitar dados retornados, usar paginacao.
⚠️ Tratamento de Erros
Ferramentas externas falham. APIs ficam fora do ar, parametros sao invalidos, timeouts acontecem. Um sistema robusto precisa lidar com essas falhas de forma elegante, sem expor erros tecnicos ao usuario final.
🛡️ Estrategias de Error Handling
- • Retry com backoff: Tentar novamente com espera exponencial (1s, 2s, 4s) para erros transientes como timeout
- • Fallback tools: Se a API principal falha, usar uma alternativa. Ex.: se a API de clima falha, retornar dados em cache
- • Mensagem amigavel: Informar o usuario que o servico esta temporariamente indisponivel, sem expor stack traces
- • Logging estruturado: Registrar cada chamada, parametros, resposta e tempo para debug posterior
💡 Como Informar o Modelo sobre Erros
Quando uma tool falha, retorne um resultado estruturado que ajude o modelo a reagir adequadamente:
{ "error": true,
"error_type": "service_unavailable",
"message": "API de clima indisponivel",
"suggestion": "Informe ao usuario e sugira tentar novamente em alguns minutos" }
🧪 Exercicio: Integrar uma API
Neste exercicio, voce vai criar um schema completo de tools para um assistente que combina uma API de clima com uma calculadora. O objetivo e praticar a definicao de schemas, descricoes claras e orquestracao.
📋 Requisitos do Exercicio
- • Tool 1 — get_weather: Recebe cidade e unidade (celsius/fahrenheit), retorna temperatura, condicao e umidade
- • Tool 2 — calculate: Recebe expressao matematica como string, retorna o resultado numerico
- • Tool 3 — convert_unit: Recebe valor, unidade de origem e unidade de destino (temperatura, distancia, peso)
🎯 Teste seu Schema
- 1. Escreva o JSON Schema completo para cada uma das 3 tools
- 2. Teste com estas perguntas: "Qual o clima em Tokyo em Fahrenheit?", "Quanto e 15% de 340?", "Converta 100km para milhas"
- 3. Teste um cenario de orquestracao: "Qual a diferenca de temperatura entre SP e NY em Celsius?"
- 4. Simule um erro (API fora do ar) e verifique se o modelo reage adequadamente
📝 Resumo do Modulo
Proximo Modulo:
3.3 — RAG (Retrieval-Augmented Generation): combine busca em documentos com geracao