Guia de Uso - APIs `/api/agents`

Base URL: https://csuite.internut.com.br/context/api/agents

📋 Índice

Agent Performance Radar
Autonomy Auto-Pilot
Autonomy Management
Exemplos Práticos

1. Agent Performance Radar

1.1 Overview (Performance Radar)

Endpoint: GET /api/agents/performance-radar

Descrição: Retorna visão executiva consolidada de performance de todos os agentes.

Parâmetros:
- org_id (int, obrigatório) - ID da organização (0 = todas)
- date_from (string, opcional) - Data inicial (YYYY-MM-DD)
- date_to (string, opcional) - Data final (YYYY-MM-DD)

Exemplo:

curl "https://csuite.internut.com.br/context/api/agents/performance-radar?org_id=0"

Resposta:

{
  "kpis": {
    "runs_total": 482,
    "success_rate_pct": 93.4,
    "avg_match_score": 92.8,
    "outcome_closure_rate_pct": 97.1,
    "escalation_rate_pct": 2.1,
    "avg_latency_sec": 0.45
  },
  "radar_axes": [
    {"axis": "Effectiveness", "score": 93.4},
    {"axis": "Reliability", "score": 97.1},
    {"axis": "Governance", "score": 97.9},
    {"axis": "Efficiency", "score": 100.0},
    {"axis": "Confidence", "score": 92.8},
    {"axis": "Precision", "score": 100.0}
  ],
  "leaderboard": [
    {
      "agent_code": "CSuite.Sales.Agent",
      "agent_name": "Sales Agent",
      "domain": "SALES",
      "autonomy": "L1",
      "runs": 150,
      "success_pct": 95.3,
      "avg_delta": 6.2,
      "closure_pct": 98.0,
      "escalation_pct": 1.5,
      "trend": "UP"
    }
  ]
}

1.2 Agent Detail Performance

Endpoint: GET /api/agents/{agent_code}/performance

Descrição: Performance detalhada de um agente específico.

Parâmetros:
- agent_code (path) - Código do agente (ex: CSuite.Sales.Agent)
- org_id (int, obrigatório) - ID da organização
- date_from (string, opcional) - Data inicial
- date_to (string, opcional) - Data final

Exemplo:

curl "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/performance?org_id=0&date_from=2024-01-01&date_to=2024-01-31"

Resposta:

{
  "agent_code": "CSuite.Sales.Agent",
  "agent_name": "Sales Agent",
  "domain": "SALES",
  "autonomy_level": "L1",
  "kpis": {
    "runs_total": 150,
    "success_rate_pct": 95.3,
    "avg_match_score": 94.2,
    "outcome_closure_rate_pct": 98.0,
    "escalation_rate_pct": 1.5,
    "avg_latency_sec": 0.42
  },
  "radar_axes": [...],
  "timeseries": [...]
}

1.3 Policy Impact Matrix

Endpoint: GET /api/agents/{agent_code}/policy-matrix

Descrição: Impacto de políticas por agente.

Parâmetros:
- agent_code (path) - Código do agente
- org_id (int, obrigatório) - ID da organização
- date_from (string, opcional) - Data inicial
- date_to (string, opcional) - Data final

Exemplo:

curl "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/policy-matrix?org_id=0"

Resposta:

{
  "agent_code": "CSuite.Sales.Agent",
  "policies": [
    {
      "policy_code": "SALES.QUOTE",
      "runs": 45,
      "success_rate_pct": 97.8,
      "avg_delta_score": 5.8,
      "impact": "HIGH"
    }
  ]
}

2. Autonomy Auto-Pilot

2.1 Executar Avaliação

Endpoint: POST /api/agents/autonomy/autopilot/run

Descrição: Executa avaliação automática de autonomia para todos os agentes ativos. Cria sugestões de PROMOTE ou DOWNGRADE baseado em métricas.

Parâmetros:
- org_id (int, obrigatório) - ID da organização (0 = todas)
- days (int, padrão: 30) - Janela de avaliação em dias
- actor (string, padrão: "autonomy_autopilot") - Quem executou

Exemplo:

curl -X POST "https://csuite.internut.com.br/context/api/agents/autonomy/autopilot/run?org_id=0&days=30&actor=system"

Resposta:

{
  "status": "success",
  "suggestions_created": 3,
  "promotions_suggested": 2,
  "downgrades_suggested": 1
}

Thresholds padrão:
- min_runs: 200
- min_success_rate_pct: 90%
- min_closure_rate_pct: 95%
- min_match_score: 90
- max_escalation_rate_pct: 5%

2.2 Listar Sugestões

Endpoint: GET /api/agents/autonomy/suggestions

Descrição: Lista sugestões de autonomia (padrão: apenas OPEN).

