API & SDK
API & SDK
Learn how to connect a governed runtime, send the first action, and move from onboarding into SDK reference without losing context.
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
OSuite should feel like a short, reliable setup 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.
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
What the agent needs
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
strongOSuite is embedded directly inside the runtime and can participate in guard, action open, approval, and outcome closure.
Lifecycle hook
strongOSuite attaches through runtime lifecycle hooks before or after tool execution without embedding the SDK into the host runtime.
Session adapter
moderateOSuite receives structured session, tool, and approval events from a local runtime adapter without modifying the runtime core.
Gateway
moderateOSuite governs requests or tool calls at an API gateway or protocol boundary before the runtime continues.
Bridge
selectiveA managed platform or external runtime forwards structured decisions and receipts through a translation layer.
Observer
weakOSuite 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.
Supported runtime shapes
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
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.
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.
Enablement model
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_typeRequiredStable action taxonomy shared by operators, policy, replay, and scoring.
declared_goalRequiredHuman-readable intent for the action before side effects happen.
risk_scoreOptionalRuntime-supplied risk hint before OSuite policy evaluation.
runtime_familyOptionalNeutral runtime family classification so governance stays portable across vendors.
adapter_modeOptionalHow OSuite attaches to the runtime, such as inline SDK, lifecycle hooks, a session adapter, gateway, bridge, or observer.
execution_boundary_kindOptionalWhere interception actually happens, such as inline tool call, managed bridge, or post-hoc observer.
governance_authorityOptionalWhich layer shaped the decision boundary, such as OSuite, the runtime, or an external governor.
tool_nameOptionalConcrete tool or capability invoked by the runtime.
runtime_session_idOptionalStable session identifier that groups many governed tool calls under one runtime session timeline.
tool_use_idOptionalRuntime-native tool call identifier used to reconcile hook events, approvals, and outcomes.
permission_request_idOptionalRuntime-native permission or approval request identifier when the host runtime emits one separately from the action.
tool_inputOptionalSanitized input summary used for replay, policy, and audit.
assumptionsOptionalBeliefs or operating assumptions recorded around the action.
approval_stateOptionalPortable approval checkpoint state independent of runtime brand.
outcomeOptionalFinal status, summary, and evidence closure for the action.
artifactsOptionalURLs, files, outputs, or references attached to the replay record.
trace_refOptionalPointer to runtime trace, log, or execution timeline when available.
install_channelOptionalHow the runtime adapter is distributed, such as project settings, user settings, local files, or plugin packaging.
settings_scopeOptionalThe active runtime settings scope, such as project, local, user, or managed.
trusted_project_requiredOptionalWhether the runtime requires a trusted project/workspace before local hooks or config layers can load.
governance_engineOptionalOptional runtime governance layer that shaped execution before OSuite issued the final certificate.
runtime_identityOptionalStandards-aligned workload identity projection such as OIDC workload claims, SPIFFE IDs, or signed runtime identity references.
trace_contextOptionalW3C Trace Context projection so runtime actions can correlate with external traces and incident tooling.
external_trust_materialsOptionalSigned receipts, runtime trust materials, or external governance references preserved alongside the action.
trust_material_envelopeOptionalNormalized trust material envelope that classifies wallet, credential, delegation, registry, and signature evidence into one portable structure.
protocol_laneOptionalDeclared interoperability lane used for this action, such as native, message-governed, A2A bridge, or signed-request transport.
governance_stage_receiptsOptionalOptional runtime stage receipts that preserve pre_input, pre_tool, post_tool, and pre_output enforcement results.
approval_receiptsOptionalPortable approval workflow receipts that preserve who approved, under which workflow, and with what evidence reference.
authorization_contextOptionalStructured permission boundary covering allowed systems, allowed actions, data domains, and escalation mode for the action.
workflow_contextOptionalBusiness workflow context that captures workflow identity, stage, connected systems, and business criticality.
evaluation_contextOptionalEvaluation and learning-loop posture for the action, including recommendation linkage and expected outcome review.
externality_contextOptionalDestination, account provenance, visibility, reversibility, and approval-enforceability facts that describe the action boundary beyond actor identity alone.
accountability_contextOptionalNamed authority and accountability chain that records final authority, policy owner, runtime owner, and approver lineage.
data_minimization_declaredOptionalWhether the runtime declared a minimization posture before handling sensitive or regulated data.
tenant_idRequiredWorkspace / tenant scope for policy, billing, compliance, and access control.
agent_idRequiredStable 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.
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);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
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.
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
Next steps
Runtime families
Choose the runtime shape, not the brand
OSuite should stay neutral. Start from the runtime shape that matches your control surface, then move into the nearest implementation path only after the capability model is clear.
Embedded SDK runtime
Best fit when you control the runtime code and can insert governance directly around actions, tools, and outcomes.
Graph-orchestrated runtime
Best fit when execution moves through explicit nodes, checkpoints, interrupts, or state transitions.
Tool-hook runtime
Best fit when the runtime exposes tool interception, pre-execution hooks, or command approval boundaries.
Workflow bridge runtime
Best fit when the runtime lives behind a hosted workflow, bridge layer, or external orchestration surface.
Multi-agent task runtime
Best fit when several cooperating workers share one governance envelope but still need distinct replay visibility.
Managed enterprise runtime
Best fit when the agent executes inside Azure AI Foundry or another managed platform and Trust Boundary sits at the runtime boundary.