CFO Agent - Documentação Completa

📋 Visão Geral

O CFO Agent é um agente executivo autônomo do CSuite que protege caixa, margem e rentabilidade da organização. Ele gera briefs financeiros diários analisando fluxo de caixa, análise de margem, cost-to-serve e alertas financeiros.

Status: ✅ Implementado (v1.1.0) - Saneamento de Métricas (CFO Ops Fix)

🎯 Propósito

O CFO Agent existe para:

Proteger Caixa: Monitorar fluxo de caixa e alertar sobre riscos de liquidez
Proteger Margem: Identificar pedidos com prejuízo e clientes ineficientes
Otimizar Rentabilidade: Analisar cost-to-serve e recomendar ações
Alertar Riscos: Detectar e escalar riscos financeiros críticos

🏗️ Arquitetura

Fluxo de Execução

1. Policy Gate
   ↓
2. Coleta de Dados
   ├─ Cashflow API (timeline, alerts, containers)
   ├─ CFO-Ops API (cost-to-serve, margin)
   ├─ Context API (KPIs)
   └─ Memory API (precedentes)
   ↓
3. Geração de Brief (LLM)
   ↓
4. Publicação (Slack)
   ↓
5. Salvamento (JSON)

Componentes

YAML Config: agents/cfo/cfo_agent.yaml - Configuração canônica
Python Script: workflows/scripts/cfo_agent_daily_brief.py - Execução principal
Workflows: n8n e LangGraph (opcional)

🔌 Integrações

1. CSuite Cashflow

Base URL: https://csuite.internut.com.br/cashflow

Endpoint	Descrição	Uso
`GET /api/cashflow/timeline`	Timeline de 180 dias	Projeção de caixa
`GET /api/cashflow/timeline/summary`	Resumo de caixa	Saldo mínimo, funding
`GET /api/cashflow/alerts`	Alertas financeiros	Riscos de liquidez
`GET /api/cashflow/containers`	Containers	Impacto de importações

2. CSuite CFO-Ops

Base URL: https://csuite.internut.com.br/cfo-ops

Endpoint	Descrição	Uso
`GET /api/view/cost-to-serve/orders`	Pedidos com análise	Margem, prejuízo
`GET /api/view/cost-to-serve/customers`	Clientes	Eficiência logística
`GET /api/view/cost-to-serve/insights`	Insights automáticos	Recomendações
`GET /api/view/vw_cfo_margin_volume_profit`	Margem/Volume/Lucro	Análise agregada

3. CSuite Executive

Base URL: https://csuite.internut.com.br/executive

Endpoint	Descrição	Uso
`POST /v1/policy/evaluate`	Policy Gate	Validação de execução
`POST /v1/memory/query`	Memory API	Precedentes financeiros

4. CSuite Context

Base URL: https://csuite.internut.com.br

Endpoint	Descrição	Uso
`GET /api/executive/dashboard/kpis`	KPIs financeiros	Métricas agregadas

📊 Output Schema

Estrutura do Brief

{
  "context": "string - Análise contextual da situação financeira",
  "cash_flow_summary": {
    "min_balance": "number - Saldo mínimo previsto",
    "min_balance_date": "string - Data do saldo mínimo (YYYY-MM-DD)",
    "max_funding_needed": "number - Necessidade máxima de funding",
    "days_until_negative": "integer|null - Dias até saldo negativo"
  },
  "margin_analysis": {
    "avg_margin_pct": "number - Margem média percentual",
    "loss_orders_count": "integer - Quantidade de pedidos com prejuízo",
    "low_margin_orders_count": "integer - Quantidade de pedidos com margem baixa",
    "top_inefficient_customers": "array - Top clientes ineficientes"
  },
  "alerts": [
    {
      "severity": "string - HIGH|MEDIUM|LOW",
      "message": "string - Mensagem do alerta",
      "date": "string - Data do alerta (YYYY-MM-DD)"
    }
  ],
  "recommendations": [
    {
      "action": "string - Ação recomendada",
      "justification": "string - Justificativa",
      "priority": "string - HIGH|MEDIUM|LOW"
    }
  ],
  "memory_updates": ["string - Atualizações de memória"],
  "should_escalate": "boolean - Se deve escalar",
  "escalation_reason": "string - Razão da escalação"
}

⚙️ Configuração

Variáveis de Ambiente

Criar/editar workflows/scripts/.env:

# URLs dos Serviços
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive
CSUITE_CASHFLOW_URL=https://csuite.internut.com.br/cashflow
CSUITE_CFO_OPS_URL=https://csuite.internut.com.br/cfo-ops
CSUITE_CONTEXT_URL=https://csuite.internut.com.br

# LLM
OPENAI_API_KEY=sk-your-key-here
LLM_MODEL=gpt-4o-mini

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

# Configurações
ORG_ID=0
TIME_WINDOW_DAYS=7

🚀 Execução

Execução Manual

cd workflows/scripts
python cfo_agent_daily_brief.py

Execução Automática (Cron)

cd workflows/scripts
./setup_cron.sh

Ou adicionar manualmente:

crontab -e
# Adicionar:
10 8 * * * cd /path/to/workflows/scripts && /path/to/venv/bin/python cfo_agent_daily_brief.py >> cron.log 2>&1

Horário sugerido: 08:10 (após CEO Agent às 08:00)

📝 Logs e Outputs

Logs

Log do agente: workflows/scripts/cfo_agent.log
Log do cron: workflows/scripts/cron.log

Briefs Gerados

Formato: workflows/scripts/cfo_brief_YYYYMMDD_HHMMSS.json
Conteúdo: Brief completo em JSON
Publicação: Slack (se configurado)

🔍 Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Solução:

# Adicionar ao .env
echo "OPENAI_API_KEY=sk-your-key-here" >> workflows/scripts/.env

Erro: Endpoints retornando 404

Causa: Serviços podem não estar rodando ou URLs incorretas

Solução:
- Verificar se serviços estão ativos
- Confirmar URLs no .env
- O agente continua mesmo com alguns endpoints falhando (graceful degradation)

Brief não está sendo publicado no Slack

Solução:
1. Verificar CFO_BRIEF_WEBHOOK_URL no .env
2. Confirmar que webhook do Slack está ativo
3. Verificar logs: tail -f workflows/scripts/cfo_agent.log

Dados de cashflow não estão sendo coletados

Solução:
1. Verificar se csuite-cashflow está rodando
2. Testar endpoint manualmente:
bash curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline?days=180"
3. Verificar autenticação (se necessário)

📚 Documentação Relacionada

Guia de APIs Cashflow: docs/guides/GUIA_USO_APIS_CASHFLOW.md
Guia de APIs CFO-Ops: docs/guides/GUIA_USO_APIS_CFO_OPS.md
CEO Agent: docs/agent/CEO_AGENT.md (referência de implementação)
Agentes Propostos: docs/agent/AGENTES_PROPOSTOS.md

🎯 Próximos Passos

Fase 1: Completar Implementação Base

[x] YAML de configuração
[x] Script Python principal
[x] README básico
[x] Documentação completa
[x] Saneamento de métricas (CFO Ops Fix)
[ ] Workflows n8n
[ ] Workflows LangGraph
[ ] Testes automatizados

Fase 2: Melhorias

[ ] Integração com mais endpoints
[ ] Dashboard de execuções
[ ] Métricas e observabilidade
[ ] Deploy em Docker Swarm

Fase 3: Expansão

[ ] Análise de budget vs actual
[ ] Previsão de vendas integrada
[ ] Simulação de cenários
[ ] Alertas proativos

Última atualização: 2026-01-10
Versão: 1.1.0

Cfo Agent