Deploy OpenAI Agents SDK projects

Deploy an existing OpenAI Agents SDK or OpenAI client project without changing its imports or agent loop.

Constal runs the JavaScript/TypeScript OpenAI Agents SDK as an upstream runtime. Your project continues importing Agent, Runner, run, tool, handoffs, guardrails, and streaming from @openai/agents; Constal does not translate the loop into another graph or require @constal/sdk imports. The current qualified line is @openai/agents 0.17.x. See the official OpenAI Agents SDK quickstart for the upstream programming model.

Before you begin

The SDK is an authoring library rather than a deployment manifest, so the project must already expose something callable:

Export an Agent as the default export for full Session and durable approval integration.
Export an existing request handler as the default export when the handler already calls run() itself.
Keep an existing conventional Node HTTP server and start script; Constal publishes it as a server Agent behind an ordinary Channel.

One-shot scripts that run a hard-coded prompt at module load have no request boundary. constal deploy reports that precisely instead of inventing an input protocol or executing the script during the build.

import { Agent, tool } from "@openai/agents";
import { z } from "zod";

const lookup = tool({
  name: "lookup_order",
  description: "Look up an order.",
  parameters: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => orders.get(orderId),
});

export default new Agent({
  name: "Support",
  instructions: "Resolve the request using the available tools.",
  model: "gpt-4.1",
  tools: [lookup],
});

Deploy

constal deploy . --wait

The build retains the exact lockfile-resolved SDK and application source. It emits one immutable Agent for the default export. A detected Node server additionally emits a Channel selecting its server Agent.

Runtime mapping

OpenAI SDK surface	Constal owner
upstream `Runner` and handoffs	installed SDK inside the Agent Worker
model calls	pinned Model Resources and the Run journal
`Session` history	customer-scoped framework storage owned by the Session coordinator
function tools	unchanged Tool code plus Constal code Policy and journaled external Resources
`needsApproval` and `interruptions`	durable wait plus serialized upstream `RunState`
stream events	durable Run protocol events
plain `openai` Responses or Chat calls	the same pinned Model Resource boundary
Credentials	non-secret environment sentinels; real material stays behind Drivers

If a Worker disappears after a paid model or Tool effect settles, the replacement receives the recorded settlement at the same SDK call identity. A human approval may remain open indefinitely without active Worker CPU; resolution restores the same serialized upstream run state.

Verify

After deployment, start a controlled Run and confirm its Agent detail reports framework.kind: openai-agents. Exercise at least one model call, Tool, stream, and approval used by the project. Inspect the Run journal to confirm each externally visible effect settled once.

Current boundary

The qualified slice covers exported Agents and handlers, upstream Sessions, function Tools, handoffs, streaming, and approval resume. Realtime, SandboxAgent, hosted computer use, and process-local stdio MCP require their separately qualified Driver or SandboxPool placements before they receive a compatibility pass. Build diagnostics name these surfaces; they are not silently downgraded.

Next steps

Continue with Resources and effects, Operate Runs, and Credentials.