> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argide.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run your first agent task in about 15 minutes

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](/agent-sdk/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**.

1. In the [dashboard](https://dashboard.argide.ai), go to **Settings → Agent API**.
2. Turn on **Enable the agent API**. Tasks are refused while it is off.
3. Under **API keys**, click **Create key**.
4. Copy the key immediately — it is shown once and cannot be retrieved again. If you lose it, revoke it and create another.

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

### 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](/agent-sdk/installation) covers that setup once; with it in place:

<CodeGroup>
  ```bash npm theme={null}
  npm install @ourguide-ai/agent
  ```

  ```bash pnpm theme={null}
  pnpm add @ourguide-ai/agent
  ```

  ```bash yarn theme={null}
  yarn add @ourguide-ai/agent
  ```
</CodeGroup>

## 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.

```ts theme={null}
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}`);
  },
});
```

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

## 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:

<CodeGroup>
  ```ts Next.js — app/api/argide/claim/route.ts theme={null}
  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" },
    });
  }
  ```
</CodeGroup>

Set the environment variables:

```bash .env.local theme={null}
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_...
```

<Warning>
  The `ak_live_...` key must never ship to the browser. Keep it in server-side environment variables only.
</Warning>

<Warning>
  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.
</Warning>

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](/agent-sdk/claiming-sessions) for the raw HTTP contract.

## 4. Run a task

```ts theme={null}
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)

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

## Next steps

<CardGroup cols={2}>
  <Card title="Claiming Sessions" icon="key" href="/agent-sdk/claiming-sessions">
    The security model behind the pairing-code exchange
  </Card>

  <Card title="Running Tasks" icon="play" href="/agent-sdk/running-tasks">
    Task lifecycle, busy sessions, and error handling
  </Card>

  <Card title="API Reference" icon="book" href="/agent-sdk/api-reference">
    Every method, option, and error code
  </Card>
</CardGroup>