Skip to Content
Platform
Getting StartedQuickstart

Quickstart

Run your first task in a few minutes. JavaScript SDK is the primary example; select CLI for the equivalent shell flow.

This guide assumes you already have a runtime registered in your project. If you don’t, register one first (see Core Concepts). Everything below drives an existing runtime by name.

Starting from scratch? Build and run your agent as a recipe on your own machine first with the pi-recipes CLI (beta): npm i -g @introspection-ai/pi-recipes, then recipes create ./my-agent and pi --recipe my-agent. Publish it to git and register it as a runtime to deploy.

The runtime and task API is available in the JavaScript, Python, and Rust SDKs and the operator CLI. The examples below show JavaScript first and CLI second.

1. Authenticate

The SDK uses an environment-scoped API key. The CLI uses a browser-approved member login and remembers the selected project.

export INTROSPECTION_TOKEN="ik_..."

The SDK reads INTROSPECTION_TOKEN from the environment by default. Never embed a key in browser code. Client apps use a different SDK and a backend token broker.

2. Install

npm install @introspection-sdk/introspection-node

3. Run a task

Open a runner against a runtime by name, create a one-shot task, and stream its run. The run streams as typed AG-UI  events; iterate it to watch the agent work in real time.

import { IntrospectionClient } from "@introspection-sdk/introspection-node";
 
const client = new IntrospectionClient({
  token: process.env.INTROSPECTION_TOKEN,
});
 
// Open a runner against a named runtime, bound to an end-user identity.
const runner = await client.runtimes("support-agent").run({
  identity: { user_id: "user_123" },
});
 
// Start a task, returns a handle on its initial run.
const run = await runner.tasks.start({ prompt: "Summarize my open tickets" });
 
// Stream the run as typed AG-UI events.
for await (const ev of run.stream()) {
  console.log(ev);
}
 
// Tear down the runner and the client when you're done.
await runner.close();
await client.shutdown();

A few notes on the SDK shape:

  • client.runtimes("name").run(...) resolves the runtime and opens a runner bound to a sandbox. The project is taken from your API key server-side.
  • identity.user_id binds the runner to an end-user, so captured behavior is attributed correctly. Pass null if there is no end-user.
  • runner.tasks.start({ prompt }) starts a task and returns a handle whose stream() yields run events. The same handle exposes cancel() to stop a run mid-flight.

In the SDK tab, always call runner.close() and client.shutdown() when you finish. The runner holds a sandbox open; closing it frees those resources promptly. In the CLI tab, tasks follow returns when the run settles.

4. See what it captured

Once the run completes, the task’s record lives on in the platform:

  • The conversation is the immutable, replayable record of the task: every model call, tool call, and message. You can replay it turn by turn from the dashboard.
  • When the conversation completes, Introspection synthesizes observations & patterns: what it noticed about this run (user intent, task resolution, agent struggle, and more), clustered into recurring themes across many conversations.

This is the whole point of running on Introspection. You don’t just get an answer back, you get a structured, queryable record of what the agent actually did.

Next steps

  • Core Concepts: recipes, runtimes, tasks, conversations, judges, and experiments.
  • SDK & CLI: the JavaScript SDK, the browser SDK, and the introspection CLI in full.
  • API Reference: the REST surface behind the SDK.
Last updated on