API Reference

import { ArgideAgent, startAgentRuntime } from "@ourguide-ai/agent";

ArgideAgent is a facade that owns one runtime per page — it is what most integrations use. startAgentRuntime is the lower-level primitive it wraps.

ArgideAgent.init(options)

Initializes the page’s runtime. Idempotent and safe under React StrictMode — call it from anywhere, any number of times. On the server (SSR) it warns and does nothing; no session is minted until it runs in a browser.

Option	Type	Required	Description
`apiUrl`	`string`	Yes	Your Argide API host, e.g. `https://api.argide.ai`
`productId`	`string`	Yes	The product this page belongs to
`claim`	`({ sessionId, pairingCode }) => Promise<void>`	No	Called only when a session is freshly minted — never on recovery. Exchange the pair for a claim via your server. Omit to claim through your own channel.
`onStateChange`	`(state) => void`	No	Reports the facade lifecycle: `"starting" \| "ready" \| "error" \| "stopped"`

ArgideAgent.do({ goal })

Starts a task, or rejoins the running one.

Returns Promise<{ taskId: string }> — resolves as soon as the task exists, not when it finishes. Waits internally for init and the claim first.
Rejects with 409 SESSION_BUSY when called with a different goal while a task is running.
Called with the same goal as the running task, it resolves with the same taskId (rejoin).

ArgideAgent.check({ taskId })

Fetches the authoritative outcome.

Returns Promise<{ taskId, status, summary }>. status is one of running, completed, failed, or cancelled; summary is a string or null.
Rejects on any non-2xx, including 404 for a task that is unknown or belongs to another session.

ArgideAgent.cancel({ taskId })

Ends the task early.

The returned promise resolves with the same { taskId, status, summary } outcome shape as check().
Rejects on any non-2xx, including 404 (unknown or foreign task) and 409 (task already terminal).

ArgideAgent.onActivity(callback)

Subscribes to ephemeral, per-tab activity events. Returns an unsubscribe function.

const off = ArgideAgent.onActivity((activity) => {
  // { kind: "tool-start" | "tool-end" | "idle", ... }
});
// later, to unsubscribe: off()

Additional event fields vary by kind. Activity is not persisted — for the authoritative outcome use check().

ArgideAgent.session()

Returns Promise<{ sessionId, pairingCode, recovered }> for claiming through your own channel. Claim only when recovered is false — a recovered session is already claimed, and re-claiming returns 409 ALREADY_CLAIMED. See Claiming Sessions.

ArgideAgent.stop()

Tears down and resets the runtime. The next init() starts fresh. Normal pages never call this — the runtime is designed to live as long as the tab.

Local teardown only: it leaves a running task alive server-side. Use cancel() to end the task.

Errors

Error	Status	Surfaces from	What it means
`SESSION_BUSY`	409	`do()`	A task with a different goal is still running. Wait or `cancel()` first.
`ALREADY_CLAIMED`	409	the claim endpoint	The session was already claimed. Reserved as the stolen-pairing-code signal — do not retry.
Not found	404	`check()`, `cancel()`	Unknown `taskId`, or a task belonging to another session.
Conflict	409	`cancel()`	The task is already terminal.

These codes describe server-side behavior. On the client, do(), check(), and cancel() reject with a plain Error whose message carries the HTTP status (e.g. agent task create failed: HTTP 409) — the codes themselves aren’t exposed as properties on the error.

startAgentRuntime

ArgideAgent owns one runtime per page. Drop down to the primitive it wraps when you need more than one product on a page, or you want to manage the lifecycle yourself:

import { startAgentRuntime } from "@ourguide-ai/agent";

const argide = await startAgentRuntime({ apiUrl, productId });
// argide.{ sessionId, pairingCode, recovered, do, check, cancel, onActivity, stop }

At this level the claim-on-recovered rule and concurrent-start guarding are your responsibility: check recovered before claiming, and guard against starting two runtimes concurrently yourself.

Integration requirements

What your stack must support before going live

Get Started

Setup

Agent

Agent SDK

Knowledge Base

Integration

Monitor

ArgideAgent.init(options)

ArgideAgent.do({ goal })

ArgideAgent.check({ taskId })

ArgideAgent.cancel({ taskId })

ArgideAgent.onActivity(callback)

ArgideAgent.session()

ArgideAgent.stop()

Errors

startAgentRuntime

Integration requirements

​ArgideAgent.init(options)

​ArgideAgent.do({ goal })

​ArgideAgent.check({ taskId })

​ArgideAgent.cancel({ taskId })

​ArgideAgent.onActivity(callback)

​ArgideAgent.session()

​ArgideAgent.stop()

​Errors

​startAgentRuntime

Integration requirements

ArgideAgent.init(options)

ArgideAgent.do({ goal })

ArgideAgent.check({ taskId })

ArgideAgent.cancel({ taskId })

ArgideAgent.onActivity(callback)

ArgideAgent.session()

ArgideAgent.stop()

Errors

startAgentRuntime