Contratos de ferramentas de IA: entradas e saídas úteis

Um contrato de ferramenta define o que ela recebe, o que faz e o que devolve. Contratos claros reduzem a ambiguidade entre a intenção do modelo e a ação da aplicação. Valide entradas e permissões em código mesmo quando o modelo costuma fornecer argumentos corretos.

Prefira uma ação explícita

Imagine uma ferramenta chamada gerenciar_cliente que recebe uma instrução livre. Ela pode significar ler notas, alterar um estado ou enviar uma mensagem. Separar capacidades como consultar_resumo_cliente e preparar_resposta_cliente facilita inspecionar e autorizar o comportamento.

Uma ferramenta de escrita deve identificar o registro exato e os campos permitidos. Evite usar apenas o nome quando clientes diferentes podem compartilhar o mesmo nome.

Defina os campos importantes

• Entrada obrigatória: identificadores e parâmetros necessários para executar.
• Validação: valores permitidos, formatos e regras de negócio.
• Efeitos: o que muda fora da conversa com o modelo.
• Resultado: estado estruturado, identificadores e erros úteis.
• Recuperação: se repetir é seguro e como reconciliar o pedido.

Explicite a ausência de dados. Um resultado vazio deve distinguir nenhum registro encontrado de conexão indisponível. Essas condições exigem próximos passos diferentes.

Retorne evidência, não tranquilização

Uma resposta dizendo que deu tudo certo oferece pouco para verificar. Uma resposta com código do rascunho salvo, conta e estado permite um relato preciso. Evite dados sensíveis nos logs quando identificadores bastarem.

Em trabalho assíncrono, retorne um identificador de tarefa e estado pendente. Ofereça um caminho separado para consultar a conclusão, em vez de incentivar sua dedução pela aceitação do pedido.

Teste usos inválidos e normais

Experimente um identificador ausente, um destino não autorizado e um campo inválido. Confirme que a ferramenta rejeita antes de produzir efeitos. Depois teste um pedido válido para garantir que os controles não bloqueiem trabalho útil. Um bom contrato facilita o comportamento correto e torna o incorreto visível.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.