OpenAI

Archetype: AI (Actor) — returns AIAgentActor + AIActorDecision for governed engine.transition(...) submission.

What it does

@loop-engine/adapter-openai uses OpenAI chat completions with response_format: { type: "json_object" } to produce structured actor decisions. It returns an AIAgentActor and AIActorDecision for runtime submission where policy guards are enforced.

Quick setup

1. Install

   ⧉

   1npm install @loop-engine/adapter-openai openai

2. Create the actor

   ⧉

   1import { createOpenAIActorAdapter } from "@loop-engine/adapter-openai";
   2 
   3const adapter = createOpenAIActorAdapter({
   4  apiKey: process.env.OPENAI_API_KEY!,
   5  model: "gpt-4o"
   6});

3. Submit to a loop transition

   ⧉

   1"cmt">// @no-typecheck
   2const { actor, decision } = await adapter.createSubmission({
   3  loopId: "procurement",
   4  loopName: "SCM Procurement",
   5  currentState: "pending_analysis",
   6  availableSignals: [
   7    {
   8      signalId: "submit_recommendation",
   9      name: "Submit Recommendation",
   10      allowedActors: ["ai-agent"]
   11    }
   12  ],
   13  instruction: "Analyze demand data and recommend a purchase order.",
   14  evidence: { demandForecast: 0.89, currentStock: 42, reorderPoint: 50 }
   15});
   16 
   17await loopSystem.engine.transition({
   18  aggregateId: "procurement-1",
   19  transitionId: decision.transitionId,
   20  actor,
   21  evidence: decision
   22});

How it works

1. Builds a structured prompt from loop context
2. Calls OpenAI with JSON object response format
3. Parses response and validates signalId + confidence
4. Computes promptHash for auditability
5. Returns actor + decision for runtime enforcement

Configuration reference

| Option | Type | Default | Description | |---|---|---|---| | modelId | string | gpt-4o | OpenAI model ID (gpt-4o-mini, o1, o3-mini also supported) | | maxTokens | number | 1024 | Max tokens in response | | systemPrompt | string | — | Optional system prompt prepended to loop context | | confidenceThreshold | number | 0.7 | Minimum confidence required (0–1) |

Troubleshooting

• ActorDecisionError: INVALID_SIGNAL — Returned signalId is not in availableSignals.
• ActorDecisionError: INVALID_CONFIDENCE — Confidence outside 0–1; constrain via systemPrompt.
• ActorDecisionError: API_ERROR — Check OPENAI_API_KEY and model availability.

Related

• AI as Actor
• Confidence + Evidence
• Human Approval Gates
• Anthropic adapter, Grok adapter, Gemini adapter