Quickstart TypeScript SDK

Start with AI Platform -> Setup if you want the quickest path to a verified SDK connection. The setup page gives you the current org ID, a copyable access token, API key creation, and generated snippets.

The @prompt-orchestra/sdk package exports PromptOrchestraClient with:

stable setup, agents, and runs runtime helpers
public beta stateless agent authoring and iteration methods under client.agents
public beta authoring clients for skills, tools, and evaluations

Install

npm install @prompt-orchestra/sdk

Construct the client

import { PromptOrchestraClient } from "@prompt-orchestra/sdk";

const client = new PromptOrchestraClient({
  baseUrl: process.env.PROMPT_ORCHESTRA_BASE_URL!,
  accessToken: process.env.PROMPT_ORCHESTRA_ACCESS_TOKEN!,
});

Optional: apiKey for routes that support api_key_or_access_token. Methods that require a user token (authMode: "access_token_only") will throw PromptOrchestraClientConfigError if only apiKey is set (core/auth.ts).

Verify setup (stable)

await client.setup.verify({
  organizationId: orgId,
});

Run and inspect an agent (stable)

const agentId = "<agent-id>";

const run = await client.agents.run(agentId, {
  organizationId: orgId,
  input: { message: "hello" },
});

const detail = await client.runs.get(run.runId, {
  organizationId: orgId,
});

Author a stateless agent (public beta)

const created = await client.agents.create({
  organizationId: orgId,
  name: "Routing Agent",
  description: "Stateless SDK quickstart agent",
  interactionType: "chat",
});

const version = await client.agents.createVersion(created.id, {
  organizationId: orgId,
});

const workflow = {
  organizationId: orgId,
  entryStepKey: "check_flag",
  steps: [
    {
      stepKey: "check_flag",
      name: "Check Flag",
      stepType: "condition_step",
      positionIndex: 0,
      config: { expression: "$input.flag" },
    },
    {
      stepKey: "return_true",
      name: "Return True",
      stepType: "return_step",
      positionIndex: 1,
      inputMapping: { result: "matched" },
    },
    {
      stepKey: "return_false",
      name: "Return False",
      stepType: "return_step",
      positionIndex: 2,
      inputMapping: { result: "unmatched" },
    },
  ],
  transitions: [
    {
      fromStepKey: "check_flag",
      toStepKey: "return_true",
      transitionType: "condition_true",
      sortOrder: 0,
    },
    {
      fromStepKey: "check_flag",
      toStepKey: "return_false",
      transitionType: "condition_false",
      sortOrder: 1,
    },
  ],
};

const validation = await client.agents.validateWorkflow(version.id, workflow);
if (!validation.summary.publishReady) {
  throw new Error("workflow not publish-ready");
}

await client.agents.saveWorkflow(version.id, workflow);
await client.agents.publish(created.id, {
  organizationId: orgId,
  versionId: version.id,
});

Run a skill (public beta)

const skill = await client.skills.list({ organizationId: orgId });
const run = await client.skills.run(skill[0].id, {
  organizationId: orgId,
  variables: { message: "hello" },
});

The SDK validates responses against route contracts defined in @prompt-orchestra/contracts.

Proof scripts

prompt-orchestra-ts/scripts/sdk-smoke.ts exercises the stable runtime loop: get -> run -> run detail -> replay -> rerun.
prompt-orchestra-ts/scripts/agent-authoring-e2e.ts exercises the public beta stateless authoring loop: create -> version -> validate/save workflow -> publish -> run -> inspect -> compare -> diff -> rollback.