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

Ceo Agent

CSuite CEO Agent - Documentação

📋 Índice

  1. Visão Geral
  2. Arquitetura
  3. Configuração
  4. Workflows
  5. Integração
  6. Output Schema
  7. Uso
  8. Troubleshooting

Visão Geral

O CSuite CEO Agent é um agente executivo de alto nível que gera brief diário para o CEO, protegendo o attention budget e escalando apenas riscos irreversíveis ou sistêmicos.

Propósito

Características Principais

Arquitetura

Fluxo de Decisão

1. Policy Gate → Valida execução (ceo.daily_brief)
   ↓
2. Collect Signals → Busca dados em paralelo
   ├─ KPIs (Executive Dashboard)
   ├─ Inbox (Campanhas/Bundles)
   ├─ Daily Focus
   ├─ Rupture/Low-turn
   └─ **Market Intelligence** (BCB Macro Indicators)
   ↓
3. Load Memory → Consulta Memory API
   ├─ Riscos recentes
   ├─ Precedentes relevantes
   ├─ Violações recorrentes
   ├─ Sinais de drift
   └─ **Resolved Conflicts** (Arbitration Results)
   ↓
4. Load Cases → Consulta Policy Guardian
   └─ Casos pendentes
   ↓
5. Synthesize → Gera brief via LLM
   ├─ Context (o que mudou)
   ├─ Policies Impacted
   ├─ Risks
   ├─ Options
   ├─ Recommendation (max 3)
   └─ Memory Updates (suggestions)
   ↓
6. Emit → Publica via webhook
   └─ Slack/Email/Endpoint interno

Integrações

Configuração

Arquivo YAML (Fonte Canônica)

Localização: agents/ceo/ceo_agent.yaml

Este arquivo é a fonte canônica do agente, contendo:

Variáveis de Ambiente

# URLs dos serviços CSuite
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive
CSUITE_CONTEXT_URL=https://csuite.internut.com.br

# LLM
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini

# Webhook
CEO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Workflows

1. n8n Workflow

Arquivo: workflows/n8n/ceo_agent_daily_brief.json

Descrição: Workflow automatizado que executa o CEO Agent diariamente.

Fluxo:
1. Cron Daily (08:10) → Dispara workflow
2. Policy Gate → Valida execução
3. If Not DENY → Continua se permitido
4. Fetch Signals (paralelo):
- Fetch KPIs
- Fetch Inbox
- Memory Query
- Open Cases
5. Merge Signals → Consolida dados
6. LLM - CEO Brief → Gera brief
7. Publish Brief → Publica via webhook

Importação:
1. Acesse n8n
2. Workflows → Import from File
3. Selecione ceo_agent_daily_brief.json
4. Configure variáveis de ambiente
5. Ative o workflow

Documentação: workflows/n8n/README.md

2. LangGraph State Machine

Arquivo: workflows/langgraph/ceo_agent_state_machine.json

Descrição: State machine com loop formalizado.

Nodes:
- collect_signals - Busca sinais em paralelo
- load_memory - Consulta Memory API
- load_cases - Busca casos pendentes
- policy_gate - Valida execução
- synthesize - Gera brief via LLM
- emit - Publica resultado

Edges:
- collect_signals → load_memory
- load_memory → load_cases
- load_cases → policy_gate
- policy_gate → synthesize (se não DENY)
- synthesize → emit

Documentação: workflows/langgraph/README.md

Integração

Policy Gate

O CEO Agent passa por um policy gate antes de executar:

Exemplo de política (YAML):

ceo.daily_brief:
  rule: |
    ALLOW if:
      - org_id is valid
      - time_window_days <= 30
    ESCALATE if:
      - Policy Engine unavailable
    DENY if:
      - org_id is invalid
      - time_window_days > 30

Memory API

Consulta memória institucional para:

Endpoint: POST /v1/memory/query

Executive Dashboard

Busca sinais operacionais:

