🏠 Início / 📚 Documentação / Agent Loop E Plataforma / Agent Templates Official

Agent Templates Official

Agent Templates - CSuite (v1) - Documentação Oficial

Visão Geral

Os Agent Templates são templates canônicos, reutilizáveis e governáveis, baseados no Agent Loop v1, que transformam o CSuite em uma plataforma decisional auto-evolutiva.

Arquitetura

Template Base (Herdado por Todos)

Todo agente CSuite deve:

  1. ✅ Gravar pg_decision_log (via instrument_decision)
  2. ✅ Congelar contexto (ctx_decision_context_snapshot)
  3. ✅ Executar via execution_action_ledger
  4. ✅ Fechar outcome (ctx_policy_outcomes)
  5. ✅ Alimentar memória (csuite_memory)
  6. ✅ Respeitar policies (ctx_policy_registry)

Estrutura Padrão

Cada agente segue a mesma estrutura:

agent/
├── main.py       # Entrypoint FastAPI
├── context.py    # Context Builder (snapshot_json)
├── decision.py   # Decision Engine (integra com Policy Engine)
├── execution.py  # Execution Handler (execution_action_ledger)
└── policies.py   # Policy Guardrails (validações locais)

Templates Canônicos

1️⃣ Sales Agent (CSuite.Sales.Agent)

Propósito: Converter intenção comercial em decisão executável com governança.

Decision Types

Contexto Mínimo

{
  "customer": { "id", "segment", "rfm_score", "credit_status" },
  "product": { "sku", "stock", "base_price" },
  "pricing": { "price_tier", "max_discount" },
  "history": { "last_quote_at", "conversion_rate" }
}

Ações Permitidas

Outcomes Esperados

Autonomia

Nível Condição
L0 Sempre recomendação
L1 Execução automática para RFM >= 70
L2 Follow-up automático
L3 Ajuste dinâmico de desconto (guardado por policy)

Policies

2️⃣ Pricing Agent (CSuite.Pricing.Agent)

Propósito: Otimizar preço respeitando margem, elasticidade e risco.

Decision Types

Contexto Mínimo

{
  "sku": { "id", "cost", "margin" },
  "inventory": { "days_on_hand", "turn_rate" },
  "market": { "elasticity", "competitor_price" },
  "policy": { "floor_margin", "max_discount" }
}

Ações Permitidas

Outcomes

Autonomia

Nível Condição
L0 Recomendação
L1 Ajustes ≤ 5%
L2 Promoções automáticas
L3 Otimização contínua

Policies

3️⃣ Operations Agent (CSuite.Operations.Agent)

Propósito: Manter execução estável, previsível e eficiente.

Decision Types

Contexto Mínimo

{
  "process": { "type", "sla", "attempts" },
  "resource": { "id", "capacity", "status" },
  "history": { "failures", "latency" }
}

Ações Permitidas

Outcomes

Autonomia

Nível Condição
L0 Manual
L1 Retry automático
L2 Rebalanceamento
L3 Self-healing

Policies

4️⃣ Risk Agent (CSuite.Risk.Agent)

Propósito: Detectar, priorizar e mitigar riscos antes de virarem crises.

Decision Types

Contexto Mínimo

{
  "signal": { "type", "severity" },
  "entity": { "type", "ref" },
  "trend": { "direction", "velocity" },
  "policy": { "thresholds" }
}

Ações Permitidas

Outcomes

Autonomia

Nível Condição
L0 Alerta
L1 Monitoramento automático
L2 Bloqueio parcial
L3 Bloqueio total

Policies

Agent Registry

Tabela: agent_registry

Registra todos os agentes do sistema:

SELECT * FROM csuite_agents.agent_registry;

Campos principais:
- agent_code: Código único (ex: CSuite.Sales.Agent)
- agent_domain: Domínio (SALES, PRICING, OPS, RISK)
- autonomy_level: Nível de autonomia (L0, L1, L2, L3)
- metadata_json: Decision types, ações, outcomes

