# ============================================================
# AGENT WORKFLOW SPEC — Order Fulfillment Workflow
# ============================================================
# An AgentWorkflow orchestrates multiple agents into a multi-step
# process. It declares who participates, how they collaborate,
# and in what order steps execute. This is the "sequential" pattern:
# steps run one after another, each building on the previous state.
# ============================================================

apiVersion: agents.platform.io/v1
kind: AgentWorkflow

# ── Identity & Ownership ──
metadata:
  name: order-fulfillment-workflow
  displayName: "Order Fulfillment Pipeline"
  team: commerce-platform
  version: 3.0.0
  labels:
    domain: retail
    tier: production
    pattern: sequential

context:
  environment: production

spec:
  # ── Orchestration ──
  # Defines who coordinates the workflow and which communication
  # protocol agents use to interact. "local" means agents run
  # in the same process and communicate through shared state.
  # "A2A" means agents discover each other through a registry.
  orchestration:
    orchestrator: platform-router
    protocol:
      type: local
      local:
        serviceDiscovery: dns

  # ── Participants ──
  # Each participant references an Agent spec by name.
  # The role field gives this participant a handle that steps
  # can reference as a "performer."
  participants:
    - ref: order-fulfillment-agent
      role: payment-validator
      description: "Validates payment and flags exceptions"

    - ref: inventory-checker-agent
      role: stock-verifier
      description: "Checks warehouse inventory by SKU"

    - ref: shipping-dispatch-agent
      role: shipper
      description: "Generates shipping labels and dispatches"

    - ref: notification-agent
      role: notifier
      description: "Sends order confirmation to customer"

  # ── Topology ──
  # Mode defines how steps relate to each other:
  #   sequential  — steps execute one after another
  #   parallel    — steps execute concurrently
  #   network     — agents call each other dynamically (see team spec)
  #   aggregate   — fan-out then merge results
  topology:
    mode: sequential

    # ── Steps ──
    # Each step has a name, a task description, and a performer
    # (which must match a participant role or an inline agent).
    # Conditional routing uses the "condition" field with a mapping.
    steps:
      - name: validate_payment
        task: "Verify payment status for the incoming order"
        performer: payment-validator
        config:
          retry:
            maxAttempts: 2

      - name: route_on_payment
        task: "Route based on payment validation result"
        type: conditional
        condition:
          field: payment_status
          mapping:
            approved: check_inventory
            flagged: exception_review

      - name: exception_review
        task: "Human reviews flagged payment"
        type: human
        interrupt: before        # pauses workflow for human input
        config:
          queue: payment-exceptions
          timeout: 24h

      - name: check_inventory
        task: "Confirm inventory availability for all line items"
        performer: stock-verifier

      - name: dispatch_shipping
        task: "Generate shipping label and hand off to carrier"
        performer: shipper
        config:
          retry:
            maxAttempts: 3
            backoff: exponential

      - name: send_confirmation
        task: "Send order confirmation email to customer"
        performer: notifier

  # ── Variables ──
  # Workflow-level variables that steps can read/write.
  variables:
    order_id:
      type: string
      required: true
    customer_email:
      type: string
      required: true

  # ── Operational ──
  operational:
    timeouts:
      total: 48h             # end-to-end including HITL wait
    checkpointer:
      type: postgres
      secretRef: workflow-db-credentials