# ============================================================
# TEAM OF AGENTS SPEC — Commerce Agent Team
# ============================================================
# A Team of Agents is an AgentWorkflow with "network" topology.
# Unlike a sequential workflow where steps run in a fixed order,
# a network topology lets agents discover and call each other
# dynamically. The orchestrator coordinates, but agents can
# delegate tasks to peers through the A2A protocol.
#
# Use this pattern when:
# - Multiple agents need to collaborate on complex tasks
# - The execution order depends on runtime conditions
# - Agents need to invoke each other (not just a central router)
# ============================================================

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

# ── Identity & Ownership ──
metadata:
  name: commerce-agent-team
  displayName: "Commerce Agent Team"
  team: commerce-platform
  version: 1.2.0
  labels:
    domain: retail
    tier: production
    pattern: team-of-agents

context:
  environment: production

spec:
  # ── Orchestration ──
  # A2A protocol enables agent-to-agent communication.
  # Agents register in a catalog and can discover and call
  # each other through authenticated requests.
  orchestration:
    orchestrator: team-coordinator
    protocol:
      type: A2A
      a2a:
        registry: agent-catalog-prod
        discovery: automatic       # agents auto-register on deploy
        callPolicy: authenticated  # all A2A calls require auth tokens
        timeout: 30s

  # ── Team Members ──
  # Each participant is an Agent spec deployed independently.
  # In network mode, agents can be in different containers,
  # different namespaces, or even different clusters.
  participants:
    - ref: order-fulfillment-agent
      role: fulfillment-lead
      description: "Coordinates payment validation and inventory checks"
      publishTo:
        - agent-catalog-prod
      capabilities:
        - payment-validation
        - inventory-management

    - ref: fraud-detection-agent
      role: risk-assessor
      description: "Evaluates orders for fraud signals"
      publishTo:
        - agent-catalog-prod
      capabilities:
        - fraud-scoring
        - pattern-detection

    - ref: customer-comms-agent
      role: notification-handler
      description: "Handles all outbound customer communications"
      publishTo:
        - agent-catalog-prod
      capabilities:
        - email-dispatch
        - sms-dispatch
        - push-notification

    - ref: returns-processing-agent
      role: returns-handler
      description: "Processes return requests and refunds"
      publishTo:
        - agent-catalog-prod
      capabilities:
        - return-authorization
        - refund-processing

  # ── Network Topology ──
  # In network mode, the dependencies block defines which agents
  # can call which. This is the "wiring diagram" for the team.
  # Unlike sequential mode, multiple paths can be active at once.
  topology:
    mode: network

    # Which agents can invoke which. The fulfillment lead can
    # call the risk assessor and notification handler. The risk
    # assessor can escalate back to fulfillment or trigger comms.
    dependencies:
      - from: fulfillment-lead
        to:
          - risk-assessor
          - notification-handler
          - returns-handler

      - from: risk-assessor
        to:
          - fulfillment-lead      # can escalate back
          - notification-handler   # can trigger fraud alerts

      - from: returns-handler
        to:
          - fulfillment-lead      # can re-route to fulfillment
          - notification-handler   # can notify customer of refund

    # ── Steps ──
    # In network mode, steps define the initial task entry points.
    # Agents can spawn additional tasks dynamically via A2A calls.
    steps:
      - name: process_order
        task: "Coordinate end-to-end order processing"
        performer: fulfillment-lead

      - name: assess_risk
        task: "Evaluate the order for fraud indicators"
        performer: risk-assessor
        trigger: on-demand       # called by fulfillment-lead, not auto

      - name: notify_customer
        task: "Send appropriate customer communication"
        performer: notification-handler
        trigger: on-demand

      - name: handle_return
        task: "Process return request if initiated"
        performer: returns-handler
        trigger: on-demand

  # ── Shared Variables ──
  variables:
    order_id:
      type: string
      required: true
    customer_id:
      type: string
      required: true
    risk_score:
      type: float
      default: 0.0

  # ── Operational ──
  operational:
    checkpointer:
      type: postgres
      secretRef: team-db-credentials
    telemetry:
      tracing: enabled
      metrics: enabled
      logs:
        level: info