Autonomy Auto-Pilot (Assistido) - Documentação
Visão Geral
O Autonomy Auto-Pilot é um motor de recomendação governado que:
- ✅ Avalia periodicamente cada agente
- ✅ Decide se deve sugerir promoção ou downgrade de autonomia
- ✅ Registra por que sugeriu (métricas + thresholds)
- ✅ Nunca executa sozinho (humano confirma)
Resultado:
- Zero análise manual
- Zero "achismo"
- Autonomia evolui quando merece
- Rollback rápido quando degrada
Arquitetura
Fluxo no Agent Loop
Agent Performance Radar
↓
Autonomy Auto-Pilot (evaluate)
↓
Autonomy Suggestion (record)
↓
Human Review / Approve
↓
Apply Autonomy Change
O Auto-Pilot não altera o Agent Loop v1 — apenas usa as métricas já coletadas.
Componentes
1. Tabela: agent_autonomy_suggestions
Registra todas as sugestões de autonomia:
SELECT * FROM csuite_agents.agent_autonomy_suggestions
WHERE status = 'OPEN'
ORDER BY created_at DESC;
Campos principais:
- current_level / suggested_level: Níveis de autonomia
- direction: PROMOTE ou DOWNGRADE
- suggestion_score: Quão forte é a recomendação (0-100)
- metrics_json: Métricas que justificam a sugestão
- status: OPEN → APPROVED → APPLIED (ou REJECTED)
2. Procedure: sp_agent_autonomy_autopilot
Avalia todos os agentes ativos e cria sugestões:
CALL csuite_agents.sp_agent_autonomy_autopilot(0, 30, 'system');
Parâmetros:
- p_org_id: Organization ID
- p_days: Janela de avaliação (padrão: 30 dias)
- p_actor: Quem executou (padrão: 'autonomy_autopilot')
Retorna:
- suggestions_created: Total de sugestões criadas
- promotions_suggested: Sugestões de promoção
- downgrades_suggested: Sugestões de downgrade
3. Procedure: sp_apply_autonomy_suggestion
Aplica uma sugestão aprovada:
CALL csuite_agents.sp_apply_autonomy_suggestion(123, 'robsonrr');
Validações:
- Sugestão deve existir
- Sugestão deve estar APPROVED
- Aplica autonomia no agent_registry
- Marca sugestão como APPLIED
Lógica de Avaliação
Thresholds Padrão
min_runs = 200
success_rate_pct >= 90
outcome_closure_rate_pct >= 95
avg_match_score >= 90
escalation_rate_pct <= 5
Promoção (L0→L1→L2→L3)
Condições:
- ✅ Todos os critérios passaram
- ✅ runs_total >= 200
- ✅ success_rate_pct >= 90
- ✅ outcome_closure_rate_pct >= 95
- ✅ avg_match_score >= 90
- ✅ escalation_rate_pct <= 5
- ✅ Nível atual != L3
Score: 85.0 (base para promoção)
Downgrade (L3→L2→L1→L0)
Condições (qualquer uma):
- ❌ success_rate_pct < 80 (10 pontos abaixo do mínimo)
- ❌ outcome_closure_rate_pct < 85 (10 pontos abaixo do mínimo)
- ❌ escalation_rate_pct > 10 (dobro do máximo)
- ❌ avg_match_score < 80 (10 pontos abaixo do mínimo)
Score: 90.0 (score alto para downgrade - mais crítico)
APIs REST
POST /api/agents/autonomy/autopilot/run
Executa avaliação automática:
curl -X POST "http://localhost:8000/api/agents/autonomy/autopilot/run?org_id=0&days=30&actor=system"
Response:
{
"status": "success",
"suggestions_created": 3,
"promotions_suggested": 2,
"downgrades_suggested": 1
}
GET /api/agents/autonomy/suggestions
Lista sugestões (padrão: apenas OPEN):
curl "http://localhost:8000/api/agents/autonomy/suggestions?org_id=0&status=OPEN"
Response:
[
{
"suggestion_id": 1,
"agent_code": "CSuite.Sales.Agent",
"agent_name": "Sales Agent",
"agent_domain": "SALES",
"current_level": "L1",
"suggested_level": "L2",
"direction": "PROMOTE",
"suggestion_score": 85.0,
"reason_summary": "Métricas acima dos thresholds: 482 runs, 93.4% success, 97.1% closure",
"status": "OPEN",
"created_at": "2024-01-15T10:00:00",
"evaluated_by": "autonomy_autopilot",
"metrics": {
"runs": 482,
"success_rate_pct": 93.4,
"outcome_closure_pct": 97.1,
"avg_match_score": 92.8,
"escalation_rate_pct": 2.1,
"avg_delta_score": 6.4,
"evaluation_days": 30
}
}
]
POST /api/agents/autonomy/{suggestion_id}/approve
Aprova uma sugestão:
curl -X POST "http://localhost:8000/api/agents/autonomy/1/approve?org_id=0&actor=robsonrr"
Response:
{
"status": "success",
"suggestion_id": 1,
"action": "approved"
}
POST /api/agents/autonomy/{suggestion_id}/reject
Rejeita uma sugestão:
curl -X POST "http://localhost:8000/api/agents/autonomy/1/reject?org_id=0&actor=robsonrr&reason=Preciso investigar mais"
Response:
{
"status": "success",
"suggestion_id": 1,
"action": "rejected"
}
POST /api/agents/autonomy/{suggestion_id}/apply
Aplica uma sugestão aprovada:
curl -X POST "http://localhost:8000/api/agents/autonomy/1/apply?org_id=0&actor=robsonrr"
Response:
{
"status": "success",
"suggestion_id": 1,
"action": "applied"
}
Workflow Completo
1. Executar Avaliação
POST /api/agents/autonomy/autopilot/run?org_id=0&days=30
Cria sugestões OPEN para agentes que passaram/falharam nos thresholds.
2. Revisar Sugestões
GET /api/agents/autonomy/suggestions?org_id=0&status=OPEN
Lista todas as sugestões pendentes.
3. Aprovar ou Rejeitar
# Aprovar
POST /api/agents/autonomy/1/approve?org_id=0&actor=robsonrr
# Rejeitar
POST /api/agents/autonomy/1/reject?org_id=0&actor=robsonrr&reason=...
4. Aplicar (se aprovado)
POST /api/agents/autonomy/1/apply?org_id=0&actor=robsonrr
Altera o autonomy_level do agente.
Integração com UI
Nova Aba no Agent Performance Radar
"Autonomy Suggestions"
Tabela:
- Agent (code + name)
- Domain (badge)
- Current → Suggested (badges)
- Direction (PROMOTE/DOWNGRADE badge)
- Suggestion Score (0-100)
- Key Metrics (badges: runs, success%, closure%, match_score)
- Actions: Approve / Reject / Apply
Filtros:
- Status (OPEN, APPROVED, REJECTED, APPLIED)
- Direction (PROMOTE, DOWNGRADE)
- Domain
Ações:
- Approve → Marca como APPROVED
- Reject → Marca como REJECTED (com motivo)
- Apply → Aplica autonomia (só se APPROVED)
Cron Job (Opcional)
Para avaliação automática periódica:
# Executar diariamente às 2h
0 2 * * * curl -X POST "http://localhost:8000/api/agents/autonomy/autopilot/run?org_id=0&days=30&actor=cron"
Benefícios
✅ Governança Explícita
- Todas as mudanças de autonomia são rastreáveis
- Histórico completo de decisões
- Métricas justificam cada sugestão
✅ Zero Risco
- Nunca altera autonomia sem aprovação humana
- Rollback rápido (rejeitar sugestão)
- Auditoria completa
✅ Máximo Leverage
- Usa todas as métricas já coletadas
- Zero análise manual
- Autonomia evolui quando merece
✅ Preparação para L3
- Base sólida para autonomia total futura
- Thresholds ajustáveis por domínio
- Score de confiança em cada sugestão
Próximos Passos
- Configurar cron job para avaliação automática
- Ajustar thresholds por domínio (se necessário)
- Adicionar alertas quando sugestões críticas (downgrade) são criadas
- Integrar na UI do Agent Performance Radar
- Adicionar estabilidade temporal (14 dias de métricas consistentes para promoção)
Conclusão
O Autonomy Auto-Pilot transforma autonomia de um "toggle manual" em uma decisão governada e rastreável, mantendo o controle humano enquanto reduz drasticamente o esforço de análise.
Isso não é automação cega. É assistência inteligente.