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

Execution Orchestrator Agent

⚡ Execution Orchestrator Agent — Manual Técnico

Versão: 1.0
Data: 2026-01-22
Status: Produção ✅

📋 Visão Geral

O Execution Orchestrator Agent é responsável por executar ações com confiabilidade:
- Enfileira ações (WhatsApp, CRM, etc)
- Processa com retry automático
- Circuit breaker por provider
- Dead Letter Queue para falhas
- Policy Guardian para validação

Posição no Fluxo

Quote Builder → Execution Orchestrator → WhatsApp / CRM
           (artefatos)            (envio + registro)

🔌 API Endpoints

Base URL

https://csuite.internut.com.br/exec

Porta Local: 8021

Endpoints de Execução

Método Endpoint Descrição
POST /exec/run Inicia execução de plano
GET /exec/status/{correlation_id} Status do caso
POST /exec/worker/tick Processa fila
POST /exec/retry/{action_id} Retry manual
POST /exec/cancel/{correlation_id} Cancela caso
GET /health Health check

Endpoints Control Tower

Método Endpoint Descrição
GET /control/exec/cases Lista casos
GET /control/exec/dlq Dead Letter Queue
GET /control/exec/stats Estatísticas
GET /control/providers Status providers
POST /control/providers/{name}/{channel}/reset Reset provider

📥 Executar Plano

Request

POST /exec/run
Content-Type: application/json

{
  "correlation_id": "CASE-8841-202601221720-test",
  "client_id": 8841,
  "seller_id": 22,
  "channel": "whatsapp",
  "quote_id": "QT-2026-000001",
  "quote_version": 1,
  "artifacts": {
    "whatsapp_text": "Olá! Segue sua proposta...",
    "pdf_url": "https://csuite-quotes-prod.s3.amazonaws.com/quotes/QT-2026-000001/QT-2026-000001-v1.pdf"
  },
  "actions": [
    {
      "action_type": "whatsapp_send",
      "payload": {
        "to": "5511999887766",
        "text": "{{whatsapp_text}}",
        "seller_phone": "5519991552222"
      },
      "target": "5511999887766",
      "max_attempts": 5
    },
    {
      "action_type": "crm_upsert_quote",
      "payload": {
        "quote_id": "{{quote_id}}",
        "client_id": "{{client_id}}",
        "status": "sent"
      },
      "max_attempts": 3
    },
    {
      "action_type": "crm_create_task",
      "payload": {
        "title": "Follow-up proposta {{quote_id}}",
        "client_id": "{{client_id}}",
        "seller_id": "{{seller_id}}"
      },
      "max_attempts": 3
    }
  ]
}

Response

{
  "correlation_id": "CASE-8841-202601221720-test",
  "status": "running",
  "actions_queued": 3,
  "message": "Queued 3 actions"
}

🔄 Processar Fila

Request

POST /exec/worker/tick?batch_size=25

Response

{
  "processed": 3,
  "success": 3,
  "failed": 0,
  "dead": 0,
  "cases_recomputed": 1
}

📊 Status do Caso

Request

GET /exec/status/CASE-8841-202601221720-test

Response

{
  "correlation_id": "CASE-8841-202601221720-test",
  "client_id": 8841,
  "seller_id": 22,
  "channel": "whatsapp",
  "status": "success",
  "actions": [
    {
      "id": 1,
      "action_type": "whatsapp_send",
      "status": "success",
      "attempts": 1,
      "max_attempts": 5,
      "provider_ref": "wamid.abc123",
      "finished_at": "2026-01-22T17:27:49"
    },
    {
      "id": 2,
      "action_type": "crm_upsert_quote",
      "status": "success",
      "attempts": 1,
      "max_attempts": 3,
      "provider_ref": "crm.quote.xyz789"
    }
  ]
}

🎯 Actions Disponíveis

1. WhatsApp Send

{
  "action_type": "whatsapp_send",
  "payload": {
    "to": "5511999887766",
    "text": "Mensagem",
    "seller_phone": "5519991552222",
    "image": "https://url-opcional.jpg"
  }
}

2. CRM Upsert Quote

{
  "action_type": "crm_upsert_quote",
  "payload": {
    "quote_id": "QT-2026-000001",
    "client_id": 8841,
    "seller_id": 22,
    "status": "sent",
    "total": 496.00
  }
}

3. CRM Create Task

{
  "action_type": "crm_create_task",
  "payload": {
    "title": "Follow-up proposta",
    "client_id": 8841,
    "seller_id": 22,
    "priority": "high"
  }
}

4. Escalate Human

{
  "action_type": "escalate_human",
  "payload": {
    "reason": "Cliente solicitou falar com gerente",
    "priority": "high"
  }
}

🔒 Policy Guardian

Valida ações antes de executar:

Action Regra Resultado
whatsapp_send Texto obrigatório, ≤650 chars allow/deny
crm_upsert_quote quote_id obrigatório allow/deny
crm_create_task title obrigatório allow/deny

⚡ Circuit Breaker

⚙️ Configuração

Variáveis de Ambiente

# Database
MYSQL_DSN=mysql+pymysql://user:pass@host:3306/csuite_execution

# Worker
EXEC_WORKER_BATCH_SIZE=25
EXEC_WORKER_LOCK_SECONDS=30

# Circuit Breaker
PROVIDER_FAILURE_THRESHOLD=10
PROVIDER_COOLDOWN_MINUTES=5

# CRM Integration
LEADS_AGENT_URL=http://localhost:3002
CRM_USE_STUB=false

# WhatsApp Integration
WHATSAPP_USE_STUB=false
WHATSAPP_API_URL=https://dev.whatsapp.internut.com.br/api
WHATSAPP_API_TOKEN=<token>
WHATSAPP_DEFAULT_SELLER=5519991552222

# App
LOG_LEVEL=INFO

🔗 Integrações

WhatsApp API

POST https://dev.whatsapp.internut.com.br/api/sessions/{seller_phone}/send

CRM (Leads-Agent)

POST http://localhost:3002/leads
POST http://localhost:3002/api/superbot/chatbot/log-event

🐳 Deploy

Desenvolvimento Local

cd c-suite/agents/execution-orchestrator
./scripts/run-local.sh

Docker Swarm (Prod)

./deploy.sh --build

O stack inclui:
- exec-orchestrator: API principal (2 réplicas)
- exec-worker: Processamento de fila (1 réplica)

📊 Banco de Dados

Schema: csuite_execution

Tabela exec_case

Campo Tipo Descrição
correlation_id VARCHAR(80) ID único do caso
client_id BIGINT ID do cliente
seller_id BIGINT ID do vendedor
status VARCHAR(20) running/success/failed/partial

Tabela exec_action

Campo Tipo Descrição
idempotency_key VARCHAR(64) Chave única
action_type VARCHAR(40) Tipo da ação
status VARCHAR(20) pending/running/success/failed/dead
attempts INT Tentativas
provider_ref VARCHAR(200) Ref do provider

Tabela exec_event

📊 Métricas

Métrica Valor
Actions/minuto ~100
Success rate > 95%
Avg retry < 2
DLQ rate < 1%

📝 Changelog

Data Versão Descrição
2026-01-22 1.0 MVP completo com WhatsApp e CRM

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir