TL;DR
Agorio v0.3 is the first commerce agent SDK that supports all three open protocols - UCP (Google/Shopify), ACP (OpenAI/Stripe), and MCP (JSON-RPC) - from a single codebase. Also shipping: 4 LLM adapters (including Ollama for offline agents), a plugin system, observability, and a CLI.
npm install @agorio/sdk
191 tests. MIT license. Star the repo if this is useful.
What Changed Since v0.1
A few weeks ago, we launched Agorio with UCP support and a single Gemini adapter. Here's where we are now:
| Feature | v0.1 | v0.3 |
|---|---|---|
| Protocols | UCP only | UCP + ACP + MCP (auto-detect) |
| LLM adapters | Gemini | Gemini, Claude, OpenAI, Ollama |
| Streaming | No |
runStream() async generator |
| Plugins | No | Custom tools via AgentPlugin
|
| Observability | No | Logging, tracing, metrics |
| CLI | No | npx agorio |
| Mock servers | 1 (UCP) | 3 (UCP, ACP, MCP) |
| Tests | 37 | 191 |
Let me walk through the highlights.
Triple-Protocol Auto-Detection
The agentic commerce space has three protocols now:
- UCP - Google AI Mode (75M+ daily users), Shopify merchants
- ACP - ChatGPT Instant Checkout (800M+ weekly users), Stripe merchants
- MCP - JSON-RPC 2.0 transport for tool-based interactions
Most SDKs force you to pick one. Agorio auto-detects:
import { ShoppingAgent, ClaudeAdapter } from '@agorio/sdk';
const agent = new ShoppingAgent({
llm: new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
acpOptions: {
endpoint: 'https://merchant.example.com',
apiKey: process.env.MERCHANT_API_KEY,
},
});
// Agent auto-detects UCP, ACP, or MCP - your code doesn't change
const result = await agent.run('Buy wireless headphones from shop.example.com');
console.log(result.checkout?.orderId);
When discover_merchant runs, Agorio tries UCP first (/.well-known/ucp), checks for MCP transport support, then falls back to ACP. All 12 built-in tools route through whichever protocol the merchant speaks.
Star on GitHub - it helps other developers find this.
Run Agents Offline with Ollama
No API keys? No problem. The new OllamaAdapter connects to a local Ollama instance:
import { ShoppingAgent, OllamaAdapter, MockMerchant } from '@agorio/sdk';
const merchant = new MockMerchant();
await merchant.start();
const agent = new ShoppingAgent({
llm: new OllamaAdapter({ model: 'llama3.1' }),
});
const result = await agent.run(
`Browse products at ${merchant.domain}`
);
await merchant.stop();
Fully offline. No API costs. Same LlmAdapter interface as the cloud adapters - swap one line to switch between local and cloud.
All four adapters support function calling and streaming:
new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }) // Google
new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }) // Anthropic
new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }) // OpenAI
new OllamaAdapter({ model: 'llama3.1' }) // Local
Plugin System: Add Custom Tools
The 12 built-in shopping tools cover discovery, search, cart, checkout, and order tracking. But what if you need something custom? Register a plugin:
const priceAlertPlugin: AgentPlugin = {
name: 'check_price_alert',
description: 'Check if a product price is below the user threshold',
parameters: {
type: 'object',
properties: {
product_name: { type: 'string' },
max_price: { type: 'number' },
},
required: ['product_name', 'max_price'],
},
handler: async ({ product_name, max_price }) => {
// Your custom logic here
return { alert: true, current_price: 29.99 };
},
};
const agent = new ShoppingAgent({
llm: new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
plugins: [priceAlertPlugin],
});
The LLM sees your custom tool alongside the built-in ones and can call it during the agent loop. Name conflicts with built-in tools throw at construction time.
Streaming: Watch the Agent Think
Use runStream() to get real-time events as the agent reasons and acts:
for await (const event of agent.runStream('Buy me headphones')) {
switch (event.type) {
case 'text_delta':
process.stdout.write(event.text);
break;
case 'tool_call':
console.log(`\nCalling ${event.toolName}...`);
break;
case 'tool_result':
console.log(`Got result from ${event.toolName}`);
break;
case 'done':
console.log('\nDone:', event.result.checkout?.orderId);
break;
}
}
Each adapter implements chatStream() using its provider's native streaming API. The agent yields events as the LLM thinks and acts.
Observability: Logging, Tracing, Metrics
Production agents need visibility. Agorio v0.3 ships three observability hooks:
const agent = new ShoppingAgent({
llm: new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
// Structured logging
onLog: (event: AgentLogEvent) => {
console.log(`[${event.level}] ${event.message}`, event.data);
},
// Distributed tracing
tracer: {
startSpan: (name, attributes) => {
const span = tracer.startSpan(name, { attributes });
return { end: () => span.end() };
},
},
});
// After a run, get usage metrics
const result = await agent.run('Buy headphones');
// result includes: promptTokens, completionTokens, llmCalls, toolCalls, latency
Plug in your existing OpenTelemetry setup, Datadog, or any logging backend. The interface is minimal - you bring your own implementation.
CLI: npx agorio
Explore UCP merchants and scaffold projects from the terminal:
# Discover a merchant's capabilities
npx agorio discover shop.example.com
# Start mock merchants for local development
npx agorio mock --port 3456
# Scaffold a new agent project
npx agorio init my-shopping-agent
No global install needed. The CLI ships with the SDK.
Get Started
npm install @agorio/sdk
- GitHub: github.com/Nolpak14/agorio
- npm: @agorio/sdk
- Website: agorio.dev
191 tests. 4 adapters. 3 protocols. Plugin system. CLI. MIT license.
The protocols are live, merchants are onboarding. Star the repo and come build with us.
Agorio is open source and not affiliated with Google, Shopify, OpenAI, or Stripe. UCP, ACP, and MCP are open standards maintained by their respective organizations.
Top comments (0)