API Reference

Primary entry points

Open Agent SDK exposes two primary usage styles:

1. prompt() for one-shot requests
2. createSession() / resumeSession() / forkSession() for stateful workflows

import { prompt, createSession, resumeSession, forkSession } from 'open-agent-sdk';

Prompt API

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

const out = await prompt('Summarize this repository.', {
  model: 'gpt-5.4',
  provider: 'codex',
  maxTurns: 8,
  permissionMode: 'default'
});

prompt() returns:

• result: string
• duration_ms: number
• usage: { input_tokens; output_tokens }
• session_id?: string
• structured_output?: unknown

Common PromptOptions fields:

• model: string (required)
• provider?: 'openai' | 'google' | 'anthropic' | 'codex' | 'openai-codex'
• apiKey?: string
• baseURL?: string
• codexOAuth?: CodexOAuthOptions
• maxTurns?: number
• allowedTools?: string[]
• permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'
• storage?: SessionStorage
• resume?: string
• forkSession?: boolean
• outputFormat?: OutputFormat

Session API

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

const session = await createSession({
  model: 'gpt-5.4',
  provider: 'codex',
  systemPrompt: 'You are a repository assistant.',
  maxTurns: 12,
});

await session.send('List important modules.');
for await (const event of session.stream()) {
  // handle assistant/tool/system events
}
await session.close();

Lifecycle methods:

• await session.send(message)
• for await (const event of session.stream()) { ... }
• session.getMessages()
• await session.close()

Resume and fork:

import { resumeSession, forkSession, FileStorage } from 'open-agent-sdk';

const storage = new FileStorage({ cwd: process.cwd() });
const resumed = await resumeSession('session-id', { storage });
const forked = await forkSession('session-id', { storage, model: 'gpt-5.4', provider: 'codex' });

Providers and authentication

Supported providers:

• Codex OAuth
• OpenAI
• Google Gemini
• Anthropic

Provider can be explicit (provider) or auto-detected from model naming conventions. For Codex OAuth, run codex login once and then use provider: 'codex'.

Base URL behavior

• Default auth uses provider-specific API keys
• You can set baseURL for proxies or compatible endpoints
• Anthropic-compatible endpoints may use different auth strategies automatically

Permissions

Permission modes:

• default
• acceptEdits
• bypassPermissions
• plan

bypassPermissions requires allowDangerouslySkipPermissions: true.

Custom permission callback:

import type { CanUseTool } from 'open-agent-sdk';

const canUseTool: CanUseTool = async (toolName, input) => {
  if (toolName === 'Bash') {
    return {
      behavior: 'deny',
      message: 'Bash is disabled in this runtime.',
      interrupt: false,
    };
  }

  return {
    behavior: 'allow',
    updatedInput: input,
  };
};

Attach with prompt({ canUseTool }) or createSession({ canUseTool }).

Type reference

Frequently used exported types:

import type {
  PromptOptions,
  PromptResult,
  Session,
  CreateSessionOptions,
  ResumeSessionOptions,
  ForkSessionOptions,
  PermissionMode,
  CanUseTool,
  OutputFormat,
  Tool,
  ToolDefinition,
  SDKMessage,
} from 'open-agent-sdk';

Built-in tool IO types include:

• ReadInput, ReadOutput
• WriteInput, WriteOutput
• EditInput, EditOutput
• BashInput, BashOutput
• WebSearchInput, WebSearchOutput
• WebFetchInput, WebFetchOutput

Session and storage types include:

• SessionStorage
• SessionData
• FileStorageOptions
• InMemoryStorage
• FileStorage

Hook-related types include:

• HookEvent
• HookInput
• HookCallback
• SessionStartHookInput
• PostToolUseHookInput
• PermissionRequestHookInput

Structured output:

import { Schema, type OutputFormat } from 'open-agent-sdk';

const outputFormat: OutputFormat = {
  name: 'summary',
  description: 'Structured summary',
  schema: Schema.object({
    title: Schema.string(),
    bullets: Schema.array(Schema.string()),
  }),
};