API & SDK

Learn how to connect a governed runtime, send the first action, and move from onboarding into SDK reference without losing context.

Buyer readinessConsoleReadiness

DocsAPI & SDK

API & SDK

Start here, get one action flowing, then continue into runtime families and SDK reference from the same documentation portal.

This page is the API & SDK branch inside the documentation architecture. Use it to connect a runtime, validate the first governed action, and then move deeper only when implementation detail is needed.

Golden path

Install the SDK, set three environment variables, run one real action, and confirm the evidence lands in the control plane.

Agents only need the public OSuite HTTP surface and a workspace API key. They should never need database credentials or operator-only secrets.

Champion scenario

Buyer-ready governed proof

Connect the runtime, submit one governed action, open replay, export proof, and verify the document fingerprint. This is the shortest path to a customer-visible OSuite outcome.

One-line installer

Install the OSuite CLI before choosing a deeper runtime path.

Install the OSuite CLI first, then let doctor show the missing workspace key, runtime identity, and signature posture.

curl installer

curl -fsSL https://studio.osuite.ai/install.sh | bash -s -- sdk

Choose your SDK

Use the Node.js path below. This page keeps the first-action flow short and only switches the parts that differ by language.

Selected SDK

Node.js

Install command:

Node.js install

npm install osuite

Use your real OSuite app URL as OSUITE_BASE_URL.

For local self-host, that is usually http://localhost:3000.

For hosted environments, use your public OSuite domain, not osuite.ai marketing pages.

What the agent needs

Base URL: https://studio.osuite.ai

Workspace API key

No direct database access

No runtime registration console required

Manage API keys View docs path

Decision model

Every integration should start with a simple mental model: decide what the agent is allowed to do, record the action, record what it assumed, and close the loop with an outcome.

What is the concrete action type you want to govern first?

What is the initial risk level for that action in your environment?

Which operator surface should light up when the action succeeds?

Does this action need synchronous human approval or just an audit trail?

Product surfaces

The first milestone is a real SDK-driven action loop: create the action, record assumptions, close the outcome, and make the evidence visible to operators.

Decisions

First place to verify that your action, assumptions, and outcome are landing live.

Replay

Action-by-action evidence surface for debugging what the agent attempted and why.

Pairings

Where verified agents become operator-approved identities rather than anonymous API callers.

Policies

Promotion path from simple logging to human-in-the-loop approval and harder controls.

Runtime adapter contract

OSuite does not optimize for one branded agent product. It expects every runtime adapter to preserve the same neutral control contract across identity, execution boundary, approval semantics, and replay evidence.

Identity and tenant scope

Every adapter must preserve stable tenant and agent identity across actions, approvals, and replay.

Execution boundary mapping

Adapters must declare where OSuite can truly intercept execution versus only observe or import evidence.

Runtime session projection

Adapters must preserve session start, session end, and per-tool event identity so a coding session becomes replayable beyond isolated actions.

Runtime family projection

Adapters should classify the runtime into a neutral family so documentation, policy, and reporting do not collapse into vendor names.

Adapter mode projection

Adapters must declare whether OSuite attaches inline, through a gateway, through a managed bridge, or as an observer.

Action envelope normalization

Adapters should normalize runtime events into one portable action envelope instead of platform-specific payloads.

Workload identity projection

Adapters should project runtime identity into standards-aligned OIDC or SPIFFE-compatible fields instead of relying only on vendor-specific labels.

Trace context projection

Adapters should preserve W3C Trace Context so governed actions stay joinable with incident, telemetry, and external audit pipelines.

Portable approval semantics

Approval must map to a consistent OSuite checkpoint whether the runtime uses native waits, interrupts, or external holds.

Governance layer split

External runtime governors such as Trust Boundary can enforce pre-execution controls, but OSuite remains the workspace, certificate, and proof authority.

Data governance projection

Adapters should preserve privacy, residency, retention, minimization, and cross-border handling metadata as first-class action attributes.

Protocol lane projection

Adapters should declare which protocol lane carried the action so OSuite can govern interoperability separately from transport.

Replay evidence closure

Adapters must emit enough trace, artifact, and outcome data for operators to reconstruct what happened.

Neutral runtime contract

The neutral runtime contract keeps OSuite broad. Runtime family describes what kind of agent system is being governed, and adapter mode describes where OSuite can actually attach to it.

Runtime families

OpenAI-compatible gateway

Runtimes that expose chat, response, or tool-call semantics through an OpenAI-shaped API boundary.

Managed agent platform

Hosted agent systems that own sessions, tool execution, and state progression inside a managed control surface.

Framework SDK runtime

Code-first runtimes where governance can attach directly to tools, graph nodes, handoffs, and outcomes.

Tool-hook runtime

Developer-facing runtimes that expose command, tool, or shell hooks before side effects occur.

Observer or import-only runtime

Systems where OSuite can import evidence or outcomes even when it cannot preempt execution inline.

Adapter modes

Inline SDK

strong

OSuite is embedded directly inside the runtime and can participate in guard, action open, approval, and outcome closure.

Lifecycle hook

strong

OSuite attaches through runtime lifecycle hooks before or after tool execution without embedding the SDK into the host runtime.

Session adapter

moderate

OSuite receives structured session, tool, and approval events from a local runtime adapter without modifying the runtime core.

Gateway

moderate

OSuite governs requests or tool calls at an API gateway or protocol boundary before the runtime continues.

Bridge

selective

A managed platform or external runtime forwards structured decisions and receipts through a translation layer.

Observer

weak

OSuite receives receipts, outcomes, or evidence after execution and cannot guarantee inline interception.

Authority split

Workspace authority

OSuite remains authoritative for tenant scope, approvals, billing, proof bundles, and replay exports.

Runtime authority

The runtime remains authoritative for actual execution, tool invocation, local state mutation, and native trace generation.

External governor authority

Trust Boundary or another external governor may add pre-execution policy enforcement, attestation, or sandbox controls.

Trust Boundary runtime

Trust Boundary is best used as the runtime governance layer for agent execution. OSuite should still own workspace scope, approvals, replay, and proof.

Trust Boundary runtime

Use Trust Boundary to enforce runtime policy and trust at the execution boundary, then map the resulting action into OSuite for tenant-aware approval, replay, and proof.

Trust Boundary handles runtime policy enforcement, zero-trust identity, sandboxing, and runtime receipts.

OSuite keeps the workspace boundary, approval semantics, replay closure, and PCAA certificate.

This split avoids double governance while still letting Foundry or other hosted runtimes use a serious execution layer.

Supported runtime shapes

Azure AI Foundry Agent ServiceOpenAI Agents SDK and code-first runtimesLangGraph / LangChain graphsDify and bridge-based hosted runtimes

Trust Boundary environment

export OSUITE_POLICY_EVALUATOR_TRUST_BOUNDARY_ENABLED="true"
export OSUITE_POLICY_EVALUATOR_TRUST_BOUNDARY_URL="https://trust-boundary.example.com/evaluate"
export TRUST_BOUNDARY_POLICY_REFERENCE="foundry/default"
export TRUST_BOUNDARY_FOUNDRY_PROFILE="customer-prod"

Latest AGT release signals

Contributor reputation checks can feed curated plugin and pack trust before runtime execution starts.

Policy composition with extends inheritance fits OSuite workspace, platform, and vertical governance packs.

Multi-stage policy pipelines align with pre_input, pre_tool, post_tool, and pre_output execution checkpoints.

Sentry integration can strengthen agent SRE signals and route runtime incidents into OSuite evidence, support, and readiness workflows.

OpenTelemetry-native observability and EU AI Act templates strengthen runtime receipts and enterprise assurance exports.

Rollout stages

Short term

Select agt_v1 as a policy evaluator and preserve Trust Boundary material inside the action envelope.

Medium term

Use Trust Boundary as the runtime bridge for Azure Foundry and other enterprise agent platforms.

Long term

Attach agent messaging, discovery, and signed trust materials without giving up OSuite certificate authority.

Trust Boundary docs

Plugin exchange

After the first connection works, the next layer is curated expansion: identity bridges, security packs, trust providers, and vertical packs can be enabled per workspace without replacing PCAA certificate authority.

Plugin exchange

Curated workspace-level enablement for identity bridges, security packs, trust providers, and regulated vertical packs.

AIM and AIP identity bridges for zero-trust agent identity.

GoPlus AgentGuard and MCP perimeter packs for runtime security.

Attestix and commerce trust adapters for verifiable trust materials.

Ond ESG and Microsoft governance packs for regulated reporting and enterprise posture.

Enablement model

Signed manifests

Workspace-level scopes

Audit trail for every enable or disable

Open Plugin Exchange Read docs

PCAA checkpoints

PCAA should show up as a portable execution sequence, not a runtime-specific abstraction. Any adapter path should make these checkpoints explicit.

Pre-action admissibility

Evaluate whether the proposed action is allowed, warned, blocked, or approval-gated before side effects happen.

SDK method: guard

Action open

Create the portable action record that becomes the trust object for replay, scoring, and proof.

SDK method: createAction

Assumption capture

Record what the runtime believed or depended on so operators can replay the reasoning boundary later.

SDK method: recordAssumption

Approval checkpoint

Pause, wait, or externally hold execution when policy requires a human checkpoint.

SDK method: waitForApproval

Outcome closure

Write the final result, evidence, and status so the action certificate closes cleanly.

SDK method: updateOutcome

Portable action envelope

action_typeRequired

Stable action taxonomy shared by operators, policy, replay, and scoring.

declared_goalRequired

Human-readable intent for the action before side effects happen.

risk_scoreOptional

Runtime-supplied risk hint before OSuite policy evaluation.

runtime_familyOptional

Neutral runtime family classification so governance stays portable across vendors.

adapter_modeOptional

How OSuite attaches to the runtime, such as inline SDK, lifecycle hooks, a session adapter, gateway, bridge, or observer.

execution_boundary_kindOptional

Where interception actually happens, such as inline tool call, managed bridge, or post-hoc observer.

governance_authorityOptional

Which layer shaped the decision boundary, such as OSuite, the runtime, or an external governor.

tool_nameOptional

Concrete tool or capability invoked by the runtime.

runtime_session_idOptional

Stable session identifier that groups many governed tool calls under one runtime session timeline.

tool_use_idOptional

Runtime-native tool call identifier used to reconcile hook events, approvals, and outcomes.

permission_request_idOptional

Runtime-native permission or approval request identifier when the host runtime emits one separately from the action.

tool_inputOptional

Sanitized input summary used for replay, policy, and audit.

assumptionsOptional

Beliefs or operating assumptions recorded around the action.

approval_stateOptional

Portable approval checkpoint state independent of runtime brand.

outcomeOptional

Final status, summary, and evidence closure for the action.

artifactsOptional

URLs, files, outputs, or references attached to the replay record.

trace_refOptional

Pointer to runtime trace, log, or execution timeline when available.

install_channelOptional

How the runtime adapter is distributed, such as project settings, user settings, local files, or plugin packaging.

settings_scopeOptional

The active runtime settings scope, such as project, local, user, or managed.

trusted_project_requiredOptional

Whether the runtime requires a trusted project/workspace before local hooks or config layers can load.

governance_engineOptional

Optional runtime governance layer that shaped execution before OSuite issued the final certificate.

runtime_identityOptional

Standards-aligned workload identity projection such as OIDC workload claims, SPIFFE IDs, or signed runtime identity references.

trace_contextOptional

W3C Trace Context projection so runtime actions can correlate with external traces and incident tooling.

external_trust_materialsOptional

Signed receipts, runtime trust materials, or external governance references preserved alongside the action.

trust_material_envelopeOptional

Normalized trust material envelope that classifies wallet, credential, delegation, registry, and signature evidence into one portable structure.

protocol_laneOptional

Declared interoperability lane used for this action, such as native, message-governed, A2A bridge, or signed-request transport.

governance_stage_receiptsOptional

Optional runtime stage receipts that preserve pre_input, pre_tool, post_tool, and pre_output enforcement results.

approval_receiptsOptional

Portable approval workflow receipts that preserve who approved, under which workflow, and with what evidence reference.

authorization_contextOptional

Structured permission boundary covering allowed systems, allowed actions, data domains, and escalation mode for the action.

workflow_contextOptional

Business workflow context that captures workflow identity, stage, connected systems, and business criticality.

evaluation_contextOptional

Evaluation and learning-loop posture for the action, including recommendation linkage and expected outcome review.

externality_contextOptional

Destination, account provenance, visibility, reversibility, and approval-enforceability facts that describe the action boundary beyond actor identity alone.

accountability_contextOptional

Named authority and accountability chain that records final authority, policy owner, runtime owner, and approver lineage.

data_minimization_declaredOptional

Whether the runtime declared a minimization posture before handling sensitive or regulated data.

tenant_idRequired

Workspace / tenant scope for policy, billing, compliance, and access control.

agent_idRequired

Stable runtime identity inside the tenant boundary.

Governance packs

These are the recommended operator-visible runtime surfaces to enable as your agent moves from first connection to governed execution.

Claude Code Hooks

Govern Bash, Edit, Write, and MultiEdit tool calls without SDK instrumentation.

Codex Hooks

Govern Codex Bash tool execution through repo-local hooks, project config, and runtime-session evidence.

Terminal Approval Channel

Approve or deny gated actions from the terminal while preserving replay evidence.

Verified Agents

Add signed actions, pairing, and stronger identity proof for governed runtimes.

Recommended rollout paths

Use Claude Connectors Directory for public distribution, and Claude Desktop Extension plus Codex Plugin for desktop-scale rollout and non-technical users. Repo-local hooks remain as advanced engineering lanes.

Primary packaged lanes

Claude Connectors Directory

Use when preparing the public remote MCP connector and OAuth flow for Claude Connectors Directory.

Claude Desktop Extension

Use when rolling out the OSuite MCP server and hardened defaults to Claude Desktop for non-technical users.

Codex Plugin

Use when distributing a Codex plugin with bundled hooks, MCP, and skills across the app, CLI, and IDE.

Advanced engineering lanes

Claude Code Hooks

Use when engineers need to manage Claude Code PreToolUse/PostToolUse hooks directly.

Codex Hooks

Use when engineers need direct control of repo-local .codex hooks and project config.

Platform pathways

Minimal governance

Start with guard + createAction + updateOutcome. This is enough for a trustworthy first connection.

Governance range: observe -> record

Recommended surfaces: Decisions + Replay

Code-first multi-agent runtime

Best fit when several agent workers share one workspace API key but still need distinct agent identities and replay visibility.

Governance range: record -> approve

Recommended surfaces: Agents + Decisions + Replay

Operator-approved execution

Add waitForApproval or verified pairings when the action can change production state.

Governance range: record -> approve

Recommended surfaces: Pairings + Approvals + Replay

Verified identity

Use pairing and signatures when you need to prove which agent instance authored an action.

Governance range: approve -> verify

Recommended surfaces: Pairings + Trust + Replay

Set environment variables

Set the minimum connection values in the agent runtime. The agent only talks to the OSuite HTTP API.

Node.js environment

export OSUITE_BASE_URL="https://studio.osuite.ai"
export OSUITE_API_KEY="<workspace-api-key>"
export OSUITE_AGENT_ID="my-agent"

For customer and agent runtimes, the minimum viable set is OSUITE_BASE_URL, OSUITE_API_KEY, and optionally OSUITE_AGENT_ID. Keep everything else operator-side.

Copy the minimal starter snippet

This is the smallest real example that creates a live action in OSuite.

Node.js starter

import { OSuite } from 'osuite';

const osuite = new OSuite({
  baseUrl: process.env.OSUITE_BASE_URL || 'https://studio.osuite.ai',
  apiKey: process.env.OSUITE_API_KEY,
  agentId: process.env.OSUITE_AGENT_ID || 'smoke-agent',
});

const decision = await osuite.guard({
  action_type: 'integration.smoke_test',
  declared_goal: 'Verify OSuite connection and dashboard visibility',
  risk_score: 5,
});

if (decision.decision === 'block') {
  throw new Error(`Blocked: ${decision.reasons.join(', ')}`);
}

const { action_id } = await osuite.createAction({
  action_type: 'integration.smoke_test',
  declared_goal: 'Verify OSuite connection and dashboard visibility',
  risk_score: 5,
  metadata: { environment: 'local', template: 'minimal-smoke' },
});

if (decision.decision === 'review') {
  await osuite.updateOutcome(action_id, {
    status: 'pending_approval',
    summary: 'Smoke test created and awaiting operator approval',
  });
  console.log('Smoke test pending approval:', action_id);
  process.exit(0);
}

await osuite.recordAssumption({
  action_id,
  assumption: 'OSuite base URL and API key are valid',
});

await osuite.updateOutcome(action_id, {
  status: 'completed',
  summary: 'Smoke test completed successfully',
});

console.log('Smoke test action:', action_id);

Prefer a guided approval first? With CLI 2.10.1+, run the fixed acknowledgement walkthrough. It does not execute a shell command or call an external tool. A workspace denial stays blocked.

CLI review walkthrough

osuite doctor
osuite try

Approve the exact request in Studio, then return to the terminal for its evidence link. Slack and email delivery require your workspace notification configuration.

Starter templates

The smoke-test snippet is only the first proof. Move to a real domain template as soon as the first governed action works.

Selected template

Minimal Smoke Test

