Registro de Roteamento de Ferramentas de Agente de IA

Quando Usar

• Definir quais ferramentas um agente pode chamar, seus esquemas de parâmetros e limites de tempo de execução.
• Revisar um registro de ferramenta proposto antes de conectá-lo a um tempo de execução de agente.
• Documentar contratos de tempo limite, retentativas e autorização para um roteador existente.

Escopo e pré-requisitos

Esta habilidade produz um registro e um plano de verificação. Um registro não implementa um roteador nem estabelece que uma ferramenta é segura. Leia o esquema real do servidor/ferramenta e o modelo de identidade e permissão da aplicação. Registre a configuração observada separadamente da política proposta. Não invoque ferramentas registradas, leia credenciais ou habilite um registro de produção meramente para preencher a tabela.

Fluxo de Trabalho

1. Identifique uma tarefa, o principal/inquilino chamador, a ferramenta pretendida e seu efeito de leitura ou gravação. Nomes de ferramentas, saída do modelo e descrições não são autorização.
2. Leia o esquema anunciado e os limites de implementação. Defina campos obrigatórios, rejeição de campos adicionais, limites de comprimento/intervalo e versão do esquema. Prefira a rejeição à coerção adivinhada ou com perda. A validação do esquema não impõe autorização em nível de linha, contenção de caminho ou restrições de rede.
3. Descreva a propagação de identidade e as verificações de recursos do lado do servidor. Vincule uma solicitação ao principal verificado; nunca permita que um argumento de ferramenta selecione um inquilino arbitrário.
4. Defina limites de tempo limite, taxa, concorrência, tamanho de resposta e custo medidos/aprovados pelo projeto. O cancelamento deve se propagar para o trabalho downstream onde suportado; retornar apenas um tempo limite não prova que uma gravação não foi concluída.
5. Classifique as retentativas por efeito. Retente apenas falhas transitórias classificadas dentro de um orçamento limitado. Uma gravação requer um contrato de desduplicação verificado do lado do servidor e reconciliação para conclusão ambígua; uma chave aleatória sozinha é insuficiente.
6. Defina casos adversários e de falha: argumentos ausentes/desconhecidos, inquilino incorreto, recursos negados, ferramenta indisponível, resposta excessiva e conclusão tardia.
7. Registre evidências de teste reais e lacunas não resolvidas. Mantenha o status como Rascunho até que as verificações necessárias sejam executadas contra a revisão exata do tempo de execução e do esquema. Um rótulo de registro nunca concede permissão de execução.

Referência de Campo

Para exportações SQL ou Notion, mantenha estas distinções: IDs textuais permanecem strings; objetos/arrays precisam de uma representação JSON deliberada ou tabelas relacionadas; datas devem usar valores de data reais. Não trate um booleano de lista de verificação como um controle comprovado. Escape texto semelhante a fórmula de planilha como texto ao exportar campos fornecidos pelo usuário.

Exemplo Trabalhado

Um agente precisa de um resumo de documento. A ferramenta proposta aceita apenas um ID de documento; o servidor obtém o chamador do contexto de sessão verificado, não dos argumentos.

{
  "tool_id": "TOOL-001",
  "canonical_name": "read_document",
  "server": "project-docs",
  "effect": "read",
  "parameter_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {"document_id": {"type": "string", "minLength": 1, "maxLength": 80}},
    "required": ["document_id"],
    "additionalProperties": false
  },
  "runtime_limits": {"timeout_ms": 5000, "max_response_bytes": 65536},
  "retry_contract": {"max_attempts": 2, "retry_on": ["transient_unavailable"]},
  "status": "draft",
  "evidence": []
}

Esses limites são requisitos ilustrativos, não capacidades de serviço medidas. O esquema local pode rejeitar um tenant_id adicionado, mas um ID de documento existente ainda

…