Migração CrewAI → LangGraph, Fases 2–5

Pipeline imperativo virou plataforma declarativa — mas só em um estado

A Fase 1 provou que o grafo equivale ao caminho imperativo em NEGOTIATION. Os outros sete estados continuam vivendo no domain_agent.process_turn do CrewAI legacy. Migrar é o que destrava a remoção da dependência crewai==1.14.4.

Sub-grafos por estado, roteados na entrada

Cada fase encapsula um cluster de estados em seu próprio sub-grafo, mantendo o pattern Fase 1: nós são wrappers finos sobre funções existentes; side-effects ficam fora do grafo (ADR-2).

Cada sub-grafo herda o boundary da Fase 1: decisão dentro, side-effects fora. O roteador é puramente determinístico — zero LLM, zero overhead.

Quatro fases · pattern provado em todas

Re-estimativas pós-AUDIT_2026-05-08 destacadas em laranja. Fase 4 ganha um spike prévio; Fase 5 dobrou de 1 dia para 2–3 dias após reconhecer que substituir domain_agent.process_turn é refactor honesto, não pip uninstall.

TypedDict por sub-grafo, herdando o pattern da Fase 1

ADR-3 da Fase 1 (TypedDict, não Pydantic) foi validada pelo audit. Cada nova fase replica a estratégia — estados pequenos, opcionais, sem overhead de validação.

# services/conversation/langgraph/state.py
class NegotiationState(TypedDict, total=False):
    user_input: str
    redacted_input: str
    relevant_memories: List[Dict]
    context: Dict[str, Any]
    state_manager_ref: Any

    # perception
    sentiment: str
    risk_signal: str
    pii_detected: bool

    # cascade
    path_taken: str
    planner_message: Optional[str]
    outcome: Dict[str, Any]
    ai_telemetry: Dict[str, Any]

# services/conversation/langgraph/auth/state.py
class AuthState(TypedDict, total=False):
    user_input: str
    context: Dict[str, Any]
    state_manager_ref: Any

    # otp flow
    expected_otp: Optional[str]
    submitted_otp: Optional[str]
    otp_verified: bool
    attempts: int

    # outcome (mesmo shape Fase 1)
    outcome: Dict[str, Any]
    next_state: str  # NEGOTIATION | DONE

Pontos de extensão por fase

Cada fase abre um sub-grafo novo e adiciona um branch no roteador central. As funções abaixo são os únicos pontos cruzados entre fases — o resto vive isolado em sub-pacotes.

# Roteador determinístico no entry-point.
# Hoje (pós-Fase 1) só NEGOTIATION tem branch; F2-F4 expandem.

def _dispatch_message_to_graph(self, user_input: str) -> Dict:
    from services.conversation.langgraph.runtime import is_langgraph_enabled

    if not is_langgraph_enabled():
        return self._legacy_dispatch(user_input)

    state = self.state
    if state == "NEGOTIATION":        # Fase 1 (shipped)
        from .langgraph.runtime import run_graph
        return run_graph(self, user_input, ...)
    elif state == "AUTH":              # Fase 2 ✦ NEW
        from .langgraph.auth.runtime import run_auth_graph
        return run_auth_graph(self, user_input)
    elif state in {"ONBOARDING", "SALES", "PLANS", "CONTRACT"}:  # F3
        from .langgraph.contractor.runtime import run_contractor_graph
        return run_contractor_graph(self, user_input)
    elif state in {"CHECKOUT", "INGESTION"}:  # Fase 4
        from .langgraph.ops.runtime import run_ops_graph
        return run_ops_graph(self, user_input)

    return self._legacy_dispatch(user_input)  # bypass safety net

Arquitetura aditiva: cada fase adiciona um branch sem tocar nos anteriores. _legacy_dispatch permanece como rede de segurança até Fase 5.

# Pattern Fase 1: nó como wrapper-fino sobre função existente.

