Contrasync Docs

Appearance

Runbook: Adicionar uma nova AI tool (D0.4) ​

Tempo médio: ~20 min. Severidade: rotina (não é incidente).

Pré-condições ​

  • Existe endpoint REST no Product API que faz a ação (a IA nunca toca o Postgres do produto, ADR-002).
  • A ação tem permissão correspondente no RBAC do produto.

Passos ​

  1. Escolha o grupo em contrasync-ai-api/src/modules/tools/ (contracts, templates, org, billing, insights) ou crie nome.tools.ts.
  2. Defina o schema Zod e o objeto definition:
    • name (snake_case único), description (PT-BR, o LLM lê isto), permission (string RBAC), schema, audit: true, access: READ | WRITE.
    • Ação destrutiva → requiresConfirmation: true e adicione confirm: z.boolean().optional() ao schema.
  3. Implemente a classe @AITool(def) @Injectable() com readonly definition = def e execute(input, context) chamando ProductApiClientService.request(...) com: userToken: context.userToken, traceparent: context.traceparent, e em WRITE idempotencyKey: context.idempotencyKey.
  4. Registre a classe no array exportado do arquivo (*_TOOLS): o ToolsModule já injeta todos; o AIToolRegistryService autodescobre no boot via DiscoveryService.
  5. Eval: adicione casos em eval/tool-selection.json (e intent.json se for nova intenção). Rode npm run ai:eval -- --check.
  6. Valide: npm run format && npm run lint && npx tsc --noEmit && npm test.
  7. Doc: atualize architecture/ai-api/tool-framework.md (lista de tools) e o módulo de negócio em docs/business/ se for nova capacidade (regra "no doc, no merge").

Verificação ​

sh
curl -H "Authorization: Bearer $JWT" http://localhost:4001/ai/v1/tools.json

A tool nova deve aparecer em { tools: [...] } com inputSchema correto.

Rollback ​

Remova a classe do array *_TOOLS e faça novo deploy, o registry deixa de expô-la no próximo boot. Tool calls passadas continuam auditadas em ai_tool_call.