🏠 Início / 📚 Documentação / Guias de Uso / Channel Agents Implementation Plan

Channel Agents Implementation Plan

🌱 Plano de Implementação: Agentes de Canal

Objetivo: Implementar 5 novos agentes para gerenciamento completo do ciclo de vida do canal de revenda.

Base conceitual: Ver 📘books & chats/Partes do processo de Plantação.md

📋 Visão Geral

Agentes a Implementar

# Agente Código Propósito
1 Account State Agent account-state Batimento cardíaco do canal - declara estado de cada conta
2 Onboarding Agent onboarding Engenharia de sobrevivência - primeiros 30-60 dias
3 Reactivation Agent reactivation Estratégias de recuperação de contas paradas
4 Qualification Agent qualification Gate de entrada - decide se vale cultivar
5 Channel Performance Agent channel-performance Aprendizado e evolução de políticas

Ordem de Implementação (Dependências)

1. Account State Agent     (sem dependências - FUNDAÇÃO)
           ↓
2. Onboarding Agent        (depende de Account State)
           ↓
3. Reactivation Agent      (depende de Account State)
           ↓
4. Qualification Agent     (usa estados para feedback)
           ↓
5. Channel Performance     (consome dados de todos)

📐 Estrutura Padrão de Cada Agente

Seguindo o padrão existente (nba, scia, pricing):

c-suite/agents/{agent-name}/
├── .env.example           # Variáveis de ambiente
├── Dockerfile             # Container definition
├── README.md              # Documentação do agente
├── docker-stack.yml       # Deploy Swarm
├── deploy.sh              # Script de deploy
├── requirements.txt       # Dependências Python
├── main.py                # Entry point FastAPI
├── app/
│   ├── __init__.py
│   ├── models.py          # Pydantic models
│   ├── database.py        # Conexão DB
│   ├── repository.py      # Queries SQL
│   ├── heuristics.py      # Lógica de decisão
│   └── settings.py        # Configurações
├── routes/
│   ├── __init__.py
│   ├── core.py            # Health, info endpoints
│   └── {agent}.py         # Endpoints específicos
├── policies/
│   └── {agent}.py         # Definições de policy
└── sql/
    ├── schema.sql         # DDL tables
    └── views.sql          # Views de monitoramento

🔗 Integração com Seller Cockpit e Outros Clientes

Endpoints Padronizados

Todos os agentes seguem o mesmo padrão de API:

Endpoint Método Descrição
/ GET Info do serviço
/health GET Health check
/v1/{agent}/evaluate POST Avaliar situação
/v1/{agent}/decide POST Tomar decisão
/v1/{agent}/outcome POST Registrar resultado
/v1/{agent}/history/{entity_id} GET Histórico de decisões

Consumo pelo Seller Cockpit

// seller-cockpit/backend/src/services/{agent}.service.js
const {agent}Service = {
    evaluate: (data) => axios.post(`${BASE_URL}/v1/{agent}/evaluate`, data),
    decide: (data) => axios.post(`${BASE_URL}/v1/{agent}/decide`, data),
    getHistory: (id) => axios.get(`${BASE_URL}/v1/{agent}/history/${id}`)
};

📑 CHECKLISTS DE IMPLEMENTAÇÃO

1️⃣ Account State Agent

Propósito: Declarar o estado atual de cada conta/revenda baseado em dados objetivos.

📍 Localização

c-suite/agents/account-state/

📊 Estados Gerenciados

Estado Trigger Duração Típica
NEW Cadastro criado 0-7 dias
ACTIVATING Primeira compra 7-60 dias
ACTIVE Segunda compra confirmada Indefinido
STALLED Sem compra > ciclo esperado × 1.5 Até ação
AT_RISK Stalled + 2+ contatos falharam Até ação
CHURN At Risk + tempo sem resposta Permanente

✅ Checklist de Implementação

Fase 1: Estrutura Base

Fase 2: Schema SQL

Fase 3: Modelos e Lógica

Fase 4: Routes/API

Fase 5: Policies

Fase 6: Docker & Deploy

Fase 7: Integração Seller Cockpit

Fase 8: Testes & Documentação

2️⃣ Onboarding Agent

Propósito: Gerenciar os primeiros 30-60 dias de uma nova revenda.

📍 Localização

c-suite/agents/onboarding/

✅ Checklist de Implementação

Fase 1: Estrutura Base

Fase 2: Schema SQL