Policy Guardian

Consulta casos pendentes:

Output Schema

Estrutura do Brief

{
  "context": "Resumo executivo do que mudou nos últimos 7 dias",
  "policies_impacted": [
    "SALES_DISCOUNT_MAX",
    "PRICE_MARGIN_FLOOR"
  ],
  "risks": [
    {
      "severity": "high",
      "description": "Margem caindo 15% em 7 dias",
      "irreversible": false,
      "policy_ref": "PRICE_MARGIN_FLOOR"
    }
  ],
  "options": [
    {
      "option": "Ajustar política de desconto máximo",
      "pros": ["Protege margem", "Alinha com estratégia"],
      "cons": ["Pode reduzir conversão"],
      "impact": "high"
    }
  ],
  "recommendation": {
    "action": "Revisar política PRICE_MARGIN_FLOOR",
    "rationale": "Margem em queda requer ajuste de política",
    "urgency": "high",
    "next_steps": [
      "Analisar histórico de margem",
      "Consultar Policy Guardian",
      "Propor mudança via Policy Radar"
    ]
  },
  "memory_updates": [
    {
      "type": "policy_question",
      "content": "PRICE_MARGIN_FLOOR está adequado para mercado atual?",
      "tags": ["CEO", "DAILY_BRIEF", "PRICING"]
    }
  ],
  "should_escalate": false,
  "escalation_reason": ""
}

Campos Obrigatórios

Campos Opcionais

Uso

Via n8n (Recomendado)

  1. Importar workflow:
    bash # No n8n, importe: workflows/n8n/ceo_agent_daily_brief.json

  2. Configurar variáveis:
    bash # No n8n, configure: CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive CSUITE_CONTEXT_URL=https://csuite.internut.com.br LLM_MODEL=gpt-4o-mini CEO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

  3. Ativar workflow:

  4. O workflow dispara automaticamente às 08:10 diariamente
  5. Ou execute manualmente para teste

Via LangGraph

  1. Carregar state machine:
    ```python
    import json
    from langgraph.graph import StateGraph

with open('workflows/langgraph/ceo_agent_state_machine.json') as f:
graph_config = json.load(f)
```

  1. Configurar runtime:
    python # Configurar variáveis de ambiente # Executar grafo result = graph.invoke({ "org_id": 0, "as_of_date": "2025-01-03", "time_window_days": 7 })

Via API (Futuro)

Quando implementado no csuite-executive:

curl -X POST https://csuite.internut.com.br/executive/api/agents/CEO_AGENT/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "org_id": 0,
    "as_of_date": "2025-01-03",
    "time_window_days": 7
  }'

Troubleshooting

Policy Gate DENY

Problema: Workflow para no "If Not DENY"

Solução:
1. Verificar política ceo.daily_brief no Policy Engine
2. Verificar se org_id é válido
3. Verificar se time_window_days <= 30

Timeout em HTTP Requests

Problema: Timeout ao buscar sinais

Solução:
1. Aumentar timeout nos nodes HTTP (padrão: 6000ms)
2. Verificar conectividade com serviços CSuite
3. Verificar se serviços estão respondendo

LLM Error

Problema: Erro ao gerar brief

Solução:
1. Verificar credenciais do LLM (OpenAI API key)
2. Verificar se LLM_MODEL está correto
3. Verificar se há créditos/quota disponível

Webhook Fail

Problema: Brief não é publicado

Solução:
1. Verificar URL do webhook
2. Verificar formato do payload
3. Verificar autenticação (se necessário)

Memory Query Vazio

Problema: Memory API retorna vazio

Solução:
1. Verificar se há dados no csuite_memory
2. Ajustar query se necessário
3. Verificar conectividade com Memory API

Próximos Passos

Implementação Futura

Melhorias Opcionais

Referências

Última atualização: 2026-01-10
Versão: 1.1.0
Status: Operacional com Inteligência de Mercado e Arbitragem

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir