🟠 Builder

Agent Trust Stack — Policy file em YAML

Como traduzir o Agent Trust Stack em arquivo YAML versionado. Schema completo + 3 exemplos reais (HR scoring, financial transaction, content generation). Output runnable por agente.

16 de maio de 2026 · 10 min · ai-agency-skills

Por que policy file em YAML

O Agent Trust Stack define 5 dimensões pra decidir delegação à IA: Reversibility, Blast radius, Auditability, Cost, Time sensitivity. O framework existe em texto. Mas para empresas operando agentes em escala, texto não escala.

Solução: codificar a policy em arquivo YAML versionado em git, lido pelo agente em runtime. Vantagens:

Versionamento: cada mudança é PR + review.
Auditabilidade: histórico completo de mudanças de policy.
Reuso: mesma policy aplicada a múltiplos agentes.
Compliance-as-code: jurídico/DPO pode revisar policy YAML diretamente.

Este post traz o schema completo + 3 exemplos reais.

Schema completo

# policy.yaml
version: "1.0"
metadata:
  name: "Production agent policy"
  owner: "ivan@skillab.co"
  updated: "2026-05-15"
  policy_id: "POL-2026-001"

actions:
  - name: <action_name>
    description: <one-line description>
    trust_dimensions:
      reversibility: <high|medium|low>      # 1-5 scale
      blast_radius: <personal|internal|external>
      auditability: <full|partial|none>
      cost_of_error: <low|medium|high>      # BRL or USD ranges
      time_sensitivity: <not-sensitive|sensitive|critical>
    total_score: <auto-computed>
    autonomy_level: <auto-computed>   # 1=fully auto, 5=hold
    required_gates:
      - <gate1>
      - <gate2>
    review_required: <true|false>
    reviewer_role: <role|null>
    audit_retention: <duration>
    notes: <free-form>

Computed fields

total_score é soma das 5 dimensões (cada uma scoreada 1-3 dependendo da severity).

autonomy_level deriva de total_score:

5-7: Level 1 (autonomous + log)
8-10: Level 2 (assistive, human approve)
11-13: Level 3 (auxiliary, human decide)
14-15: Level 4 (don’t delegate)

Required gates

Lista de gates específicos que o agente precisa cumprir:

schema_validation: validar contra schema (sempre)
dry_run: gerar preview antes de execute
idempotency_check: validar não duplicar
human_approval: human-in-the-loop
sandbox: executar em sandbox isolado
confidence_threshold:<N>: só executar se confidence > N
audit_log: log completo + retenção

Exemplo 1 — HR Scoring (high-risk)

actions:
  - name: candidate_score
    description: "AI generates 0-100 fit score for job candidate"
    trust_dimensions:
      reversibility: high      # candidate can be re-reviewed manually
      blast_radius: external   # affects external person's career
      auditability: full       # legal requirement (LGPD Art. 20)
      cost_of_error: high      # discrimination lawsuit risk
      time_sensitivity: not-sensitive
    total_score: 12
    autonomy_level: 3   # auxiliary only
    required_gates:
      - schema_validation
      - human_approval
      - audit_log
      - confidence_threshold:0.7
    review_required: true
    reviewer_role: "recruiting_manager"
    audit_retention: "5y"
    notes: |
      LGPD Art. 20 requires human review on automated decisions affecting
      individuals. Brazilian TST case 2025 (Banco do Brasil) reinforced
      that AI score alone cannot decide hiring. Reviewer must add
      written justification.

Aplicação: quando agente é prompted “score candidate”, roda o pipeline. Mas executar a decisão final exige human_approval antes — agente pausa, manda preview ao recruiter, espera approval. Audit log persiste por 5 anos.

Exemplo 2 — Financial Transaction (medium-risk reversible)

actions:
  - name: invoice_classification
    description: "AI categorizes NF-e into cost center"
    trust_dimensions:
      reversibility: high      # reclassify in monthly close
      blast_radius: internal   # affects company's books
      auditability: full       # accounting audit requirement
      cost_of_error: medium    # tax implication possible
      time_sensitivity: not-sensitive
    total_score: 8
    autonomy_level: 2   # assistive
    required_gates:
      - schema_validation
      - confidence_threshold:0.85
      - audit_log
    review_required: false  # if confidence > 0.85, auto-execute
    reviewer_role: "accountant"  # for low-confidence cases
    audit_retention: "5y"  # tax authority requirement
    notes: |
      exemplo de vertical SaaS contábil. High-confidence classifications auto-execute
      with logging. Low-confidence (<0.85) routed to human queue.
      Monthly close review covers ~5% of total volume.