CREATE TABLE IF NOT EXISTS channel_onboarding_activities (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
plan_id BIGINT NOT NULL,
activity_type ENUM('WELCOME', 'TRAINING', 'FIRST_ORDER', 'FOLLOW_UP', 'CHECK_IN', 'SECOND_ORDER') NOT NULL,
scheduled_date DATE,
completed_date DATE,
status ENUM('PENDING', 'COMPLETED', 'SKIPPED', 'FAILED') DEFAULT 'PENDING',
notes TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,

  INDEX idx_plan (plan_id),
  INDEX idx_scheduled (scheduled_date, status)

);
```
- [ ] Executar schema no RDS DEV

Fase 3: Modelos e Lógica

Fase 4: Routes/API

Fase 5: Integração Account State

Fase 6: Docker & Deploy

Fase 7: Integração Seller Cockpit

Fase 8: Testes & Documentação

3️⃣ Reactivation Agent

Propósito: Estratégias controladas para recuperar contas STALLED/AT_RISK.

📍 Localização

c-suite/agents/reactivation/

✅ Checklist de Implementação

Fase 1: Estrutura Base

Fase 2: Schema SQL

Fase 3: Modelos e Lógica

Fase 4: Routes/API

Fase 5: Integração com Outros Agentes

Fase 6: Docker & Deploy

Fase 7: Integração Seller Cockpit

Fase 8: Testes & Documentação

4️⃣ Qualification Agent

Propósito: Gate de entrada - decide se vale cultivar uma revenda.

📍 Localização

c-suite/agents/qualification/

✅ Checklist de Implementação

Fase 1: Estrutura Base

Fase 2: Schema SQL

Fase 3: Modelos e Lógica

Fase 4: Routes/API

Fase 5: Integração

Fase 6: Docker & Deploy

Fase 7: Integração (Admin/Backend)

Fase 8: Testes & Documentação

5️⃣ Channel Performance Agent

Propósito: Aprender padrões e propor ajustes de políticas.

📍 Localização

c-suite/agents/channel-performance/

✅ Checklist de Implementação

Fase 1: Estrutura Base

Fase 2: Schema SQL

CREATE TABLE IF NOT EXISTS channel_performance_metrics (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
org_id INT NOT NULL DEFAULT 1,
period_date DATE NOT NULL,
period_type ENUM('DAILY', 'WEEKLY', 'MONTHLY') NOT NULL,

  -- Onboarding Metrics
  onboarding_started INT DEFAULT 0,
  onboarding_completed INT DEFAULT 0,
  onboarding_failed INT DEFAULT 0,
  onboarding_rate DECIMAL(5,2),
  avg_activation_days DECIMAL(5,1),

  -- Reactivation Metrics
  reactivation_attempts INT DEFAULT 0,
  reactivation_won INT DEFAULT 0,
  reactivation_rate DECIMAL(5,2),
  avg_reactivation_cost DECIMAL(10,2),

  -- State Metrics
  accounts_new INT DEFAULT 0,
  accounts_activating INT DEFAULT 0,
  accounts_active INT DEFAULT 0,
  accounts_stalled INT DEFAULT 0,
  accounts_at_risk INT DEFAULT 0,
  accounts_churned INT DEFAULT 0,

  -- Revenue Metrics
  total_revenue DECIMAL(15,2),
  avg_margin DECIMAL(5,2),

  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,

  UNIQUE KEY uk_period (org_id, period_date, period_type),
  INDEX idx_date (period_date)

);
```
- [ ] Executar schema no RDS DEV

Fase 3: Modelos e Lógica

Fase 4: Routes/API

Fase 5: Integração

Fase 6: Docker & Deploy

Fase 7: Integração Seller Cockpit

Fase 8: Testes & Documentação

📅 Cronograma Sugerido

Semana Agente Foco
1 Account State Estrutura + Schema + API
2 Account State Integração Seller Cockpit
3 Onboarding Estrutura + Schema + API
4 Onboarding Integração + Testes
5 Reactivation Estrutura + Schema + API
6 Reactivation Integração + Testes
7 Qualification Implementação completa
8 Channel Performance Implementação completa

🔧 Comandos Úteis

Criar estrutura de um agente

cd /home/ec2-user/enviroment/apps/c-suite-ecosystem/c-suite/agents
mkdir -p {agent-name}/{app,routes,policies,sql}
touch {agent-name}/{main.py,requirements.txt,.env.example,Dockerfile,README.md}
touch {agent-name}/app/{__init__.py,models.py,database.py,repository.py,heuristics.py,settings.py}
touch {agent-name}/routes/{__init__.py,core.py}
touch {agent-name}/sql/{schema.sql,views.sql}

Deploy de um agente

cd /home/ec2-user/enviroment/apps/c-suite-ecosystem/c-suite/agents/{agent-name}
./deploy.sh

Executar SQL

mysql -h vallery.catmgckfixum.sa-east-1.rds.amazonaws.com -u robsonrr -p csuite_context < sql/schema.sql

📚 Referências

Documento criado: 2026-01-24
Última atualização: 2026-01-24

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir