SDK Guide

@giggle-ai/runtime-sdk is a thin, fully typed TypeScript client. Every method is one request/response round trip against the engine's REST API — no policy, risk, or state-machine logic is duplicated client-side.

Installing

npm install @giggle-ai/runtime-sdk

Inside this monorepo, it's already a workspace package — build it (and its dependencies) with npm run build:packages.

Client configuration

import { RuntimeControlClient } from "@giggle-ai/runtime-sdk";

const runtime = new RuntimeControlClient({
  baseUrl: process.env.CARC_RUNTIME_API_URL!,
  apiKey: process.env.CARC_API_KEY, // optional — see Security
  tenantId: "tenant_acme_health", // optional — see Security
  timeoutMs: 30_000, // default; set 0 to disable
});

Field	Required	Notes
baseUrl	yes	No trailing slash required.
apiKey	no	Sent as Authorization: Bearer <apiKey>. Not enforced by the engine yet.
tenantId	no	Sent as X-Tenant-ID. Falls back to the engine's default tenant. Not a security boundary — see Security.
headers	no	Extra headers merged into every request.
timeoutMs	no	Aborts a request after this many ms.
fetch	no	Override the fetch implementation (mocking, polyfills).

Timeout configuration

Every request is wrapped in an AbortController timing out after timeoutMs (default 30000). A timeout surfaces as RuntimeNetworkError.

Correlation IDs

Every request automatically sends a generated X-Correlation-ID (or reuses whatever the engine echoes back). Read the most recent one via runtime.getLastCorrelationId(), or .correlationId on any thrown SDK error — include it when filing an issue about a specific request.

Error handling

Every failure is a subclass of RuntimeSdkError:

import { RuntimeConflictError, RuntimeNotFoundError } from "@giggle-ai/runtime-sdk";

try {
  await runtime.activateAgent("some-agent");
} catch (err) {
  if (err instanceof RuntimeConflictError) {
    console.log(`Cannot activate: ${err.message} (correlation: ${err.correlationId})`);
  } else if (err instanceof RuntimeNotFoundError) {
    console.log("Agent not registered.");
  } else {
    throw err;
  }
}

See Errors for the full hierarchy and retryable/non-retryable guidance.

Agent Registry methods

await runtime.registerAgent({ agentId, name, owner, version, clinicalDomain, allowedTasks, capabilities, modelProvider, modelVersion, riskTier });
await runtime.listAgents({ status: "active" });
await runtime.getAgent(agentId);
await runtime.updateAgent(agentId, { version: "1.1.0" });
await runtime.activateAgent(agentId);
await runtime.suspendAgent(agentId);
await runtime.deprecateAgent(agentId);

Session methods

await runtime.createSession({ caseId, agentId, taskType, userRole });
await runtime.listSessions({ state: "waiting_for_human_review" });
await runtime.getSession(sessionId);
await runtime.getSessionTimeline(sessionId);
await runtime.pauseSession(sessionId, { reason });
await runtime.resumeSession(sessionId);
await runtime.cancelSession(sessionId, { reason });
await runtime.approveSession(sessionId, { reviewerId, notes });
await runtime.rejectSession(sessionId, { reviewerId, notes });
await runtime.retrySession(sessionId, { reviewerId, notes });

Agent Run methods

await runtime.submitAgentRun({ agentId, caseId, taskType, agentOutput, sourceReferences, modelProvider, modelVersion, submittedBy });
await runtime.listAgentRuns({ agentId, executionOrigin: "external" });
await runtime.getAgentRun(runId);

Managed execution methods

Initiative 1 — the platform executes a registered agent through its configured provider adapter itself. See Model Provider Adapters for the full architecture and how this differs from submitAgentRun above.

const result = await runtime.executeRegisteredAgent("openai-discharge-summary-agent", {
  caseId: "case_demo_001",
  taskType: "discharge_summary",
  clinicalContext,
  sourceReferences,
  instructions: "Draft a discharge summary.",
});

Adapter methods

await runtime.listAdapters(); // secret-free RegisteredAdapterSummary[]
await runtime.getAdapter(adapterId);
await runtime.validateAdapter(adapterId); // re-checks configuration, returns updated status

Provider Connection methods

Initiative 2 — tenant-owned connections to external model providers. See Provider Connections for the full architecture. credential is write-only and never returned by any of these methods. Contains no model/execution configuration — see Execution Profile methods below for that.

const connection = await runtime.createProviderConnection({
  provider: "openai",
  displayName: "Acme Health — OpenAI Production",
  credential: process.env.ACME_OPENAI_API_KEY!,
});
await runtime.validateProviderConnection(connection.connection_id);

await runtime.listProviderConnections({ status: "valid" });
await runtime.getProviderConnection(connection.connection_id);
await runtime.updateProviderConnection(connection.connection_id, { displayName: "Renamed" });
await runtime.rotateProviderConnectionCredential(connection.connection_id, newApiKey);
await runtime.disableProviderConnection(connection.connection_id);
await runtime.enableProviderConnection(connection.connection_id);
await runtime.deleteProviderConnection(connection.connection_id);

Execution Profile methods

Initiative 3 — the canonical execution contract (model, inference parameters, timeouts/retries). See Execution Profiles for the full architecture and resolution order.

const profile = await runtime.createExecutionProfile({
  displayName: "GPT-5 Structured Clinical",
  provider: "openai",
  adapterId: "openai-responses-adapter",
  providerConnectionId: connection.connection_id,
  model: "gpt-5",
  temperature: 0.2,
  maxOutputTokens: 2048,
});
await runtime.activateExecutionProfile(profile.profile_id);

await runtime.listExecutionProfiles({ status: "active" });
await runtime.getExecutionProfile(profile.profile_id);
await runtime.updateExecutionProfile(profile.profile_id, { temperature: 0.1 });
await runtime.disableExecutionProfile(profile.profile_id);
await runtime.deleteExecutionProfile(profile.profile_id);

Set the resulting profile_id on an agent before calling executeRegisteredAgent:

await runtime.updateAgent(agentId, {
  executionProfileId: profile.profile_id,
});

Decision record methods

await runtime.getDecisionRecord(decisionId);
await runtime.listDecisionRecords(status);

Replay methods

await runtime.getDecisionReplay(decisionId); // single-run replay
await runtime.getSessionReplay(sessionId); // full multi-run "flight recorder"

Metrics methods

await runtime.getMetrics({ agent_id, task_type, from, to });

Policy methods

await runtime.listPolicies({ enabledOnly: true });
await runtime.getPolicy(policyId);

Health methods

await runtime.getHealth();
await runtime.getReadiness();
await runtime.getVersion();

Examples in the monorepo

• packages/runtime-sdk/examples/ — small, focused SDK usage scripts
• examples/quickstart-external-agent/ — the full Quickstart flow
• examples/reference-integrations/ — three distinct end-to-end scenarios (see Reference Integrations)