Aplicação: agente classifica nota. Se confidence > 0.85, executa direto + log. Se < 0.85, vai para queue manual.

Exemplo 3 — Content Generation (low-risk, high volume)

actions:
  - name: marketing_copy_draft
    description: "AI generates first draft of marketing copy"
    trust_dimensions:
      reversibility: high      # discard and regenerate
      blast_radius: personal   # internal team only until published
      auditability: partial    # log prompt + response, not full chain
      cost_of_error: low       # marketing draft, easy to fix
      time_sensitivity: sensitive  # campaign deadlines
    total_score: 6
    autonomy_level: 1   # autonomous + sampling
    required_gates:
      - schema_validation
      - audit_log
    review_required: false
    reviewer_role: null
    audit_retention: "1y"
    sampling_review:
      enabled: true
      rate: 0.1  # 10% randomly sampled for human review
    notes: |
      Drafts go directly to writer. Sampling review catches systematic
      bias or quality drift. Once draft is published, separate workflow
      handles external publication.

Aplicação: agente gera draft, log resumido. 10% das outputs vão para human review aleatório.

Como o agente lê a policy

// Pseudo-código TypeScript
import yaml from 'js-yaml';
import { readFileSync } from 'fs';

const policy = yaml.load(readFileSync('policy.yaml', 'utf8'));

async function executeAction(actionName: string, args: unknown) {
  const policyEntry = policy.actions.find(a => a.name === actionName);
  if (!policyEntry) {
    throw new Error(`Action ${actionName} not in policy`);
  }

  // Apply gates
  for (const gate of policyEntry.required_gates) {
    const passed = await applyGate(gate, args);
    if (!passed) {
      return { rejected: true, reason: `Gate ${gate} failed` };
    }
  }

  // Check autonomy level
  if (policyEntry.autonomy_level >= 3) {
    return { pending: true, reason: 'Awaiting human approval' };
  }

  // Execute
  const result = await executeReal(actionName, args);

  // Log per policy
  await auditLog({
    action: actionName,
    args,
    result,
    policy_id: policy.metadata.policy_id,
    retention: policyEntry.audit_retention,
  });

  return { executed: true, result };
}

Versionamento de policy

Mudança de policy = PR + review do DPO + log de mudança no commit. Exemplos:

“Aumentar confidence threshold de 0.85 → 0.90 em invoice_classification” → PR.
“Adicionar action cancel_subscription com autonomy_level=3” → PR.
“Mudar audit_retention de 1y → 5y em response a regulação nova” → PR + comunicação.

Cada policy version persistido. Audit trail aponta qual policy version foi aplicada na decisão de um dia X.

Anti-padrões

Policy file gigante e desorganizado. Quebre em múltiplos files por domínio.
Policy editada direto sem PR. Anula o ganho de versionamento.
Gates implementados mas não testados. CI deve ter test pra cada gate.
Policy não enforced no código. Tem que rodar em runtime, não ser doc.

FAQ

E se policy tem bug e bloqueia uso legítimo? PR + rollback. Importante: ter monitor de “actions sendo rejeitadas em volume incomum” pra detectar bugs.

Posso usar JSON em vez de YAML? Sim. YAML é mais legível pra non-dev (DPO, jurídico). JSON é melhor pra geração programática. Escolha pelo seu uso.

Outras linguagens? Existem ferramentas como OPA (Open Policy Agent) com Rego. Mais poderoso mas mais complexo. YAML simples cobre 90% dos casos.

Como testo policy? Test suite com pares (action, args, expected_outcome). Run em CI pra cada mudança.

Próximos passos

Codifique 1 action sua em policy.yaml esta semana. Comece pela ação de maior risco.
Workshop SkilLab — Consultoria & Treinamento. Implementação de Trust Stack as code em sistemas próprios. Detalhes.
Newsletter SkilLab AI. Inscreva-se abaixo.