OpenAI Adapter

The platform's first real external provider integration — @giggle-ai/openai-agent-adapter, implementing the generic ClinicalAgentProviderAdapter contract described in Model Provider Adapters against OpenAI's Responses API. It is a standalone package: the Runtime Control Engine never imports the openai SDK or any OpenAI-specific type.

Not a clinical quality claim

This adapter proves the platform can execute a real external model and still govern its output with an unmodified evidence/policy/risk pipeline. It does not mean OpenAI's output is clinically validated, accurate, or safe to act on without review — that governance is exactly what the Runtime Control Engine still provides. Synthetic data only; never send real patient data.

Environment variables

Variable	Required	Notes
OPENAI_API_KEY	Yes (for the adapter to be available)	Never logged, never returned by any API.
OPENAI_MODEL	Yes	Never hard-coded by the adapter — you choose the model.
OPENAI_BASE_URL	No	For an OpenAI-compatible endpoint (e.g. an enterprise gateway).
OPENAI_TIMEOUT_MS	No	Defaults to 30000.
OPENAI_MAX_OUTPUT_TOKENS	No	Defaults to 2048.

If OPENAI_API_KEY or OPENAI_MODEL is missing, the engine does not fail to start. The adapter is simply never registered (or reports misconfigured if validateAdapter is called), and the seeded openai-discharge-summary-agent stays in draft status — every other platform capability continues to work unaffected.

Setup

1. Set OPENAI_API_KEY and OPENAI_MODEL in the Runtime Control Engine's environment.
2. Start (or restart) the engine — the adapter is registered under adapter_id: "openai-responses-adapter" and validated automatically at boot.
3. Confirm it's usable:

curl ${CARC_RUNTIME_API_URL}/runtime/adapters/openai-responses-adapter

status should read "available". If it reads "misconfigured", re-check your environment variables and call POST /runtime/adapters/openai-responses-adapter/validate after fixing them (no restart required).

Managed execution example

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

const runtime = new RuntimeControlClient({ baseUrl: process.env.CARC_RUNTIME_API_URL! });

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

console.log(result.control_action, result.risk_level, result.review_required);

See examples/openai-clinical-agent in this repository for a complete, runnable walkthrough including the "unsupported medication recommendation" scenario.

Operational metadata

Every managed execution response includes safe, non-payload execution_metadata:

interface ManagedExecutionMetadata {
  provider_request_id: string | null;
  input_token_count: number | null;
  output_token_count: number | null;
  total_token_count: number | null;
  latency_ms: number | null;
  finish_reason: string | null;
}

Token counts and latency are operational integration metrics — see Runtime Metrics — never a clinical quality signal.

How grounding works

The adapter asks the model (via OpenAI's structured/JSON-schema output) to return an envelope shaped like the platform's own AgentOutput — a narrative plus explicit claims, each citing the source_ids that support it. The engine's AgentExecutionMapper maps that directly into a real AgentOutput so the unmodified Evidence Engine can assess exactly which claims are supported, partially supported, or unsupported — the same mechanism that already governs the synthetic reference agent and any externally submitted run. If the model's output doesn't parse as that structured shape (a possible outcome with any real model), the mapper falls back to treating the whole response as a single ungrounded claim, so a malformed response is still governed, never silently trusted.

Limitations

• v1 scope: discharge_summary task type only.
• Synchronous execution only — no streaming, no async/background responses.
• validateConfiguration() checks configuration presence/shape only by default; it does not make a live API call, so a valid key that has since been revoked will still report available until an actual execution (or a future live health-check option) surfaces the failure.
• Requires the openai npm package as a dependency of @giggle-ai/openai-agent-adapter only — never a dependency of the Runtime Control Engine's own package.
• Synthetic data only. Do not send real patient data to this adapter or any other provider adapter.