def node_check_otp(state: AuthState) -> Dict:
    from services.conversation.auth_handler import verify_otp

    submitted = state.get("user_input", "").strip()
    expected  = state.get("expected_otp")
    verified  = verify_otp(submitted, expected)   # lógica intocada

    return {
        "submitted_otp": submitted,
        "otp_verified": verified,
        "attempts": state.get("attempts", 0) + 1,
    }

def route_after_otp(state: AuthState) -> str:
    if state["otp_verified"]:
        return "transition_to_negotiation"
    if state.get("attempts", 0) >= 3:
        return "escalate_to_handoff"
    return "prompt_retry"

# Decisão a fechar no spike de 2 h pré-Fase 4:
#   Estratégia A (call-direct):
def node_create_pix_charge(state):
    from services.payment.asaas import create_pix
    payment = create_pix(amount=state["amount"], debtor_id=state["debtor_id"])
    return {"payment_id": payment.id, "qr_code": payment.qr_code}

#   Estratégia B (re-decoração @tool):
from langchain_core.tools import tool

@tool
def create_pix_tool(amount: int, debtor_id: str) -> Dict:
    from services.payment.asaas import create_pix
    return create_pix(amount, debtor_id).to_dict()

# O spike decide qual estratégia + adiciona ADR-7 ao DESIGN_F4.

Operacional — deploy, rollback, monitoração

Cenários que precisam de teste explícito

Categorias por fase

Cronograma proposto

Pré-condição comum: ≥5 dias estável em prod entre fases. As datas abaixo assumem início imediato após o gate liberar; ajustar conforme ramo paralelo de V2.1.

• 2026-05-07 · sext
  Fase 1 — NEGOTIATION shipped
  Subpacote services/conversation/langgraph/ em prod. Flag MIGRATE_NEGOTIATION_TO_LANGGRAPH=false após smoke (rollback drill 50 s validado).
• 2026-05-12 · ter (≥5 d)
  Gate Fase 2 libera
  Pré-condição cumprida: 5 dias estáveis pós-Fase 1 + deepeval golden suite verde. Gate operacional para start de F2.
• ~2026-05-13 / 14 · ~1–2 d
  Fase 2 — AUTH
  Sub-grafo AUTH. Sem LLM, deve fechar em 1 sessão. MIGRATE_AUTH_TO_LANGGRAPH=true em smoke prod.
• ~2026-05-19 · seg
  Gate Fase 3 libera
  5 dias estáveis pós-F2. Pre-Phase audit: grep -rn "process_turn" em ONBOARDING/SALES/PLANS/CONTRACT.
• ~2026-05-20 / 22 · ~2–3 d
  Fase 3 — Estados Contractor
  4 sub-grafos. Smoke E2E: contractor novo → subaccount Asaas → primeira cobrança PIX (validação end-to-end com fluxo MULTI_TENANT_ASAAS).
• ~2026-05-27 · ter
  Spike 2 h — Tool Strategy
  Decide call-direct vs @tool. Output: ADR-7 anexado a DESIGN_F4. Bloqueia merge da Fase 4.
• ~2026-05-27 / 31 · ~3–4 d
  Fase 4 — CHECKOUT + INGESTION
  Primeiros nós com tools reais (Asaas, Bling/Omie/Sankhya). Smoke: 1 PIX + 1 import CSV via WhatsApp.
• ~2026-06-05 · sex
  Gate Fase 5 libera
  5 dias estáveis pós-F4. Soak: zero regressão, zero novos handoffs além do baseline.
• ~2026-06-06 / 09 · ~2–3 d
  Fase 5 — Cleanup
  Refactor honesto de process_turn. pip uninstall crewai + git rm -r agents/ crew/. requirements.txt sem crewai>=1.14.
• ~2026-06-10 · seg
  Archive — CREWAI_TO_LANGGRAPH completo
  SHIPPED_F5.md final + memory entry. V2 plataforma 100% LangGraph.

Avisos críticos · contratos · riscos

Mapa de mudanças por fase