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.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](https://developers.cloudflare.com/agents/) é **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

```mermaid
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](./project-email-identity.md) |
| **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](./client-cf-account-lifecycle.md) |

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](https://developers.cloudflare.com/agents/)
- [Agents SDK GitHub](https://github.com/cloudflare/agents)
- Ligbox Spec 029 `agents-roster.md` (A0–A7)
- Ligbox Spec 037 `project-email-identity.md`