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.

Autonomy Autopilot

Autonomy Auto-Pilot (Assistido) - Documentação

Visão Geral

Arquitetura

Fluxo no Agent Loop

Componentes

1. Tabela: `agent_autonomy_suggestions`

2. Procedure: `sp_agent_autonomy_autopilot`

3. Procedure: `sp_apply_autonomy_suggestion`

Lógica de Avaliação

Thresholds Padrão

Promoção (L0→L1→L2→L3)

Downgrade (L3→L2→L1→L0)

APIs REST

POST /api/agents/autonomy/autopilot/run

GET /api/agents/autonomy/suggestions

POST /api/agents/autonomy/{suggestion_id}/approve

POST /api/agents/autonomy/{suggestion_id}/reject

POST /api/agents/autonomy/{suggestion_id}/apply

Workflow Completo

1. Executar Avaliação

2. Revisar Sugestões

3. Aprovar ou Rejeitar

4. Aplicar (se aprovado)

Integração com UI

Nova Aba no Agent Performance Radar

Cron Job (Opcional)

Benefícios

✅ Governança Explícita

✅ Zero Risco

✅ Máximo Leverage

✅ Preparação para L3

Próximos Passos

Conclusão

🔊 Text-to-Speech

Autonomy Auto-Pilot (Assistido) - Documentação

Visão Geral

Arquitetura

Fluxo no Agent Loop

Componentes

1. Tabela: agent_autonomy_suggestions

2. Procedure: sp_agent_autonomy_autopilot

3. Procedure: sp_apply_autonomy_suggestion

Lógica de Avaliação

Thresholds Padrão

Promoção (L0→L1→L2→L3)

Downgrade (L3→L2→L1→L0)

APIs REST

POST /api/agents/autonomy/autopilot/run

GET /api/agents/autonomy/suggestions

POST /api/agents/autonomy/{suggestion_id}/approve

POST /api/agents/autonomy/{suggestion_id}/reject

POST /api/agents/autonomy/{suggestion_id}/apply

Workflow Completo

1. Executar Avaliação

2. Revisar Sugestões

3. Aprovar ou Rejeitar

4. Aplicar (se aprovado)

Integração com UI

Nova Aba no Agent Performance Radar

Cron Job (Opcional)

Benefícios

✅ Governança Explícita

✅ Zero Risco

✅ Máximo Leverage

✅ Preparação para L3

Próximos Passos

Conclusão

🔊 Text-to-Speech

1. Tabela: `agent_autonomy_suggestions`

2. Procedure: `sp_agent_autonomy_autopilot`

3. Procedure: `sp_apply_autonomy_suggestion`