---

# Hybrid Agentic Workflow Architecture

**Enterprise Orchestration & Micro-Agent Adapters**

This document outlines the architectural blueprint for transitioning a deterministic payment and routing flow engine into a **Hybrid Agentic Workflow System**. It defines the interplay between a global LLM-driven Orchestrator and specialized, MCP-enabled micro-agent adapters built within an Elixir/OTP environment.

---

## 1. The Orchestrator Agent (Global Supervisor)

The Orchestrator Agent sits above the deterministic routing pipeline. It is responsible for translating high-level business goals into structural Directed Acyclic Graphs (DAGs) and acting as a cognitive escalation path when the deterministic state machine encounters ambiguity.

### 1.1 Memory and Context Management

To ensure safe, compliant, and optimized routing (especially in high-stakes environments like Licensed Financial Institutions and PCI-compliant networks), the Orchestrator requires tiered memory:

* **Short-Term Context (Session/Transaction):** Maintains the `Shared State Object` of the current transaction. This includes the initial payload, intermediate risk scores, and temporal execution paths.
* **Long-Term Memory (Optimization & Learning):** Ingests historical Telemetry data (e.g., `:telemetry.execute` events, circuit breaker trips, and `:fuse` logs). If a specific generated flow historically results in high latency or gateway timeouts, the Orchestrator adjusts future JSON graph generation to prioritize fallback routes.
* **Context Window Assembly:** When a human operator requests a new flow, the prompt is injected with (a) the current RouteTable state, and (b) the available MCP schema definitions of all loaded Elixir adapter modules.

### 1.2 Orchestration Patterns

* **Generative Graph Synthesis:** The LLM does not execute transactions directly. It generates the structural routing logic.
* **Human-In-The-Loop (HITL):** Before any generative flow is published to the `MwRouter.RouteTable` (ETS), the Orchestrator outputs a visual representation for a human architect to review and approve.
* **Cognitive Escalation (Fallback):** If a DAG execution reaches an `:all_failed` state across standard adapters, the payload can be routed back to the Orchestrator to dynamically infer the root cause (e.g., parsing unstructured ISO 8583 error strings) and suggest a targeted retry.

### 1.3 Canvas Node JSON Schema (Flow Builder Target)

The Orchestrator synthesizes output into a strict JSON contract compatible with visual canvas libraries (e.g., jsPlumb). This translates the AI's intent into renderable nodes and connections.

```json
{
  "flow_id": "payment.dag_dynamic_routing",
  "metadata": {
    "generated_by": "orchestrator_v1",
    "goal": "Route high-value transactions through fraud check, fallback on error."
  },
  "nodes": [
    {
      "id": "node_request_1",
      "type": "RequestNode",
      "position": { "left": 100, "top": 200 },
      "data": { "endpoint": "/api/v1/messages/dynamic.checkout" }
    },
    {
      "id": "node_adapter_fraud",
      "type": "AgenticAdapter",
      "position": { "left": 400, "top": 200 },
      "data": {
        "module": "AdapterFraud",
        "priority": 1,
        "timeout_ms": 3000,
        "mcp_capability": "adapter_fraud_score"
      }
    }
  ],
  "connections": [
    {
      "source": "node_request_1",
      "target": "node_adapter_fraud",
      "type": "FlowLine",
      "anchors": ["Right", "Left"]
    }
  ]
}

```

---

## 2. Adapter / Node Agents (The Workers)

Adapters handle the "south-side" integration with external systems (Core Banking APIs, Mastercards KMP, Fraud APIs). In this architecture, adapters are elevated from simple HTTP wrappers to **Autonomous Micro-Agents** via the Model Context Protocol (MCP).

### 2.1 The Agentic Adapter Design

An Agentic Adapter operates strictly within its domain boundary. It exposes its capabilities to the Orchestrator, but executes its local task using the most efficient tool available—whether that is a simple Regex parser, a localized XGBoost ML model for fraud, or an Elixir Finch HTTP call.

* **Stateless Execution:** Handled via `MwRouter.DagExecutor`. Adapters do not hold transaction state; they receive the current state, perform their localized goal, and return a mutated state.
* **Deterministic Fallbacks:** Each adapter defines strict physical guardrails (e.g., 5 errors in 10s trips the `:fuse`). If the local agent cannot recover, it yields a standardized `{:error, reason}` to the Supervisor.

### 2.2 Model Context Protocol (MCP) Integration

To allow the Orchestrator to "discover" these tools at runtime, the `MwKernel.Adapter` behaviour is extended. Upon application boot, the platform crawls all compiled Elixir modules and extracts their MCP schemas.

**Elixir Implementation Example:**

```elixir
defmodule AdapterFraud do
  @moduledoc "Fraud-scoring agentic adapter."
  @behaviour MwKernel.Adapter

  @impl MwKernel.Adapter
  def mcp_tool_definition do
    %{
      name: "adapter_fraud_score",
      description: "Evaluates financial payloads for risk and compliance anomalies.",
      inputSchema: %{
        type: "object",
        properties: %{
          amount: %{type: "number", description: "Transaction value in major currency units."},
          merchant_id: %{type: "string", description: "Registered merchant identifier."}
        },
        required: ["amount", "merchant_id"]
      }
    }
  end

  @impl MwKernel.Adapter
  def send(state, %MwKernel.Message{} = msg) do
    # 1. Local Agent processing (Data mapping, ML scoring, API calls)
    # 2. Return strict JSON contract to DAG Executor
  end
  
  # ... health_check/1, connect/1, disconnect/1
end

```

