SDKs

Install from npm

npm install @intertrace-runtime/runtime
npm install @intertrace-runtime/tracing

Runtime protection

Wrap tools so authorize + execution permits run before the body. Mint an itr_rt_* key in Settings. The SDK talks to the Intertrace edge at https://intertrace.fly.dev. fromEnv() reads INTERTRACE_*. The first protected call starts a real session if you skip startSession().

import { IntertraceRuntime } from "@intertrace-runtime/runtime";

const runtime = IntertraceRuntime.fromEnv();
// Default baseUrl: "https://intertrace.fly.dev"
const { sessionId } = await runtime.startSession({ taskSummary: "Handle ticket" });

const sendEmail = runtime.protectTool(
  {
    name: "send_email",
    category: "external_communication",
    actionType: "write",
    dataBoundary: "external",
    possibleDataClasses: ["customer_pii"],
  },
  async (args: { to: string; body: string }) => {
    return { ok: true, to: args.to };
  }
);

await sendEmail({ to: "user@example.com", body: "Hello" });
await runtime.endSession(sessionId);

Agent builders

LLM plane: openaiCompatibleConfig() or baseURL=https://intertrace.fly.dev/v1. Tool plane: LangChain/LangGraph, OpenAI Agents, Vercel AI SDK 5, Mastra, CrewAI, LlamaIndex, AutoGen, Semantic Kernel, and Pydantic AI. Full cookbook: Agent frameworks.

import { openaiCompatibleConfig } from "@intertrace-runtime/runtime";

const edge = openaiCompatibleConfig({
  apiKey: process.env.INTERTRACE_RUNTIME_API_KEY!,
  assetId: "support-agent",
});
// new OpenAI(edge) · ChatOpenAI({ configuration: { baseURL: edge.baseURL } })

Errors

Catch typed errors. isIntertraceError(err) is the type guard. Blocked and approval-required decisions never run the tool body.

import {
  IntertraceBlockedActionError,
  IntertraceReviewRequiredError,
  isIntertraceError,
} from "@intertrace-runtime/runtime";

try {
  await sendEmail({ to: "user@example.com", body: "Hello" });
} catch (err) {
  if (err instanceof IntertraceReviewRequiredError) {
    // wait for approval, then retry with the approval id
  } else if (err instanceof IntertraceBlockedActionError) {
    // show err.message + err.policyReasons
  } else if (isIntertraceError(err) && err.retryable) {
    // transient edge error
  } else {
    throw err;
  }
}

Tracing

Films the session into Estate → Sessions. fromEnv() plus bindSession() share the runtime job. Patches Chat Completions, Responses, and Anthropic Messages. Nested trace() sets parent spans.

import { fromEnv, instrumentOpenAI } from "@intertrace-runtime/tracing";
import OpenAI from "openai";

const tracer = fromEnv();
tracer.bindSession(sessionId);

const openai = instrumentOpenAI(
  new OpenAI({
    apiKey: process.env.INTERTRACE_API_KEY,
    baseURL: "https://intertrace.fly.dev/v1",
  })
);

await tracer.trace("handle ticket", async () => {
  await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Summarize the ticket" }],
  });
});

OpenAI-compatible (no Intertrace SDK)

Point the official OpenAI client at the edge with a runtime key. Full pack: OpenAI SDK.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.INTERTRACE_RUNTIME_API_KEY,
  baseURL: "https://intertrace.fly.dev/v1",
});

Python

The Python SDK is not on PyPI. Install from the monorepo, or use the OpenAI SDK against https://intertrace.fly.dev/v1.

# From this repo
pip install -e packages/python-sdk

from intertrace import IntertraceRuntime

runtime = IntertraceRuntime.from_env()
session_id = runtime.start_session(task_summary="Handle ticket")
runtime.end_session(session_id)

Environment

• INTERTRACE_API_KEY / INTERTRACE_RUNTIME_API_KEY — itr_rt_* from Settings
• INTERTRACE_PROJECT_ID — workspace org UUID
• INTERTRACE_AGENT_ID / INTERTRACE_AGENT_PURPOSE
• Runtime / OpenAI edge: https://intertrace.fly.dev (/v1 for chat)

Interactive API: API reference · Machine spec: /openapi.json.