v0.2 — Gemini, Claude, OpenAI

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 npm

agent.ts

import { ShoppingAgent, GeminiAdapter, MockMerchant } from '@agorio/sdk';

const merchant = new MockMerchant();
await merchant.start();

const agent = new ShoppingAgent({
  llm: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }),
});

const result = await agent.run(
  `Go to ${merchant.domain} and buy me wireless headphones`
);

console.log(result.answer);
console.log(result.checkout?.orderId);

await merchant.stop();

Why Agorio

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

Capability	Building from Scratch	With Agorio
UCP merchant discovery	Parse /.well-known/ucp yourself, handle both capability formats, normalize services	`client.discover("shop.example.com")`
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	`new MockMerchant() — full UCP server`
Agent orchestration	Implement plan-act-observe from scratch	`agent.run("buy me headphones")`

Works with any LLM

Three adapters ship out of the box. Implement the LlmAdapter interface to bring your own.

Google GeminiAvailable

GeminiAdapter

Anthropic ClaudeAvailable

ClaudeAdapter

OpenAI GPTAvailable

OpenAIAdapter

swap-adapters.ts

"token-comment">// Swap your LLM with a single line — zero code changes
const agent = new ShoppingAgent({
  llm: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }),
  "token-comment">// llm: new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
  "token-comment">// llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
});

12 Built-in Shopping Tools

Every tool the agent needs for the full UCP shopping workflow — from discovery to order tracking.

🔍

discover_merchant

Fetch and parse a UCP profile by domain

📋

list_capabilities

List what the merchant supports

🛒

browse_products

Paginated catalog with filtering

🔎

search_products

Keyword search across products

📦

get_product

Detailed product info with variants

➕

add_to_cart

Add products with quantity selection

🧾

view_cart

View cart contents and subtotal

❌

remove_from_cart

Remove items from cart

🚀

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

Quick Start

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

$npm install @agorio/sdk

my-agent.ts

import { ShoppingAgent, GeminiAdapter, MockMerchant } from '@agorio/sdk';

"token-comment">// 1. Start a mock merchant (UCP-compliant test server)
const merchant = new MockMerchant({ name: 'TechShop' });
await merchant.start();

"token-comment">// 2. Create an agent with your LLM of choice
const agent = new ShoppingAgent({
  llm: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }),
  verbose: true,
  onStep: (step) => {
    if (step.type === 'tool_call') {
      console.log(`Calling ${step.toolName}...`);
    }
  },
});

"token-comment">// 3. Give it a task
const result = await agent.run(
  `Go to ${merchant.domain} and buy me a mechanical keyboard.
   Ship to: Jane Doe, 123 Main St, San Francisco, CA 94102, US`
);

"token-comment">// 4. Inspect the result
console.log(result.success);            "token-comment">// true
console.log(result.answer);             "token-comment">// Natural language summary
console.log(result.checkout?.orderId);   "token-comment">// "ord_..."
console.log(result.checkout?.total);     "token-comment">// { amount: "95.98", currency: "USD" }

await merchant.stop();

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