v0.4 — Multi-Merchant · Shopify · Webhooks · Playground

Build AI commerce agents in 20 lines of code

The open-source TypeScript toolkit for building AI agents that discover merchants, browse products, and complete purchases — using the UCP and ACP open protocols.

$npm install @agorio/sdk

GitHub Try Playground npm

agent.ts

1import { ShoppingAgent, GeminiAdapter, MockMerchant,
2         WebhookServer } from '@agorio/sdk';
3
4const shop1 = new MockMerchant({ name: 'TechDirect' });
5const shop2 = new MockMerchant({ name: 'GadgetWorld' });
6await shop1.start();
7await shop2.start();
8
9const webhooks = new WebhookServer({
10  onOrderUpdate: (e) => console.log(`Order ${e.orderId}: ${e.newStatus}`),
11});
12await webhooks.start();
13
14const agent = new ShoppingAgent({
15  llm: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }),
16  webhookUrl: webhooks.callbackUrl,
17});
18
19const result = await agent.run(
20  `Compare headphone prices on ${shop1.domain} and ${shop2.domain},
21   buy the cheapest, and track shipping.`
22);
23
24console.log(result.checkout?.orderId);

tests passing

LLM adapters

shopping tools

protocols

Why Agorio

Stop rebuilding commerce plumbing. Focus on what makes your agent unique.

Capability	Building from Scratch	With Agorio
Merchant discovery	Parse /.well-known/ucp yourself, handle ACP endpoints separately, detect protocol	`Auto-detects UCP or ACP per merchant`
Product search	Build REST client, handle pagination, parse responses	`Built-in agent tool, automatic`
Cart & checkout flow	Manage sessions, shipping, payment state machine	`12 tools handle the full flow`
LLM integration	Write provider-specific function calling code	`Swap adapters: Gemini, Claude, OpenAI`
Testing	Stand up your own mock server, write fixtures	`MockMerchant (UCP) + MockAcpMerchant (ACP)`
Agent orchestration	Implement plan-act-observe from scratch	`agent.run("buy me headphones")`

Works with any LLM

Four adapters ship out of the box — all with streaming support. Use Ollama for fully local agents. Implement the LlmAdapter interface to bring your own.

Google Gemini

GeminiAdapterAvailable

Anthropic Claude

ClaudeAdapterAvailable

OpenAI GPT

OpenAIAdapterAvailable

Ollama (Local)

OllamaAdapterAvailable

swap-adapters.ts

1"token-comment">// Swap your LLM with a single line — zero code changes
2const agent = new ShoppingAgent({
3  llm: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }),
4  "token-comment">// llm: new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
5  "token-comment">// llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
6  "token-comment">// llm: new OllamaAdapter({ model: 'llama3.1' }), // fully local
7});
8
9"token-comment">// Stream results in real time
10for await (const event of agent.runStream("Buy headphones")) {
11  if (event.type === 'text_delta') process.stdout.write(event.text);
12}

New in v0.4

Multi-merchant price comparison, real Shopify connectivity, webhook order tracking, and a browser playground.

Multi-Merchant

Discover multiple merchants, compare prices across stores, and maintain isolated carts per merchant.

example.ts

1const result = await agent.run(
2  'Compare headphone prices on TechDirect and GadgetWorld'
3);
4"token-comment">// Agent discovers both, searches each, returns comparison
5"token-comment">// Each merchant gets its own cart, checkout, and order state

Shopify Adapter

Connect to real Shopify stores via the Storefront API. Auto-detected by domain, zero config.

example.ts

1import { ShoppingAgent, ShopifyAdapter } from '@agorio/sdk';
2
3const agent = new ShoppingAgent({
4  llm: adapter,
5  adapters: [new ShopifyAdapter({
6    storeDomain: 'my-store.myshopify.com',
7    storefrontToken: process.env.SHOPIFY_TOKEN,
8  })],
9});

Webhooks

Subscribe to order lifecycle events. Get notified when orders ship and deliver via HMAC-signed callbacks.

example.ts

1import { WebhookServer } from '@agorio/sdk';
2
3const webhooks = new WebhookServer({
4  secret: 'my-hmac-secret',
5  onOrderUpdate: (event) => {
6    console.log(event.orderId, event.newStatus);
7    "token-comment">// "ord_123" "shipped" | "delivered"
8  },
9});
10await webhooks.start();

Observability

Structured logging, OpenTelemetry-compatible tracing, and automatic usage metrics for every run.

example.ts

1const result = await agent.run('Buy headphones');
2console.log(result.usage?.totalTokens);    "token-comment">// 4521
3console.log(result.usage?.llmCalls);        "token-comment">// 6
4console.log(result.usage?.toolCalls);       "token-comment">// 8
5console.log(result.usage?.totalLatencyMs);  "token-comment">// 3200

Interactive Playground

See the agent in action — right in your browser

No API keys, no setup. Type any shopping task and watch the agent discover merchants, search products, compare prices, and complete checkout in real time.

Buy me wireless headphones and track shipping

Run

Waiting for task...

Cart

Empty

Order

No order yet

Stats

Steps

Tools

Open the Playground

No API keys required. Runs entirely in your browser.

17 Built-in Shopping Tools

Every tool the agent needs for the full shopping workflow — UCP and ACP, from discovery to order tracking. Need more? Add custom tools with plugins.

Discovery

discover_merchant

Auto-detect UCP or ACP merchant by domain

list_capabilities

List what the merchant supports

switch_merchant

Switch active context between discovered merchants

Shopping

browse_products

Paginated catalog with filtering

search_products

Keyword search across products

get_product

Detailed product info with variants

get_product_reviews

Customer reviews and average ratings

compare_prices

Compare prices across all discovered merchants

Cart

add_to_cart

Add products with quantity selection

view_cart

View cart contents and subtotal

remove_from_cart

Remove items from cart

apply_discount_code

Apply coupon or promo code at checkout

Checkout

initiate_checkout

Start checkout, get shipping options

submit_shipping

Submit shipping address

submit_payment

Complete payment, receive order

get_order_status

Check status of an existing order

subscribe_order_updates

Webhook notifications for shipping updates

Quick Start

From zero to a working shopping agent in under a minute.

$npm install @agorio/sdk

my-agent.ts

1import { ShoppingAgent, GeminiAdapter, MockMerchant } from '@agorio/sdk';
2
3"token-comment">// 1. Start a mock merchant (UCP-compliant test server)
4const merchant = new MockMerchant({ name: 'TechShop' });
5await merchant.start();
6
7"token-comment">// 2. Create an agent with your LLM of choice
8const agent = new ShoppingAgent({
9  llm: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }),
10  verbose: true,
11  onStep: (step) => {
12    if (step.type === 'tool_call') {
13      console.log(`Calling ${step.toolName}...`);
14    }
15  },
16});
17
18"token-comment">// 3. Give it a task
19const result = await agent.run(
20  `Go to ${merchant.domain} and buy me a mechanical keyboard.
21   Ship to: Jane Doe, 123 Main St, San Francisco, CA 94102, US`
22);
23
24"token-comment">// 4. Inspect the result
25console.log(result.success);            "token-comment">// true
26console.log(result.answer);             "token-comment">// Natural language summary
27console.log(result.checkout?.orderId);   "token-comment">// "ord_..."
28console.log(result.checkout?.total);     "token-comment">// { amount: "95.98", currency: "USD" }
29
30await merchant.stop();

See the full README for UcpClient usage, mock merchant config, and more.