Parâmetros:
- org_id (int, obrigatório) - ID da organização
- status (string, opcional) - Filtro por status: OPEN, APPROVED, REJECTED, APPLIED
- direction (string, opcional) - Filtro por direção: PROMOTE, DOWNGRADE

Exemplo:

# Listar sugestões abertas
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0&status=OPEN"

# Listar todas as sugestões
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0"

# Listar apenas promoções
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0&status=OPEN&direction=PROMOTE"

Resposta:

[
  {
    "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
    }
  }
]

2.3 Aprovar Sugestão

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

Descrição: Aprova uma sugestão de autonomia (marca como APPROVED, mas não aplica).

Parâmetros:
- suggestion_id (path) - ID da sugestão
- org_id (int, obrigatório) - ID da organização
- actor (string, obrigatório) - Quem aprovou

Exemplo:

curl -X POST "https://csuite.internut.com.br/context/api/agents/autonomy/1/approve?org_id=0&actor=robsonrr"

Resposta:

{
  "status": "success",
  "suggestion_id": 1,
  "action": "approved"
}

2.4 Rejeitar Sugestão

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

Descrição: Rejeita uma sugestão de autonomia.

Parâmetros:
- suggestion_id (path) - ID da sugestão
- org_id (int, obrigatório) - ID da organização
- actor (string, obrigatório) - Quem rejeitou
- reason (string, opcional) - Motivo da rejeição

Exemplo:

curl -X POST "https://csuite.internut.com.br/context/api/agents/autonomy/1/reject?org_id=0&actor=robsonrr&reason=Preciso investigar mais"

Resposta:

{
  "status": "success",
  "suggestion_id": 1,
  "action": "rejected"
}

2.5 Aplicar Sugestão

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

Descrição: Aplica uma sugestão aprovada (altera o autonomy_level do agente).

Parâmetros:
- suggestion_id (path) - ID da sugestão
- org_id (int, obrigatório) - ID da organização
- actor (string, obrigatório) - Quem aplicou

Exemplo:

curl -X POST "https://csuite.internut.com.br/context/api/agents/autonomy/1/apply?org_id=0&actor=robsonrr"

Resposta:

{
  "status": "success",
  "suggestion_id": 1,
  "action": "applied"
}

Nota: A sugestão deve estar com status APPROVED para ser aplicada.

3. Autonomy Management

3.1 Promover Autonomia Manualmente

Endpoint: POST /api/agents/{agent_code}/autonomy/promote

Descrição: Promove autonomia de um agente manualmente (sem passar por sugestão).

Parâmetros:
- agent_code (path) - Código do agente
- org_id (int, obrigatório) - ID da organização
- to_level (string, obrigatório) - Nível de destino: L0, L1, L2, L3
- actor (string, obrigatório) - Quem promoveu
- reason (string, opcional) - Motivo

Exemplo:

curl -X POST "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/autonomy/promote?org_id=0&to_level=L2&actor=robsonrr&reason=Teste manual"

Resposta:

{
  "status": "success",
  "agent_code": "CSuite.Sales.Agent",
  "new_autonomy": "L2"
}

3.2 Kill-Switch (Ativar/Desativar Agente)

Endpoint: POST /api/agents/{agent_code}/active

Descrição: Ativa ou desativa um agente (kill-switch).

Parâmetros:
- agent_code (path) - Código do agente
- org_id (int, obrigatório) - ID da organização
- is_active (bool, obrigatório) - true para ativar, false para desativar
- actor (string, obrigatório) - Quem executou
- reason (string, opcional) - Motivo

Exemplo:

# Desativar agente
curl -X POST "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/active?org_id=0&is_active=false&actor=robsonrr&reason=Manutenção"

# Reativar agente
curl -X POST "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/active?org_id=0&is_active=true&actor=robsonrr"

Resposta:

{
  "status": "success",
  "agent_code": "CSuite.Sales.Agent",
  "is_active": false
}

4. Exemplos Práticos

4.1 Workflow Completo: Avaliar e Aplicar Autonomia

# 1. Executar avaliação automática
curl -X POST "https://csuite.internut.com.br/context/api/agents/autonomy/autopilot/run?org_id=0&days=30&actor=system"

# 2. Listar sugestões criadas
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0&status=OPEN"

# 3. Aprovar uma sugestão (exemplo: suggestion_id=1)
curl -X POST "https://csuite.internut.com.br/context/api/agents/autonomy/1/approve?org_id=0&actor=robsonrr"

# 4. Aplicar a sugestão aprovada
curl -X POST "https://csuite.internut.com.br/context/api/agents/autonomy/1/apply?org_id=0&actor=robsonrr"

# 5. Verificar performance atualizada
curl "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/performance?org_id=0"

