Projete ferramentas e contratos de ação
Trate as ferramentas como uma interface para o modelo: nomes e schemas claros, erros úteis, resultados concisos.
- Projetar ferramentas estreitas, com schemas claros e rótulos de efeito colateral
- Devolver erros com os quais o modelo consiga agir
- Manter os resultados das ferramentas concisos, com filtragem e paginação
As ferramentas são a forma de um ciclo tocar o mundo, e o modelo é o usuário delas. A Anthropic chama isso de interface agente-computador e sugere investir nela tanto quanto numa interface para humanos: nomes e descrições claros, exemplos de uso, parâmetros sensatos e testes completos (Building effective agents).
Um bom contrato de ferramenta tem:
- Um único propósito estreito, com ações só de leitura e ações que mudam o estado mantidas separadas.
- Um schema de entrada, validado pelo seu código antes de qualquer coisa rodar.
- Erros úteis: “priority precisa ser low, medium ou high (veio ‘urgent’)” deixa o modelo corrigir a chamada; “Entrada inválida”, não.
- Resultados concisos: devolva o que a próxima decisão precisa - filtrado, paginado -, não 5.000 linhas que inundam o contexto.
- Repetição segura: timeouts, e idempotência para ações com efeitos colaterais.
Experimente
Até 15 XPQue projeto de ferramenta é melhor?
Cada rodada compara duas formas de expor a mesma capacidade a um agente.
1tool = {
2 "name": "list_orders",
3 "description": "Read-only. List a customer's orders, newest first.",
4 "input_schema": {"customer_id": "string", "limit": "integer <= 50"},
5}
6print(tool["name"], "-", tool["description"])list_orders - Read-only. List a customer's orders, newest first.
Principais conclusões
Projete as ferramentas para o modelo como uma interface para uma pessoa: estreitas, documentadas, testadas.
Valide todos os argumentos e devolva erros que expliquem como corrigir a chamada.
Devolva resultados concisos e paginados; mantenha separadas as ferramentas com efeitos colaterais, e seguras para tentar de novo.
Quiz da aula
6 perguntas · aprovação com 5 acertos · até 50 XP
Ao passar, você conclui a aula e mantém sua sequência. As perguntas erradas voltarão em sessões de revisão.
Pratique: escreva código em Python
Escreva código Python no editor e execute os testes com exemplos. O Python roda localmente no navegador usando WebAssembly.
Valide as chamadas com erros úteis
Cada linha é uma chamada JSON {"tool": ..., "arguments": {...}}, conferida com SCHEMAS (tipos str, int ou uma lista de valores permitidos). Imprima ok, ou error: seguido de todos os problemas unidos por ; , nesta ordem:
unknown tool 'NAME' (available: A, B)(sozinho, se a ferramenta não existir);unknown argument 'NAME'para cada argumento a mais (em ordem);missing argument 'NAME'(na ordem do schema);NAME must be a string|an integer (got REPR)ouNAME must be one of A, B, C (got REPR)(na ordem do schema; booleanos não são inteiros).
- Cinco chamadas
O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.
Pagine os resultados das ferramentas
A linha 1 é uma lista JSON de resultados. A linha 2 é PAGE_SIZE CURSOR, em que CURSOR é start ou um número (o índice de onde continuar). Imprima cada resultado da página, depois showing A-B of N (a partir de 1) e next_cursor: C ou next_cursor: none.
- Primeira página
- Última página
O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.
Dúvidas sobre esta lição
Travou em algum ponto? Pergunte. Descobriu algo? Compartilhe. Explicar também é uma ótima forma de aprender.
Carregando publicações…