Quickstart

This walks through the exact flow implemented in examples/quickstart-external-agent in the monorepo — a small, standalone, runnable TypeScript app. Everything below is copy-paste executable.

1. Start the Runtime Control Engine

npm install
npm run build:packages
npm run dev:engine

In another terminal, set the engine origin and confirm it is up:

export CARC_RUNTIME_API_URL="<runtime-engine-origin>"
curl ${CARC_RUNTIME_API_URL}/health

2. Install or link the SDK

Inside this monorepo, the SDK is already built by build:packages. In your own project:

npm install @giggle-ai/runtime-sdk

3. Configure RuntimeControlClient

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

const runtime = new RuntimeControlClient({
  baseUrl: process.env.CARC_RUNTIME_API_URL!,
  tenantId: "tenant_acme_health", // optional — see Security
});

4. Register a clinical agent

let agent = await runtime.registerAgent({
  agentId: "acme-quickstart-agent",
  name: "Acme Quickstart Agent",
  owner: "acme-health-ai",
  version: "1.0.0",
  clinicalDomain: "inpatient_discharge",
  allowedTasks: ["discharge_summary"],
  capabilities: ["summarize", "recommend_medication"],
  modelProvider: "acme-ai",
  modelVersion: "quickstart-v1",
  riskTier: "high",
});

New agents register as draft by default.

5. Activate the agent

agent = await runtime.activateAgent("acme-quickstart-agent");

6. Submit an external Agent Run

const result = await runtime.submitAgentRun({
  agentId: "acme-quickstart-agent",
  caseId: "quickstart-case-1",
  taskType: "discharge_summary",
  modelProvider: "acme-ai",
  modelVersion: "quickstart-v1",
  submittedBy: "quickstart-integration",
  sourceReferences: [
    {
      source_id: "src-quickstart-1",
      source_type: "chart_note",
      title: "Discharge chart note",
      content: "Patient stable, ready for discharge.",
      authored_at: new Date().toISOString(),
    },
  ],
  agentOutput: {
    identity: {
      agent_id: "acme-quickstart-agent",
      agent_version: "1.0.0",
      model_provider: "acme-ai",
      model_version: "quickstart-v1",
      task_type: "discharge_summary",
    },
    generated_at: new Date().toISOString(),
    narrative: "Patient discharged in stable condition with a new anticoagulant prescription.",
    claims: [
      {
        claim_id: "claim-follow-up",
        claim_type: "instruction",
        statement: "Follow up with primary care within 7 days.",
        supporting_source_ids: ["src-quickstart-1"],
      },
    ],
    medication_recommendations: [
      {
        recommendation_id: "rec-anticoagulant",
        medication: "apixaban 5mg twice daily",
        instruction: "Take with food, morning and evening.",
        rationale: "VTE prophylaxis following inpatient admission.",
        supporting_source_ids: ["src-quickstart-1"],
      },
    ],
    discharge_instructions_present: true,
  },
});

7. Read the control action

console.log(result.control_action); // "require_human_review"
console.log(result.risk_level); // "medium"
console.log(result.policy_results); // medication_requires_review triggered

A medication recommendation always requires human review — this is deterministic, so this exact scenario reliably lands in waiting_for_human_review every time you run it.

8. Approve if human review is required

let session = result.session;
if (session.current_state === "waiting_for_human_review") {
  session = await runtime.approveSession(session.session_id, {
    reviewerId: "dr.quickstart",
    notes: "Reviewed medication recommendation, approved.",
  });
}

9. Retrieve the Decision Context Record

const record = await runtime.getDecisionRecord(session.decision_id);
console.log(record.status); // "finalized"

10. Retrieve Decision Replay

const replay = await runtime.getSessionReplay(session.session_id);
console.log(replay.replay_steps.length); // every event across every run, in order

Run it yourself

npm run quickstart

runs exactly this flow from examples/quickstart-external-agent/src/index.ts and prints session/run/decision IDs, the control action, risk score, policy/evidence results, and a final summary including the request's correlation ID.

Next

• Reference Integrations — three more worked examples with distinct outcomes
• Integration Patterns — synchronous, human-review, and asynchronous patterns
• Errors — what to expect when something goes wrong