ShoppingAgent

ShoppingAgent is the heart of Agorio. Given a natural-language goal, it runs a plan-act-observe loop: the LLM plans which tool to call, the agent calls it, observes the result, and repeats until it can answer.

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);

The 17 tools

The agent ships with 17 built-in shopping tools — discovering merchants, searching catalogs, inspecting products, managing a cart, creating and completing checkouts, tracking orders, and more. The LLM picks among them on each loop iteration. When you configure sub-agents, an 18th tool, invoke_sub_agent, is auto-registered.

run() vs runStream()

• run(goal) — runs to completion and returns a result with answer and an optional checkout.
• runStream(goal) — yields output incrementally so you can render tokens and tool calls as they happen.

Multi-merchant

Pass several adapters in merchants and the agent can compare and transact across all of them in a single run — for example finding the cheapest matching product across three stores.

The onComplete hook

AgentOptions accepts an onComplete hook that fires at every run exit point (success, error, or early termination). It’s the canonical place to flush observability — the Agorio Cloud helper uses it to ship the final trace batch.

Sessions and resume

Provide sessionStorage plus a sessionId and the agent snapshots its state every iteration and hydrates on construction when the sessionId matches stored state — letting a run resume across process restarts. See Session Storage.