# ============================================================
# AGENT SPEC — Order Fulfillment Agent
# ============================================================
# A single AI agent declared as a version-controlled asset.
# This spec captures everything the platform needs to deploy,
# observe, and govern this agent — no imperative code required.
# ============================================================

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

# ── Identity & Ownership ──
# Every agent has a unique name, an owning team, and a version.
# These fields drive catalog registration, RBAC, and audit trails.
metadata:
  name: order-fulfillment-agent
  displayName: "Order Fulfillment Agent"
  team: commerce-platform
  version: 2.1.0
  labels:
    domain: retail
    tier: production
    data-class: internal

# ── Context ──
# The environment tag controls which conformance profile applies.
# An agent promoted from dev → staging → production must pass
# increasingly strict validation at each gate.
context:
  environment: production    # playground | dev | test | stage | production

# ── Core Behavior ──
# Role, goal, and system prompt define what this agent does.
# These are the fields a prompt engineer owns.
spec:
  role: "Order fulfillment coordinator"
  goal: "Validate payment, verify inventory, dispatch shipping, and confirm the order"
  systemPrompt: |
    You are an order fulfillment agent for a retail commerce platform.
    Your job is to process incoming orders through a structured workflow:
    1. Validate the payment with the payment gateway
    2. Check inventory availability in the warehouse system
    3. Generate a shipping label and dispatch the order
    4. Send confirmation to the customer

    Always verify payment before checking inventory. If payment is
    flagged for review, pause and wait for human approval. Never
    dispatch an order without confirmed inventory.

  # ── LLM Configuration ──
  # The model and routing. If gatewayRef is set, the platform routes
  # through the LLM gateway (rate limiting, key rotation, fallback).
  # If provider is set instead, the agent calls the provider directly.
  llm:
    model: gpt-4o
    gatewayRef: llm-gateway-prod    # resolves to an llmGateways[] entry
    temperature: 0.1
    maxTokens: 4096

  # ── LLM Gateways ──
  # Gateway definitions that gatewayRef can point to.
  # The gateway handles API key rotation, rate limits, and failover.
  llmGateways:
    - name: llm-gateway-prod
      provider: openai
      endpoint: https://llm-gateway.internal/v1
      auth:
        secretRef: llm-gateway-api-key

  # ── Tools ──
  # Tools the agent can invoke. Two types:
  # - MCP tools: connect to an MCP server (serverRef must resolve)
  # - Function tools: call a registered function directly
  tools:
    - name: payment_verify
      description: "Verify payment status for an order"
      mcp:
        serverRef: payments-mcp      # must match an mcpServers[] entry
    - name: inventory_check
      description: "Check warehouse inventory for a product SKU"
      type: function
      function: check_inventory_api
    - name: shipping_create_label
      description: "Generate a shipping label for dispatch"
      mcp:
        serverRef: logistics-mcp

  # ── MCP Servers ──
  # MCP server definitions that tool serverRefs point to.
  mcpServers:
    - name: payments-mcp
      url: https://mcp.payments.internal/sse
      auth:
        type: bearer
        secretRef: payments-mcp-token
    - name: logistics-mcp
      url: https://mcp.logistics.internal/sse
      auth:
        type: bearer
        secretRef: logistics-mcp-token

  # ── Knowledge Bases ──
  # External knowledge sources this agent can query via RAG.
  # Each ref points to a separate KnowledgeBase resource.
  knowledgeBases:
    - ref: product-catalog-kb
      description: "Product catalog with SKUs, pricing, and availability"

  # ── State Schema ──
  # Typed fields that flow through the workflow. Reducers define
  # how parallel updates merge (critical for fan-out patterns).
  stateSchema:
    order_id:
      type: string
    payment_status:
      type: string
      default: "pending"
    inventory_result:
      type: object
      default: {}
    shipping_label:
      type: string
    error_log:
      type: array
      reducer: append          # concurrent errors get concatenated
    messages:
      type: message_list
      reducer: add_messages    # LangGraph message reducer

  # ── Checkpointer ──
  # Automatic state persistence. Every node completion saves a
  # checkpoint. Enables crash recovery, HITL, and time-travel debug.
  checkpointer:
    type: postgres
    config:
      pool_size: 5
      table_name: workflow_checkpoints
    secretRef: checkpoint-db-credentials

  # ── Security Configuration ──
  # Guardrails, egress controls, and compliance settings.
  # Required at Gold conformance profile.
  securityConfig:
    egress:
      allowlist:
        - "*.payments.internal"
        - "*.logistics.internal"
        - "llm-gateway.internal"
    guardrails:
      maxToolCallsPerTurn: 5
      requireHumanApproval:
        - payment_amounts_over: 10000
    telemetry:
      logs:
        redaction:
          enabled: false       # set to true for PII/PHI workloads

  # ── Operational Config ──
  # Timeouts, retries, and resource limits for production stability.
  operational:
    timeouts:
      perNode: 30s
      total: 300s
    retries:
      maxAttempts: 2
      backoff: exponential
    resources:
      cpu: "500m"
      memory: "512Mi"