Quickstart

Integrate @ourguide-ai/agent end to end: install the package, initialize it in the browser, add the server-side claim endpoint, and run your first task.

Before you start

You need:

Access to the package on GitHub Packages, and a token configured — see Installation.
A Product ID and an ak_live_... agent API key — see below.
A backend that can keep the API key secret and expose one new endpoint.

Get your agent API key

The agent API key is separate from the widget’s secret key, and it lives under Settings, not Deploy.

In the dashboard, go to Settings → Agent API.
Turn on Enable the agent API. Tasks are refused while it is off.
Under API keys, click Create key.
Copy the key immediately — it is shown once and cannot be retrieved again. If you lose it, revoke it and create another.

Only an organization admin can create or revoke agent API keys. If you are a member, the action fails.

Get your Product ID

Go to Settings → Products and copy the Product ID of the product you are integrating.

1. Install

The SDK is a restricted package on GitHub Packages, so it needs an access grant and a token before this works. Installation covers that setup once; with it in place:

npm install @ourguide-ai/agent

pnpm add @ourguide-ai/agent

yarn add @ourguide-ai/agent

2. Initialize in the browser

Call init once, wherever your page boots. It is idempotent and safe under React StrictMode — call it from anywhere, any number of times.

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

ArgideAgent.init({
  apiUrl: process.env.NEXT_PUBLIC_ARGIDE_AGENT_API_URL!,
  productId: process.env.NEXT_PUBLIC_ARGIDE_AGENT_PRODUCT_ID!,
  // Called only when a session is freshly minted — never on recovery.
  claim: async ({ sessionId, pairingCode }) => {
    const res = await fetch("/api/argide/claim", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ sessionId, pairingCode }),
    });
    if (!res.ok) throw new Error(`claim failed: HTTP ${res.status}`);
  },
});

On the server (SSR), init warns and does nothing. No session is minted until it runs in a real browser.

3. Add the claim endpoint on your server

The claim callback above posts the session’s { sessionId, pairingCode } pair to your backend. Your backend exchanges the pair for a claim using your ak_live_... key — until that happens, the session can’t run tasks. Create the endpoint the callback calls:

import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const apiUrl = process.env.NEXT_PUBLIC_ARGIDE_AGENT_API_URL;
  const apiKey = process.env.ARGIDE_AGENT_API_KEY;
  if (!apiUrl || !apiKey) {
    return NextResponse.json(
      { error: "Set NEXT_PUBLIC_ARGIDE_AGENT_API_URL and ARGIDE_AGENT_API_KEY" },
      { status: 500 },
    );
  }

  const { sessionId, pairingCode } = await req.json();
  if (
    typeof sessionId !== "string" || !sessionId ||
    typeof pairingCode !== "string" || !pairingCode
  ) {
    return NextResponse.json(
      { error: "sessionId and pairingCode are required strings" },
      { status: 400 },
    );
  }

  const res = await fetch(
    `${apiUrl}/api/agent/v1/sessions/claim`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${apiKey}`,
      },
      body: JSON.stringify({ sessionId, pairingCode }),
      cache: "no-store",
    },
  );
  return new NextResponse(await res.text(), {
    status: res.status,
    headers: { "Content-Type": "application/json" },
  });
}

Set the environment variables:

.env.local

NEXT_PUBLIC_ARGIDE_AGENT_API_URL=https://api.argide.ai
NEXT_PUBLIC_ARGIDE_AGENT_PRODUCT_ID=YOUR_PRODUCT_ID
ARGIDE_AGENT_API_KEY=ak_live_...

The ak_live_... key must never ship to the browser. Keep it in server-side environment variables only.

This route spends your API key. Gate it behind your own authenticated user session and rate-limit it — anyone who can load your page can obtain a pairing code and call it.

Any backend works — the endpoint just forwards the pair to POST {apiUrl}/api/agent/v1/sessions/claim with an Authorization: Bearer ak_live_... header. See Claiming Sessions for the raw HTTP contract.

4. Run a task

const { taskId } = await ArgideAgent.do({ goal: "cancel my subscription" });

const outcome = await ArgideAgent.check({ taskId });
// { taskId, status, summary }

status is one of running, completed, failed, or cancelled; summary is a string or null. do() resolves as soon as the task exists — not when it finishes — and waits internally for init and the claim to complete first, so you never have to check “is it ready”.

5. Watch it work (optional)

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

Next steps

Claiming Sessions

The security model behind the pairing-code exchange

Running Tasks

Task lifecycle, busy sessions, and error handling

API Reference

Every method, option, and error code

Get Started

Setup

Agent

Agent SDK

Knowledge Base

Integration

Monitor

Before you start

Get your agent API key

Get your Product ID

1. Install

2. Initialize in the browser

3. Add the claim endpoint on your server

4. Run a task

5. Watch it work (optional)

Next steps

Claiming Sessions

Running Tasks

API Reference

​Before you start

​Get your agent API key

​Get your Product ID

​1. Install

​2. Initialize in the browser

​3. Add the claim endpoint on your server

​4. Run a task

​5. Watch it work (optional)

​Next steps

Claiming Sessions

Running Tasks

API Reference

Before you start

Get your agent API key

Get your Product ID

1. Install

2. Initialize in the browser

3. Add the claim endpoint on your server

4. Run a task

5. Watch it work (optional)

Next steps