### 2.3 The Feedback Loop

1. **Execution:** The `MwRouter.Dispatcher` pushes traffic through the deployed DAG.
2. **Telemetry:** `AdapterFraud` processes messages and emits `:telemetry.execute([:adapter_fraud, :request], %{count: 1}, %{status: :error})`.
3. **Aggregation:** An asynchronous Broadway pipeline or GenServer aggregates these metrics and updates the Orchestrator's Long-Term Memory.
4. **Self-Correction:** The next time the Orchestrator is prompted to optimize the `payment.dag_dynamic_routing` flow, it accesses this context, recognizes the high error rate, and automatically wires a secondary `FallbackAdapter` into the jsPlumb JSON topology.

---

## 3. Coexistence with the Current Flow Builder (Non-Breaking by Design)

This platform must support **both**:

1. **Human-authored flows** created in the current Flow Builder.
2. **Agent-generated proposals** that are reviewed and optionally published by humans.

The existing deterministic execution path remains the source of truth. Agentic capability is additive.

### 3.1 Compatibility Principles

* **No disruption to existing runtime:** `MwRouter.Pipeline`, `MwRouter.DagExecutor`, `MwRouter.Dispatcher`, and `MwRouter.RouteTable` continue unchanged for currently published flows.
* **No forced migration of existing flows:** all existing `canvas_json` records stay valid.
* **Human remains publisher of record:** agent output is a draft/proposal until explicitly approved.
* **Same execution engine for both paths:** once published, human and agent-generated flows are executed identically by the same deterministic DAG engine.

### 3.2 Dual Authoring Model

The system will expose two authoring lanes:

* **Lane A: Human Builder (current behavior)**
  * User creates/edits nodes manually.
  * Save persists draft.
  * Publish writes active route to ETS + DB-backed state.

* **Lane B: Agentic Assistant (new behavior)**
  * User provides intent/goal to Orchestrator.
  * Orchestrator returns a **proposal payload** compatible with current builder schema.
  * Proposal opens in the same Flow Builder canvas as editable draft.
  * Human reviews, edits if needed, then publishes.

This keeps a single canonical editor and avoids split UX or parallel graph formats.

### 3.3 Canonical Contract Strategy (Critical)

To keep compatibility with the current system:

* The canonical flow contract remains the existing Flow Builder/DAG contract.
* Agentic output must be normalized into this existing contract before save/publish.
* Any richer AI metadata (goal, rationale, confidence) is stored as optional metadata and never required by runtime execution.

**Rule:** Runtime must never depend on LLM-specific fields.

### 3.4 Versioning and Backward Compatibility

* Keep current `canvas_version` behavior.
* Introduce optional metadata namespace for agentic context, for example:
  * `metadata.generated_by`
  * `metadata.generation_mode` (`human`, `agent_assisted`, `agent_generated`)
  * `metadata.proposal_id`
* If metadata is missing, flow is treated exactly as today.

### 3.5 Governance and Safety

* **Draft-only generation:** Orchestrator cannot directly publish to RouteTable.
* **Approval workflow:** publish action requires authenticated human role.
* **Auditability:** store who requested generation, who approved, and final diff between proposal and published flow.
* **Policy gate before publish:** validate adapter allow-list, timeout bounds, fallback policy, and tenant constraints.

---

## 4. Implementation Delta Plan (Aligned to Existing System)

### Phase 1: Additive Foundation (No Runtime Behavior Change)

1. Add an **Orchestrator Proposal Service** that produces draft flow JSON only.
2. Add a **normalizer** that converts agent output to current canvas/node/connection format.
3. Add proposal persistence (`proposal_id`, status, requested_by, approved_by, timestamps).
4. Keep publish path unchanged (same Flow Builder publish action).

### Phase 2: MCP Discovery Without Breaking Adapters

1. Extend adapter behavior with optional MCP callback (non-breaking default implementation).
2. Registry extracts MCP definitions only when callback exists.
3. Existing adapters without MCP metadata continue working unchanged.

### Phase 3: HITL UX Integration

1. In Flow Builder, add "Generate with AI" entry point.
2. Load proposal into editable canvas.
3. Show structured validation warnings before save/publish.
4. Preserve existing manual editing and publish flow as default path.

### Phase 4: Telemetry-Guided Suggestions (Not Auto-Publish)

1. Aggregate adapter error/latency/fallback telemetry.
2. Produce optimization recommendations as draft proposals.
3. Require human approval for every production publish.

---

## 5. Explicit "Will Not Change" List

To protect current operations, the following remain as-is during initial rollout:

* Existing Flow Builder save and publish semantics.
* Existing DAG execution and deterministic fallback behavior.
* Existing route lookup and tenant routing behavior.
* Existing adapter invocation contract (`connect` -> `send` -> response/error).
* Existing circuit breaker guardrails and telemetry emission patterns.

---

## 6. Outcome

This approach supports a **hybrid authoring future** while preserving your current stable routing core:

* Human-created flows continue exactly as today.
* Agentic flows are introduced safely as proposals.
* Both converge to one deterministic runtime contract.
* Governance, audit, and operational safety remain intact.

---

## 7. Implementation Reference

For concrete Phase 1 implementation details (API payloads, proposal table schema, lifecycle states, normalizer contract, and rollout criteria), see:

* `docs/AI-Agentic/phase1-technical-spec.md`