4.2 Monitoramento de Performance

# Dashboard executivo (todos os agentes)
curl "https://csuite.internut.com.br/context/api/agents/performance-radar?org_id=0"

# Performance de um agente específico
curl "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/performance?org_id=0&date_from=2024-01-01&date_to=2024-01-31"

# Impacto de políticas
curl "https://csuite.internut.com.br/context/api/agents/CSuite.Sales.Agent/policy-matrix?org_id=0"

4.3 Gestão de Autonomia

# Ver sugestões pendentes
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0&status=OPEN"

# Ver apenas promoções sugeridas
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0&status=OPEN&direction=PROMOTE"

# Ver apenas downgrades sugeridos
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0&status=OPEN&direction=DOWNGRADE"

# Ver histórico de sugestões aplicadas
curl "https://csuite.internut.com.br/context/api/agents/autonomy/suggestions?org_id=0&status=APPLIED"

4.4 Autenticação

Nota: Se a autenticação estiver habilitada, você precisará incluir o token JWT:

# Com autenticação
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://csuite.internut.com.br/context/api/agents/performance-radar?org_id=0"

5. Códigos de Agentes Canônicos

Os 4 agentes canônicos implementados:

CSuite.Sales.Agent - Sales Agent
CSuite.Pricing.Agent - Pricing Agent
CSuite.Operations.Agent - Operations Agent
CSuite.Risk.Agent - Risk Agent

6. Níveis de Autonomia

L0: Sempre recomendação (sem execução automática)
L1: Execução automática para casos simples
L2: Execução automática com validações
L3: Autonomia total (com kill-switch)

7. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/context/docs

OpenAPI JSON: https://csuite.internut.com.br/context/openapi.json

8. Troubleshooting

Erro: "Not Found"

Verifique se o serviço csuite-context está rodando
Verifique se a imagem Docker foi atualizada com o código mais recente
Verifique se o router agent_performance está registrado

Erro: "Method Not Allowed"

Verifique se está usando o método HTTP correto (GET vs POST)
Alguns endpoints são POST, não GET

Erro: "Access Denied"

Verifique se a autenticação está configurada corretamente
Verifique se o token JWT é válido

9. Próximos Passos

Integrar na UI: Criar interface no Agent Performance Radar
Configurar Cron: Executar autopilot periodicamente
Alertas: Notificar quando sugestões críticas são criadas
Métricas: Adicionar dashboards no Grafana

Última atualização: 2024-01-15
Versão: v1.1 (STABLE)

Guia Uso Apis Context Agents

Guia de Uso - APIs `/api/agents`

📋 Índice

1. Agent Performance Radar

1.1 Overview (Performance Radar)

1.2 Agent Detail Performance

1.3 Policy Impact Matrix

2. Autonomy Auto-Pilot

2.1 Executar Avaliação

2.2 Listar Sugestões

2.3 Aprovar Sugestão

2.4 Rejeitar Sugestão

2.5 Aplicar Sugestão

3. Autonomy Management

3.1 Promover Autonomia Manualmente

3.2 Kill-Switch (Ativar/Desativar Agente)

4. Exemplos Práticos

4.1 Workflow Completo: Avaliar e Aplicar Autonomia

4.2 Monitoramento de Performance

4.3 Gestão de Autonomia

4.4 Autenticação

5. Códigos de Agentes Canônicos

6. Níveis de Autonomia

7. Documentação OpenAPI

8. Troubleshooting

Erro: "Not Found"

Erro: "Method Not Allowed"

Erro: "Access Denied"

9. Próximos Passos

🔊 Text-to-Speech

Guia de Uso - APIs /api/agents

📋 Índice

1. Agent Performance Radar

1.1 Overview (Performance Radar)

1.2 Agent Detail Performance

1.3 Policy Impact Matrix

2. Autonomy Auto-Pilot

2.1 Executar Avaliação

2.2 Listar Sugestões

2.3 Aprovar Sugestão

2.4 Rejeitar Sugestão

2.5 Aplicar Sugestão

3. Autonomy Management

3.1 Promover Autonomia Manualmente

3.2 Kill-Switch (Ativar/Desativar Agente)

4. Exemplos Práticos

4.1 Workflow Completo: Avaliar e Aplicar Autonomia

4.2 Monitoramento de Performance

4.3 Gestão de Autonomia

4.4 Autenticação

5. Códigos de Agentes Canônicos

6. Níveis de Autonomia

7. Documentação OpenAPI

8. Troubleshooting

Erro: "Not Found"

Erro: "Method Not Allowed"

Erro: "Access Denied"

9. Próximos Passos

🔊 Text-to-Speech

Guia de Uso - APIs `/api/agents`