For AI Agents

Overview

UCP is designed with agentic commerce in mind. AI agents can discover businesses, browse catalogs, make purchases, and track orders - all autonomously. This guide covers MCP tool integration, A2A protocol usage, and mandate handling.

MCP Tool Integration

The Model Context Protocol (MCP) allows LLMs to interact with UCP as native tools. Businesses expose their capabilities as MCP tools:

// MCP Tool Manifest (from business)
{
  "tools": [
    {
      "name": "ucp_search_products",
      "description": "Search for products in the catalog",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "category": { "type": "string" },
          "max_price": { "type": "number" }
        },
        "required": ["query"]
      }
    },
    {
      "name": "ucp_create_checkout",
      "description": "Create a checkout session with items",
      "input_schema": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "product_id": { "type": "string" },
                "quantity": { "type": "integer" }
              }
            }
          }
        },
        "required": ["items"]
      }
    }
  ]
}

Connecting to MCP Server

import { MCPClient } from '@modelcontextprotocol/sdk';

const client = new MCPClient();

// Connect to business MCP server
await client.connect('https://mcp.acme-store.com');

// List available tools
const tools = await client.listTools();

// Use a tool
const results = await client.callTool('ucp_search_products', {
  query: 'wireless headphones',
  max_price: 200
});

A2A Protocol Usage

The Agent-to-Agent (A2A) protocol enables complex multi-agent commerce scenarios. Multiple agents can coordinate to complete transactions.

// A2A Message Format
{
  "type": "a2a.commerce.request",
  "from": "agent:buyer-assistant-001",
  "to": "agent:store-agent-acme",
  "conversation_id": "conv_abc123",
  "payload": {
    "intent": "purchase",
    "items": [
      { "sku": "WH-PRO-001", "quantity": 1 }
    ],
    "constraints": {
      "max_total": 250.00,
      "delivery_by": "2025-01-20"
    },
    "mandate_ref": "mandate_xyz789"
  }
}

A2A Conversation Flow

1. Discovery - Agent discovers store's A2A endpoint
2. Intent - Agent sends purchase intent with constraints
3. Negotiation - Store agent confirms availability and pricing
4. Confirmation - Buyer agent confirms within mandate limits
5. Execution - Transaction is executed
6. Receipt - Both agents receive confirmation

AP2 Mandate Handling

AP2 Mandates provide cryptographic authorization for agents to make purchases within defined constraints. This enables truly autonomous commerce.

// Creating a mandate (user grants to agent)
{
  "mandate_id": "mandate_xyz789",
  "principal": "user:john@example.com",
  "agent": "agent:shopping-assistant",
  "constraints": {
    "max_single_purchase": 500.00,
    "max_daily_total": 1000.00,
    "allowed_categories": ["electronics", "home"],
    "excluded_merchants": [],
    "valid_until": "2025-06-30T23:59:59Z"
  },
  "signature": "base64-encoded-signature"
}

Using Mandates in Transactions

// Agent includes mandate in checkout
const checkout = await client.callTool('ucp_create_checkout', {
  items: [{ product_id: 'WH-PRO-001', quantity: 1 }],
  mandate: {
    mandate_id: 'mandate_xyz789',
    proof: generateMandateProof(mandate, transaction)
  }
});

// Business validates mandate
// - Signature is valid
// - Transaction within constraints
// - Mandate not revoked
// - Not expired

Autonomous Transaction Flow

// Complete autonomous purchase flow
async function autonomousPurchase(
  requirement: string,
  mandate: Mandate
) {
  // 1. Search for products
  const products = await mcp.callTool('ucp_search_products', {
    query: requirement
  });

  // 2. Select best match within budget
  const selected = selectBestProduct(products, mandate.constraints);

  // 3. Create checkout with mandate
  const session = await mcp.callTool('ucp_create_checkout', {
    items: [{ product_id: selected.id, quantity: 1 }],
    mandate: {
      mandate_id: mandate.id,
      proof: generateProof(mandate, selected.price)
    }
  });

  // 4. Complete purchase
  const order = await mcp.callTool('ucp_complete_checkout', {
    session_id: session.id
  });

  // 5. Track order
  return order;
}

Error Handling for Agents

Agents should handle UCP errors gracefully:

try {
  const result = await mcp.callTool('ucp_create_checkout', {...});
} catch (error) {
  switch (error.code) {
    case 'MANDATE_EXCEEDED':
      // Purchase exceeds mandate limits
      return { action: 'request_user_approval', reason: error.message };

    case 'PRODUCT_UNAVAILABLE':
      // Product out of stock
      return { action: 'find_alternative', original: error.details };

    case 'PRICE_CHANGED':
      // Price changed since search
      return { action: 'revalidate', new_price: error.details.new_price };

    default:
      return { action: 'escalate_to_user', error };
  }
}

Best Practices

• Always verify mandates - Check constraints before initiating purchases
• Log all transactions - Maintain audit trail for accountability
• Handle failures gracefully - Have fallback strategies for common errors
• Respect rate limits - Implement exponential backoff
• Confirm high-value purchases - Add human-in-the-loop for large transactions

Next Steps

• Learn about MCP Transport in detail
• Explore A2A Protocol for multi-agent scenarios
• Understand AP2 Mandates for authorization