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.
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.
Action envelope normalization
Adapters should normalize runtime events into one portable action envelope instead of platform-specific payloads.
Portable approval semantics
Approval must map to a consistent OSuite checkpoint whether the runtime uses native waits, interrupts, or external holds.
Replay evidence closure
Adapters must emit enough trace, artifact, and outcome data for operators to reconstruct what happened.
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.
tool_nameOptionalConcrete tool or capability invoked by the runtime.
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.
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.
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.
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://docs.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://docs.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://docs.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);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://docs.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.