ligbox-ops-platform/specs/037-dns-multi-cloudflare-orchestration/cf-agents-sdk-architecture.md

Anexo 037-D — Cloudflare Agents SDK × Orquestração Ligbox

Parent: spec.md · Spec 037
Relacionado: Spec 029 (agentic-ops-runbooks) · Spec 030 (agentic-ops-ui)
Roger · 2026-06-22 · Status: 📋 Arquitectura alvo

---

Contexto

O Cloudflare Agents SDK é realidade hoje:

Padrão	Uso Ligbox
Multi-agent	Agentes especializados (identidade, DNS, mail) colaboram no onboarding
Human-in-the-loop	Decisões críticas: BYO vs Ligbox CF, handoff gestor, purge
Addressable agents	WebSocket wizard ↔ agente; Desk ops ↔ thread A6 Copiloto

Infra: cada agente = Durable Object stateful — hiberna ocioso, acorda sob demanda, storage próprio, MCP para APIs externas (VM112, pfSense, Carbonio).

---

Duas camadas agenticas Ligbox

flowchart TB
  subgraph edge [Cloudflare Edge — Agents SDK]
    O[Orquestrador Onboard]
    I[Agente Identidade]
    D[Agente DNS/CF]
    H[Agente Handoff]
  end
  subgraph vm122 [VM122 Ops Desk — Spec 029]
    A0[Maestro A0]
    A6[Copiloto A6]
    A2[Trilho A2]
  end
  subgraph vm112 [VM112 Wizard API]
    W[FastAPI onboarding]
    C[Carbonio zmprov]
    CF[Cloudflare API]
  end
  O --> I
  O --> D
  O --> H
  I -->|MCP / webhook| W
  D -->|MCP / webhook| W
  H -->|MCP / webhook| W
  W --> C
  W --> CF
  O -->|eventos funil 004| A0
  A6 -->|human-in-the-loop| O
  A2 -->|validação infra| D

Camada	Onde corre	Papel
Edge (CF Agents)	Workers + Durable Objects	Orquestração por cliente/domínio em tempo real no wizard
Ops (Spec 029)	VM122 + Ollama	Vigilância 24/7, inbox humano, runbooks, Copiloto

Não substituem-se — complementam.

---

Roster onboarding (novos agentes edge)

Agente edge	Codename	Responsabilidade	Spec 037
Orquestrador	onboard-maestro	Triagem: Ligbox CF / BYO / registrador; estado do funil	Fluxo decisão
Identidade	proj-mail	Cria proj_{id}@ligbox.com.br, vault senha, entrega wizard	037-C
DNS	cf-zone	provision-zone, apply, dns/verify, multi-conta ligit/itecnologys/ibytera	Fase 1 actual
Handoff	cf-handoff	Convite admin@dominio na CF após go-live	037-B

Cada agente edge tem:

• Durable Object ID = project:{domain} ou session:{onboarding_session_id}
• Memória = project_id, ligbox_project_email, cf_account_id, dns_mode, passos concluídos
• MCP tools = wrappers HTTP para VM112 (/api/onboarding/...)

---

Mapeamento → Roster Spec 029 (A0–A7)

Agente edge	Delega / reporta a	Human-in-the-loop
onboard-maestro	A0 Maestro (tick + audit)	agentic_operator se BYO token inválido 3×
proj-mail	A2 Trilho (infra mail)	Ops se Carbonio falhar
cf-zone	A3 Carta (deliverability)	Cliente escolhe caminho DNS
cf-handoff	A6 Copiloto (thread cliente)	Confirmação antes de convite gestor CF
Falha crítica	A7 Remediador	Sempre humano antes de acção

Role Desk já existente: agentic_operator (Spec 027/029).

---

Human-in-the-loop — pontos obrigatórios

1. Escolha DNS — BYO vs Ligbox vs registrador (wizard UI).
2. Reveal senha proj_* — uma vez; agente pausa até mark_password_delivered.
3. Handoff CF — convite admin@cliente só após dns/verify + account/create OK.
4. Purge / delete zona — nunca automático (Spec 017).

Padrão SDK: agente planeja → persiste estado no DO → aguarda webhook/UI → retoma.

---

Conectividade

Canal	Uso
WebSocket (wizard)	Stream de passos, logs activity, «agente a trabalhar»
MCP → VM112	provision-email, provision-zone, apply, account/create
MCP → CF API	Nativo no Worker (token scoped por conta cliente)
Webhook → VM122	Funil 004: onboard.dns.applied, project.email.created
Scheduling	Retry DNS verify, lembrete NS registrador D+1

---

Fases de implementação

Fase A — Hoje (sem Workers)

• VM112 FastAPI + wizard React (Spec 037 Fase 1) ✅
• project_identity.py scaffold (037-C)
• Agentes 029 observam via webhooks

Fase B — Worker orquestrador único

• 1 Durable Object OnboardSession por sessão wizard
• Delega a VM112 via HTTP (sem multi-agent ainda)
• WebSocket no wizard

Fase C — Multi-agent edge

• 4 agentes especializados + MCP
• Estado partilhado via onboard-maestro (coordenação)
• Human-in-the-loop nos 4 pontos acima

Fase D — Conta CF dedicada por cliente

• cf-zone + Tenant API POST /accounts
• Token scoped por cf_account_id no DO storage

---

Porque Cloudflare Agents aqui

Benefício	Onboarding Ligbox
Stateful por cliente	Sessão longa (dias até NS propagar)
Hibernação	Milhares de onboardings paralelos, custo ~0 entre passos
MCP	VM112/pfSense sem expor tokens no browser
Edge	Baixa latência wizard público onboard.ligbox.com.br

---

Critérios de aceitação (Fase C)

1. Wizard conecta WebSocket ao onboard-maestro DO.
2. proj-mail cria caixa e orquestrador só avança após senha entregue.
3. cf-zone completa apply + verify com estado persistido no DO.
4. Eventos chegam ao Maestro A0 no Desk.
5. Handoff CF exige ack humano na inbox Spec 029.

---

Referências

• Cloudflare Agents — multi-agent
• Agents SDK GitHub
• Ligbox Spec 029 agents-roster.md (A0–A7)
• Ligbox Spec 037 project-email-identity.md