# 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](https://developers.openai.com/api/docs/guides/agents/quickstart) for the upstream programming model.

## Before you begin {#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.

```ts
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 {#steps}

```sh
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 {#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 {#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 {#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 {#next-steps}

Continue with [Resources and effects](/docs/foundations/resources-effects.md), [Operate Runs](/docs/runs/operate.md), and [Credentials](/docs/credentials).