Getting Started

Getting Started

This page takes you from an empty directory to a running AI commerce agent.

Prerequisites

  • Node.js 20+ (the SDK targets ES2022 and ships ESM).
  • An API key for at least one LLM provider. Agorio ships adapters for Gemini, Claude, OpenAI, and Ollama (local, no key required).

Install

npm install @agorio/sdk

The SDK has no runtime dependency on any specific LLM SDK at the top level — install the provider package you intend to use (for example @google/generative-ai for Gemini) alongside it if it isn’t already present.

Set your LLM key

Agorio’s LLM adapters read their key from the option you pass, which conventionally comes from an environment variable:

# Pick the provider you're using:
export GEMINI_API_KEY=...      # GeminiAdapter
export ANTHROPIC_API_KEY=...   # ClaudeAdapter
export OPENAI_API_KEY=...       # OpenAiAdapter
# Ollama runs locally and needs no key.

Run a mock merchant

You don’t need a real store to develop. The CLI starts a UCP-compliant mock merchant with a 10-product catalog:

npx agorio mock

By default this serves a UCP merchant on a local port. You can also start ACP- or MCP-only mock merchants — run npx agorio mock --help for the protocol flags. Programmatically, the same servers are exported as MockMerchant, MockAcpMerchant, and MockMcpMerchant.

Your first agent

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 }),
  verbose: true,
});
 
const result = await agent.run(`Go to ${merchant.domain} and buy me wireless headphones`);
console.log(result.answer);
console.log(result.checkout?.orderId);

Run it with tsx:

npx tsx my-agent.ts

The agent runs a plan-act-observe loop: it plans which tool to call, calls it, observes the result, and repeats until it can answer. With verbose: true you’ll see each tool call printed as it happens.

What’s next

IntroductionOverview