Quick Migration Guide

1. Install and baseline

npm install open-agent-sdk@alpha

Create a minimal parity test that runs your most common task end-to-end.

2. Map session workflow

• Replace your current session creation with createSession()
• Replace resume/fork semantics with resumeSession() / forkSession()
• Keep message streaming behavior under integration tests

3. Map permission behavior

• Start with permissionMode: 'default'
• Port custom allow/deny rules into canUseTool
• Only use bypassPermissions where you can guarantee runtime safety

4. Map providers

• Codex OAuth: run codex login, then set provider: 'codex'
• OpenAI: set provider: 'openai' and OPENAI_API_KEY
• Google: set provider: 'google' and GEMINI_API_KEY
• Anthropic: set provider: 'anthropic' and ANTHROPIC_API_KEY

If you used custom compatible endpoints, set baseURL explicitly.

5. Strongly type integration boundaries

Use exported types for options/results/tool IO instead of local ad-hoc interfaces.

6. Validate with targeted checks

Recommended smoke checks before full rollout:

• one prompt path
• one session resume path
• one fork path
• one sensitive tool permission denial path
• one structured output path

Minimal migration example

import { createSession } from 'open-agent-sdk';

const session = await createSession({
  model: 'gpt-5.4',
  provider: 'codex',
  permissionMode: 'default',
});

await session.send('Inspect repository and propose next steps.');
for await (const event of session.stream()) {
  // consume output
}