Fastest way to prove the SDK, API key, and dashboard path are all wired correctly.

Best for: First live connection and CI smoke checks

Node.js template

import { OSuite } from 'osuite';

const osuite = new OSuite({
  baseUrl: process.env.OSUITE_BASE_URL || 'https://studio.osuite.ai',
  apiKey: process.env.OSUITE_API_KEY,
  agentId: process.env.OSUITE_AGENT_ID || 'smoke-agent',
});

const decision = await osuite.guard({
  action_type: 'integration.smoke_test',
  declared_goal: 'Verify OSuite connection and dashboard visibility',
  risk_score: 5,
});

if (decision.decision === 'block') {
  throw new Error(`Blocked: ${decision.reasons.join(', ')}`);
}

const { action_id } = await osuite.createAction({
  action_type: 'integration.smoke_test',
  declared_goal: 'Verify OSuite connection and dashboard visibility',
  risk_score: 5,
  metadata: { environment: 'local', template: 'minimal-smoke' },
});

if (decision.decision === 'review') {
  await osuite.updateOutcome(action_id, {
    status: 'pending_approval',
    summary: 'Smoke test created and awaiting operator approval',
  });
  console.log('Smoke test pending approval:', action_id);
  process.exit(0);
}

await osuite.recordAssumption({
  action_id,
  assumption: 'OSuite base URL and API key are valid',
});

await osuite.updateOutcome(action_id, {
  status: 'completed',
  summary: 'Smoke test completed successfully',
});

console.log('Smoke test action:', action_id);

Optional: enable verified agents

Basic mode works with an API key only. Verified mode adds signed actions and pairing, but it is not required for your first successful connection.

Node.js pairing

const { pairing, pairing_url } = await osuite.createPairingFromPrivateJwk(privateKeyJwk);
console.log('Approve this agent:', pairing_url);
await osuite.waitForPairing(pairing.id);

Inline runtime bootstrap

For code-first runtimes like OpenClaw, LangGraph, CrewAI, and OpenAI Agents SDK, generate a signed bootstrap package directly from the workbench instead of hand-rolling public-key setup.

Copy, run, confirm

Generate a package here and the agent will already be enrolled, signed, and visible in Agents before it sends the first governed action.

Validate the connection

Run the smoke template and verify that Decisions and Replay both light up.

Node.js validator

node smoke-test.mjs
open https://studio.osuite.ai/decisions

A clean validator run should result in a visible action in Decisions and a replay record you can inspect without touching the database.

Successful validation can feed proof back into /setup so the verification surface shows that a live SDK integration worked.

What success looks like

After the snippet and validator run cleanly, OSuite should start showing live evidence of the connection.

The action appears in /decisions with the expected action type and goal.

Replay shows assumptions and the final outcome.

The agent ID is stable across repeated runs.

Operators can describe what happened without reading raw agent logs.

Hosting model

Self-host and SaaS are deployment model choices for the control plane, and the deployment model does not determine governance level by itself.

Self-hosted control plane

Use your own URL, your own operator configuration, and keep the agent path identical.

Hosted shared cloud

Use the public OSuite workspace URL and keep the same SDK contract.

Optional: chain attestation

Each tenant org can configure its own default wallet for platform attestations.

When enabled, OSuite signs each action digest with the tenant wallet and anchors it asynchronously to the configured Solana network.

Self-hosted or air-gapped deployments can use offline queue mode so actions stay signed locally until a broadcaster is available.

Common mistakes

Using a marketing domain instead of your real OSuite app URL.

Giving the agent operator secrets or a database connection string.

Using a throwaway action type like "test" forever instead of a real domain action.

Skipping assumptions and outcome updates, which leaves replay records incomplete.

Treating verified pairing as mandatory for the very first successful connection.

Next steps

Open Studio Go to /setup Read full SDK docs Enable verified agents Review policies Dify guide

Runtime families

Choose the runtime shape, not the brand

Start from the runtime shape that matches how your agents run, then pick the closest implementation path once the capability model is clear.

API & SDK

Start here, get one action flowing, then continue into runtime families and SDK reference from the same documentation portal.

Choose your SDK

Set environment variables

Copy the minimal starter snippet

Minimal Smoke Test

Optional: enable verified agents

Validate the connection

What success looks like

Choose the runtime shape, not the brand

Embedded SDK runtime

Graph-orchestrated runtime

Tool-hook runtime

Workflow bridge runtime

Multi-agent task runtime

Managed enterprise runtime