Tabela: agent_runs

Registra execuções de agentes:

SELECT * FROM csuite_agents.agent_runs
WHERE agent_code = 'CSuite.Sales.Agent'
ORDER BY started_at DESC
LIMIT 10;

Links:
- decision_log_id → pg_decision_log
- outcome_id → ctx_policy_outcomes

View: vw_agent_performance

Performance agregada por agente:

SELECT * FROM csuite_agents.vw_agent_performance;

Métricas:
- Total de runs
- Taxa de sucesso
- Confiança média
- Latência média

Policy Packs

Policy Packs são registrados em ctx_policy_registry:

Sales Policy Pack

Pricing Policy Pack

Ops Policy Pack

Risk Policy Pack

Integração com Agent Loop v1

Fluxo Completo

1. Request → Agent
2. Agent → Context Builder → snapshot_json
3. Agent → Decision Engine → decision
4. Decision Engine → Policy Engine → pg_decision_log
5. Policy Engine → Snapshot → ctx_decision_context_snapshot
6. Policy Engine → Outcome → ctx_policy_outcomes
7. Agent → Execution → execution_action_ledger
8. Agent → Registry → agent_runs
9. Memory Feed → csuite_memory (precedents)

Exemplo de Integração

# Em decision.py
from app.policy_engine.instrumentation import instrument_decision
from app.policy_engine.outcome_recorder import record_outcome_from_decision

# Cria request
req = EvaluateRequest(
    decision_id=f"{agent_code}:{decision_type}",
    actor=f"{agent_code}:system",
    inputs={"org_id": org_id, "payload": payload, "context": context}
)

# Instrumenta (grava pg_decision_log + snapshot)
decision_log_id = instrument_decision(db, req, resp, start_time)

# Registra outcome
record_outcome_from_decision(
    db=db,
    decision_log_id=decision_log_id,
    org_id=org_id,
    policy_code=decision_type,
    entity_type=entity_type,
    entity_ref=entity_ref,
    action_taken=action_taken,
    created_by=agent_code
)

# Registra run
db.execute(text("""
    CALL csuite_agents.sp_register_agent_run(...)
"""))

Uso

Executar Agente

# Sales Agent
curl -X POST http://localhost:8001/run \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 0,
    "customer": {"id": "CUST-123", "rfm_score": 75},
    "product": {"sku": "PROD-456", "base_price": 10000},
    "pricing": {"max_discount": 8}
  }'

Ver Performance

SELECT 
  agent_code,
  total_runs,
  success_rate_pct,
  avg_confidence,
  avg_latency_ms
FROM csuite_agents.vw_agent_performance
WHERE agent_domain = 'SALES';

Ver Runs Recentes

SELECT 
  r.run_id,
  r.agent_code,
  r.run_status,
  r.confidence_score,
  r.started_at,
  d.decision_id,
  o.status AS outcome_status
FROM csuite_agents.agent_runs r
LEFT JOIN csuite_executive.pg_decision_log d
  ON d.decision_log_id = r.decision_log_id
LEFT JOIN csuite_context.ctx_policy_outcomes o
  ON o.decision_log_id = r.decision_log_id
WHERE r.started_at >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
ORDER BY r.started_at DESC;

Benefícios

✅ Reutilizável

✅ Comparável

✅ Governável

✅ Auto-Evolutivo

Próximos Passos

  1. Integrar com sistemas reais

  2. Orçamentos, precificação, processos, alertas

  3. Evoluir autonomia

  4. Aumentar autonomia baseado em performance

  5. Ajustar thresholds dinamicamente

  6. Adicionar novos agentes

  7. Inventory Agent
  8. Customer Service Agent

  9. Finance Agent

  10. Machine Learning

  11. Treinar modelos por agente
  12. Otimizar decisões baseado em outcomes

Conclusão

Os Agent Templates transformam o CSuite de um "sistema com agentes" em uma plataforma decisional auto-evolutiva, onde:

Isso não é um MVP. É uma arquitetura de produção.

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir