Chamada de ferramenta: Design de sistema

Separa propostas de ferramentas do modelo da autorização: toda chamada requer aprovação da política, mutações de alto impacto exigem uma aprovação vinculada à ação, e a idempotência previne execuções duplicadas sem conceder permissão.

Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não se afirma que uma implementação adotante os tenha passado.

Decisão

O modelo pode propor um nome de ferramenta e argumentos; um mecanismo de política decide se a chamada será executada. Ferramentas de leitura que não podem alterar estado durável podem ser executadas após verificações de ACL. Toda mutação requer autorização de sessão. Mutações de alto impacto, irreversíveis, financeiras, administrativas ou visíveis externamente requerem adicionalmente um artefato de aprovação não expirado vinculado ao ator exato, ferramenta, alvo e argumentos normalizados. Uma chave de idempotência é apenas proteção contra repetição: ela pode repetir uma operação já autorizada com segurança, mas nunca concede autoridade ou substitui aprovação. O usuário atuante, locatário e papéis vêm do contexto de requisição autenticada, nunca de campos gerados pelo modelo.

Escopo

• Despacho de ferramentas do agente no backend: proposta, autorização, confirmação, execução simulada (dry-run), idempotência e auditoria.
• Ferramentas com efeitos colaterais como tickets, reembolsos, deploys ou atualizações de registros.
• Vinculação do ACL da ferramenta ao principal humano que possui a sessão do agente.

Fora deste bloco

• Filtros de conteúdo para injeção de prompt em documentos recuperados.
• Cancelamento de streaming no frontend de tokens já exibidos.

Contrato

• Cada registro de invocação de ferramenta armazena proposed_by: model e authorized_by como decisão de política sobre a identidade da sessão.
• Ferramentas marcadas como mutation: true executam somente após autorização da sessão. Quando a política classifica a ação como de alto impacto, um approval_id vinculado à ação também é exigido.
• Execução simulada (dry-run) é obrigatória para ferramentas mutantes quando require_dry_run é verdadeiro; o resultado do dry-run é o que o humano confirma.
• Argumentos que nomeiam um usuário ou locatário diferente da sessão são rejeitados como identity_spoof.
• O ACL da ferramenta é avaliado sobre o principal da sessão contra identificadores de recurso após validação do esquema dos argumentos.
• Uma chave de idempotência é aceita somente com o mesmo ator, ferramenta, alvo e impressão digital da requisição que a chamada original autorizada. Ela repete o resultado armazenado e nunca autoriza uma primeira chamada por si só.

Implementação

• Mantenha flags de mutação, política de confirmação e suporte a dry-run em um catálogo de ferramentas, não no texto do prompt.
• Emita artefatos de aprovação de curta duração que hash o snapshot do dry-run e vinculem ator, ferramenta, alvo, versão da política e argumentos normalizados para que uma troca de argumento não possa reutilizar a aprovação.

Tratamento de falhas

• Negação da política retorna tool_forbidden sem chamar o provedor.
• Artefatos de aprovação expirados falham fechados. Após um timeout incerto, reconcilie a operação original antes de tentar novamente com a mesma chave de idempotência e impressão digital da requisição inalterada.

Verificação

• Tente uma mutação com um id de usuário fornecido pelo modelo e espere identity_spoof.
• Confirme um dry-run, altere argumentos e espere divergência na confirmação; repita a mesma chave e afirme um único efeito colateral.

Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Execute python tools/validate.py a partir da raiz da coleção para verificar a estrutura e metadados do pacote; então implemente e execute os cenários no repositório alvo.

Suposições para adoção

• Nomes e valores numéricos em example.yaml são um perfil de adoção, não padrões universais.
• A equipe adotante deve mapear atores, classes de dados, vocabulário de erros e propriedade para seu sistema.

Referências

• OWASP AI Agent Security Cheat Sheet separa autorização, aprovação humana e proteção contra repetição para ações de alto impacto.