🧰 Tool design e schemas
Este modulo transforma o aluno em alguem capaz de projetar ferramentas pequenas, compreensiveis e mais resistentes a chamadas erradas do agente.
📝 Descricao de tool
Antes de pensar em codigo, o engenheiro precisa escrever bem o papel da ferramenta. Descricao boa reduz uso errado e ajuda o agente a escolher melhor.
Conceito principal
Uma tool precisa explicar para que serve, quando deve ser chamada e quando nao deve ser chamada.
Alerta
Nome bonito sem escopo claro vira convite para uso indevido.
📦 Schema de entrada e saida
Schema nao e burocracia. E o mecanismo que reduz ambiguidade, simplifica validacao e melhora interoperabilidade.
Bom schema
Campos claros, tipos definidos, enums quando necessario e shape de saida previsivel.
Schema ruim
Parametros vagos, campos opcionais demais e retorno inconsistente.
✅ Validacao e tipos
Validacao e a barreira minima entre um pedido malformado e um efeito colateral no mundo real.
Criterio tecnico
Se o parametro nao passa na validacao, a tool nao executa. Isso reduz risco e facilita debug.
Dica pratica
Sempre diferencie erro de formato, falta de dado e autorizacao insuficiente.
🚨 Erros recuperaveis e nao recuperaveis
Nem toda falha merece retry. Parte do talento de engenharia esta em classificar erro e responder com a estrategia certa.
Recuperavel
Timeout, indisponibilidade temporaria ou dependencia momentaneamente fora.
Nao recuperavel
Input invalido, permissao negada e acao proibida por politica.
👤 Aprovacao humana e side effects
Quanto maior o impacto da acao, menor deve ser a autonomia livre. O modulo reforca essa regra antes da trilha avancada.
Conceito principal
Excluir, enviar, alterar ou gastar recursos pede preview e gate humano quando houver risco relevante.
Alerta
“O agente sabe o que faz” nao e politica de seguranca.
🧪 Laboratorio de tool calling
O aluno desenha 3 tools, testa chamadas validas e invalidas e refina a descricao com base nos erros observados.
Exercicio
Criar uma tool de leitura, uma de transformacao e uma de acao com schema e mensagem de erro padronizada.
Entregavel
Pacote com 3 definicoes de tools, exemplos de payload e tabela de validacoes.
✅ Resumo final
✓ Aprendeu a escrever boas descricoes de tool.
✓ Entendeu o papel de schemas e validacao.
✓ Viu como classificar falhas e proteger side effects.
✓ Entendeu por que aprovacao humana faz parte do design.
✓ Saiu com um pequeno kit de tools desenhadas corretamente.