Mission SDK quickstart

This guide walks you through installing @praxa/sdk, configuring your connection to the Praxa Integration Gateway, and submitting your first governed AI agent mission — all without touching a provider API key. You’ll need Node.js 20 or later and a Praxa gateway URL and access token from your deployment administrator.

This quickstart uses a deployment-specific Integration Gateway and OAuth token. To call the personal-tenant api.praxa.io/v1 task API with a Platform key, follow Run and verify a durable task.

Install the SDK

Add @praxa/sdk to your project using your preferred package manager:

npm install @praxa/sdk

yarn add @praxa/sdk

pnpm add @praxa/sdk

Set environment variables

Export two environment variables before running your code. PRAXA_BASE_URL is the HTTPS origin of your Praxa Integration Gateway — the base URL of the deployment, not a specific path. PRAXA_ACCESS_TOKEN is a short-lived delegated OAuth token issued by your gateway; see the Authentication guide for how to obtain one.

export PRAXA_BASE_URL="https://api.your-praxa-gateway.example"
export PRAXA_ACCESS_TOKEN="<your-short-lived-oauth-token>"

PRAXA_BASE_URL must be an HTTPS origin. The SDK rejects HTTP origins and any URL containing embedded usernames or passwords.

Create your first mission

Create a file called mission.ts with the following code. It reads your environment variables, instantiates a PraxaClient, submits a mission with a goal specification and resource budget, and then streams the resulting mission events to the console.

mission.ts

import { PraxaClient } from "@praxa/sdk";

const baseUrl = process.env.PRAXA_BASE_URL;
const accessToken = process.env.PRAXA_ACCESS_TOKEN;

if (baseUrl === undefined || accessToken === undefined) {
  throw new Error("Set PRAXA_BASE_URL and PRAXA_ACCESS_TOKEN");
}

const praxa = new PraxaClient({
  baseUrl,
  accessToken: () => accessToken,
});

const mission = await praxa.createMission(
  {
    goalSpec: { task: "Prepare the weekly review" },
    resourceBudget: {
      maximumSteps: 12,
      maximumToolCalls: 8,
      maximumElapsedMs: 120_000,
      maximumParallelism: 2,
    },
  },
  crypto.randomUUID(),
);

console.log({ runId: mission.runId, status: mission.status });

for await (const event of praxa.missionEvents(mission.runId)) {
  console.log(event.id, event.event, event.data);
}

The second argument to createMission is your idempotency key — a stable 16–128 character key that prevents a retry from creating a duplicate mission. crypto.randomUUID() produces a valid value. Generate and persist one key before each new logical mission, then reuse that same value for every retry of that mission.The resourceBudget fields cap what the mission may consume:

Field	Value	Meaning
`maximumSteps`	`12`	At most 12 reasoning or action steps
`maximumToolCalls`	`8`	At most 8 tool invocations
`maximumElapsedMs`	`120000`	At most 2 minutes of wall-clock time
`maximumParallelism`	`2`	At most 2 concurrent sub-tasks

Run it

Execute your file directly with tsx (no compile step needed):

npx tsx mission.ts

node --import tsx mission.ts

You should see a runId and an initial status logged immediately, followed by a stream of structured events as the gateway executes your mission.

Your gateway URL must use HTTPS. The Praxa SDK rejects HTTP origins at client construction time. If you see an error about an invalid base URL, check that PRAXA_BASE_URL starts with https://.

Next step: Read the Authentication guide to understand how to obtain short-lived OAuth tokens and refresh them in production applications.

Get started

Core Concepts

Releases

Mission SDK quickstart