Skip to content

ACP_INTEGRATION.md

Latest commit

 

History

History
512 lines (383 loc) · 12.3 KB

ACP_INTEGRATION.md

File metadata and controls

512 lines (383 loc) · 12.3 KB
Raw

ACP (Agentic Commerce Protocol) Integration

Overview

The Agentic Commerce Protocol (ACP) is an open standard that enables AI agents to interact with commerce platforms seamlessly. This integration allows your AI agents to:

  • Discover products through intelligent search
  • Manage shopping carts with add, update, and remove operations
  • Process checkouts with complete order flows
  • Handle payments through delegated payment providers
  • Track orders and provide shipping updates

Quick Start

1. Installation

The ACP integration is included in the @lov3kaizen/agentsea-core package:

pnpm add @lov3kaizen/agentsea-core

2. Basic Setup

import {
  ACPClient,
  createACPTools,
  Agent,
  AnthropicProvider,
  ToolRegistry,
  BufferMemory,
} from '@lov3kaizen/agentsea-core';

// Initialize ACP client
const acpClient = new ACPClient({
  baseUrl: 'https://api.yourcommerce.com/v1',
  apiKey: process.env.ACP_API_KEY,
  merchantId: process.env.ACP_MERCHANT_ID,
});

// Create commerce tools
const acpTools = createACPTools(acpClient);

// Setup agent with commerce capabilities
const agent = new Agent(
  {
    name: 'shopping-assistant',
    model: 'claude-opus-4-8',
    provider: 'anthropic',
    tools: acpTools,
    systemPrompt: 'You are a helpful shopping assistant...',
  },
  new AnthropicProvider(process.env.ANTHROPIC_API_KEY),
  toolRegistry,
  new BufferMemory(),
);

3. Execute Commerce Operations

const response = await agent.execute(
  'I need wireless headphones under $100',
  context,
);

Architecture

Components

┌─────────────────────────────────────────────────────────┐
│                      AI Agent                           │
│  (with ACP Tools registered)                            │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ uses
                     ▼
┌─────────────────────────────────────────────────────────┐
│                   ACP Tools                             │
│  • acp_search_products                                  │
│  • acp_create_cart                                      │
│  • acp_add_to_cart                                      │
│  • acp_create_checkout                                  │
│  • acp_complete_checkout                                │
│  • ... (14 total tools)                                 │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ calls
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  ACP Client                             │
│  (HTTP client for ACP-compliant APIs)                   │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ HTTP/REST
                     ▼
┌─────────────────────────────────────────────────────────┐
│           Commerce Platform API                         │
│  (ACP-compliant e-commerce backend)                     │
└─────────────────────────────────────────────────────────┘

Available Tools

Product Discovery

acp_search_products

Search for products with filters and sorting.

// Agent can use this tool when user asks:
// "Find me running shoes under $100"
{
  query: "running shoes",
  maxPrice: 100,
  sortBy: "popularity"
}

acp_get_product

Get detailed information about a specific product.

{
  productId: 'prod_abc123';
}

Cart Management

acp_create_cart

Create a new shopping cart.

// Returns: { id: "cart_xyz", items: [], totalAmount: { amount: 0, currency: "USD" } }

acp_add_to_cart

Add a product to the cart.

{
  cartId: "cart_xyz",
  productId: "prod_abc123",
  quantity: 2,
  price: { amount: 49.99, currency: "USD" }
}

acp_update_cart_item

Update item quantity in cart.

{
  cartId: "cart_xyz",
  productId: "prod_abc123",
  quantity: 3  // or 0 to remove
}

acp_get_cart

View current cart contents.

{
  cartId: 'cart_xyz';
}

Checkout

acp_create_checkout

Initiate checkout process.

{
  cartId: "cart_xyz",
  customer: {
    email: "customer@example.com",
    name: "John Doe"
  }
}

acp_update_shipping_address

Set shipping address for the order.

{
  sessionId: "checkout_abc",
  address: {
    line1: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "94102",
    country: "US"
  }
}

acp_update_payment_method

Configure payment method.

{
  sessionId: "checkout_abc",
  paymentMethod: {
    type: "delegated",
    delegatedProvider: "stripe",
    token: "tok_visa"
  }
}

acp_complete_checkout

Finalize the purchase.

{
  sessionId: 'checkout_abc';
}

Order Management

acp_get_order

Retrieve order details.

{
  orderId: 'order_123';
}

acp_cancel_order

Cancel an order (if not shipped).

{
  orderId: 'order_123';
}

acp_get_order_tracking

Get shipping tracking information.

{
  orderId: 'order_123';
}
// Returns: { trackingNumber: "1Z999AA...", carrier: "UPS", status: "in_transit" }

Payment Integration

Delegated Payment Flow

ACP supports delegated payment processing, allowing you to integrate with payment providers like Stripe, PayPal, etc., without handling sensitive payment data.

// 1. Create checkout session
const checkout = await agent.execute(
  'Start checkout with email: user@example.com',
  context,
);

