Architecture

System Components

UCP defines four primary participant types, each with specific roles and responsibilities in the commerce ecosystem:

Businesses

Merchants who sell products or services. They implement UCP endpoints and declare their capabilities through a business profile. Businesses are the source of truth for inventory, pricing, and order fulfillment.

// Business responsibilities
- Publish business_profile.json at well-known URL
- Implement required capability endpoints
- Process payments through configured handlers
- Manage order lifecycle and fulfillment

Platforms

Aggregators that enable commerce on behalf of businesses (e.g., Shopify, WooCommerce). Platforms typically implement UCP as middleware, translating between their native APIs and the UCP standard.

// Platform responsibilities
- Provide UCP endpoints for hosted businesses
- Handle multi-tenant capability routing
- Manage authentication and rate limiting
- Aggregate business profiles for discovery

AI Agents

Autonomous software that acts on behalf of consumers. Agents discover businesses, negotiate purchases, and complete transactions without human intervention for each step.

// Agent responsibilities
- Discover and cache business profiles
- Validate capability compatibility
- Execute transactions within user mandates
- Handle errors and fallback scenarios

Consumers

End users who authorize agents and make purchasing decisions. Consumers grant permissions through OAuth 2.0 flows and set spending mandates.

Data Flow Architecture

UCP transactions follow a predictable flow across all transports:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Consumer  │     │   AI Agent  │     │  Business   │
└─────┬───────┘     └──────┬──────┘     └──────┬──────┘
      │                    │                   │
      │  1. Grant OAuth    │                   │
      │───────────────────>│                   │
      │                    │                   │
      │                    │  2. Discover      │
      │                    │──────────────────>│
      │                    │                   │
      │                    │  3. Fetch Profile │
      │                    │<──────────────────│
      │                    │                   │
      │                    │  4. Create Session│
      │                    │──────────────────>│
      │                    │                   │
      │                    │  5. Complete      │
      │                    │──────────────────>│
      │                    │                   │
      │  6. Confirmation   │                   │
      │<───────────────────│                   │
      │                    │                   │

Capability Architecture

Capabilities follow a consistent request/response pattern with standardized error handling:

Request Structure

{
  "capability": "dev.ucp.shopping.checkout",
  "action": "create_session",
  "version": "2026-01-11",
  "payload": {
    "cart": {
      "items": [...]
    },
    "currency": "USD"
  },
  "metadata": {
    "trace_id": "req_abc123",
    "agent_id": "agent_xyz789"
  }
}

Response Structure

{
  "success": true,
  "capability": "dev.ucp.shopping.checkout",
  "action": "create_session",
  "data": {
    "session_id": "sess_abc123",
    "status": "open",
    "cart": {...},
    "expires_at": "2025-01-15T12:00:00Z"
  },
  "metadata": {
    "trace_id": "req_abc123",
    "processing_time_ms": 142
  }
}

Error Structure

{
  "success": false,
  "capability": "dev.ucp.shopping.checkout",
  "action": "create_session",
  "error": {
    "code": "CART_VALIDATION_FAILED",
    "message": "Product DEMO-001 is out of stock",
    "details": {
      "product_id": "DEMO-001",
      "available_quantity": 0,
      "requested_quantity": 2
    }
  },
  "metadata": {
    "trace_id": "req_abc123"
  }
}

Extension Architecture

Extensions augment capabilities without modifying their core behavior. They follow an injection pattern:

// Checkout with Discount Extension
POST /checkout/sessions
{
  "cart": {
    "items": [...]
  },
  "extensions": {
    "dev.ucp.shopping.discount": {
      "promo_codes": ["SUMMER20"]
    }
  }
}

// Response includes extension data
{
  "session_id": "sess_abc123",
  "cart": {
    "subtotal": 100.00,
    "discount": 20.00,  // From discount extension
    "total": 80.00
  },
  "extensions": {
    "dev.ucp.shopping.discount": {
      "applied": [{
        "code": "SUMMER20",
        "type": "percentage",
        "value": 20
      }]
    }
  }
}

Transport Abstraction

The same capability operations work identically across all transports. The transport layer handles serialization, authentication, and delivery:

// REST Transport
POST https://api.example.com/v1/checkout/sessions
Authorization: Bearer token
Content-Type: application/json
{"cart": {...}}

// MCP Transport (Tool Call)
{
  "tool": "ucp_checkout_create_session",
  "arguments": {"cart": {...}}
}

// A2A Transport (Agent Protocol)
{
  "type": "ucp.request",
  "capability": "dev.ucp.shopping.checkout",
  "action": "create_session",
  "payload": {"cart": {...}}
}

Authentication Architecture

UCP uses OAuth 2.0 for consumer authentication with support for delegated authorization to agents:

Token Hierarchy

Consumer Token - Full user access, used for direct actions
Agent Token - Delegated access with scope limitations
Session Token - Short-lived, transaction-specific access

Scope Model

// Standard OAuth 2.0 scopes
ucp:checkout:read      // View checkout sessions
ucp:checkout:write     // Create and modify sessions
ucp:order:read         // View order history
ucp:order:write        // Modify orders (cancel, return)
ucp:profile:read       // Read user profile
ucp:mandate:execute    // Execute within mandate limits

Versioning Strategy

UCP uses date-based versioning (YYYY-MM-DD) to ensure backwards compatibility:

New versions are released monthly with additive changes only
Breaking changes require a new capability namespace
Deprecated features are supported for 12 months minimum
Version negotiation happens during capability discovery

// Version negotiation in request
{
  "capability": "dev.ucp.shopping.checkout",
  "preferred_versions": ["2026-01-11", "2025-06-01"],
  ...
}

// Response includes negotiated version
{
  "version": "2026-01-11",
  ...
}