// 2. Set up delegated payment
const payment = await acpClient.createDelegatedPayment(checkoutSessionId, {
  provider: 'stripe',
  merchantAccountId: 'acct_xxx',
  returnUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
});

// 3. User completes payment on provider's platform
// (Stripe, PayPal, etc.)

// 4. Confirm payment and complete order
await acpClient.confirmPayment(paymentIntentId, paymentToken);

Security Best Practices

  • ✅ Never store raw card numbers - Use payment tokens
  • ✅ Use delegated providers - Let Stripe/PayPal handle PCI compliance
  • ✅ Validate amounts - Always confirm prices before charging
  • ✅ Use HTTPS - All API calls are over secure connections
  • ✅ Tokenize sensitive data - Use one-time payment tokens

Examples

Example 1: Product Search and Add to Cart

const agent = new Agent(/* ... with ACP tools ... */);

// User: "I need a laptop for programming"
const response = await agent.execute(
  'I need a laptop for programming under $1500',
  context,
);

// Agent uses: acp_search_products
// Agent responds with product options

// User: "Add the MacBook to my cart"
const cartResponse = await agent.execute(
  'Add the MacBook Pro to my cart',
  context,
);

// Agent uses: acp_create_cart (if needed), then acp_add_to_cart

Example 2: Complete Purchase Flow

// 1. Search products
await agent.execute('Find wireless headphones', context);

// 2. Add to cart
await agent.execute('Add the Sony WH-1000XM5', context);

// 3. Start checkout
await agent.execute(
  'Checkout with email: john@example.com, ship to 123 Main St, SF, CA 94102',
  context,
);

// 4. Set payment
await agent.execute('Use my Stripe account for payment', context);

// 5. Complete order
await agent.execute('Complete my order', context);

// 6. Track order
await agent.execute('Where is my order?', context);

Example 3: Order Management

// Check order status
await agent.execute('What is the status of order #12345?', context);

// Track shipment
await agent.execute('Track my order', context);

// Cancel order
await agent.execute('Cancel order #12345', context);

Configuration

ACP Client Configuration

const acpClient = new ACPClient({
  // Required
  baseUrl: 'https://api.commerce.com/v1',

  // Optional authentication
  apiKey: 'your-api-key',
  merchantId: 'merchant-123',

  // Optional request configuration
  timeout: 30000, // 30 seconds
  headers: {
    'X-Custom-Header': 'value',
  },
});

Agent System Prompt Template

const systemPrompt = `You are a professional shopping assistant.

Capabilities:
- Product search and recommendations
- Shopping cart management
- Secure checkout processing
- Order tracking and support

Guidelines:
- Always confirm prices before adding to cart
- Ask for confirmation before completing purchases
- Provide clear shipping and payment information
- Handle errors gracefully with alternatives
- Be proactive about suggesting related products

When handling payments:
- Never ask for raw credit card numbers
- Use secure payment tokens only
- Confirm amounts before processing
- Provide clear transaction receipts`;

API Reference

Types

See packages/core/src/acp/types.ts for complete type definitions:

  • ACPProduct - Product information
  • ACPCart - Shopping cart
  • ACPCheckoutSession - Checkout session
  • ACPPaymentIntent - Payment intent
  • ACPOrder - Order details
  • ACPConfig - Client configuration

Client Methods

See packages/core/src/acp/client.ts for all available methods:

Product Discovery

  • searchProducts(query) - Search products
  • getProduct(productId) - Get product details
  • getProducts(productIds) - Batch get products

Cart Management

  • createCart() - Create cart
  • getCart(cartId) - Get cart
  • addToCart(cartId, item) - Add item
  • updateCartItem(cartId, productId, quantity) - Update quantity
  • removeFromCart(cartId, productId) - Remove item

Checkout

  • createCheckoutSession(cartId, customer?) - Start checkout
  • updateShippingAddress(sessionId, address) - Set shipping
  • updatePaymentMethod(sessionId, paymentMethod) - Set payment
  • completeCheckout(sessionId) - Complete purchase

Payments

  • createDelegatedPayment(sessionId, config) - Delegated payment
  • confirmPayment(intentId, token?) - Confirm payment

Orders

  • getOrder(orderId) - Get order
  • getCustomerOrders(customerId) - Get customer orders
  • cancelOrder(orderId) - Cancel order
  • getOrderTracking(orderId) - Track shipment

Resources

Troubleshooting

Common Issues

Issue: "Tool not found" error

// Solution: Ensure ACP tools are registered
const acpTools = createACPTools(acpClient);
toolRegistry.registerMany(acpTools);

Issue: API timeout errors

// Solution: Increase timeout in client config
const acpClient = new ACPClient({
  baseUrl: '...',
  timeout: 60000, // 60 seconds
});

Issue: Payment fails

// Solution: Verify payment token and provider config
// Ensure delegated payment configuration is correct
// Check merchant account credentials

Contributing

To extend ACP functionality:

  1. Add new types to packages/core/src/acp/types.ts
  2. Add client methods to packages/core/src/acp/client.ts
  3. Create tools in packages/core/src/acp/tools.ts
  4. Update examples and documentation

License

MIT - See LICENSE file for details