diff --git a/packages/docs/astro.config.mjs b/packages/docs/astro.config.mjs index 391642a..1f27b23 100644 --- a/packages/docs/astro.config.mjs +++ b/packages/docs/astro.config.mjs @@ -18,7 +18,8 @@ export default defineConfig({ ], components: { ThemeSelect: './src/components/ThemeToggle.astro', - SiteTitle: './src/components/SiteTitle.astro' + SiteTitle: './src/components/SiteTitle.astro', + Footer: './src/components/Footer.astro' }, social: [ { diff --git a/packages/docs/src/components/Footer.astro b/packages/docs/src/components/Footer.astro new file mode 100644 index 0000000..16d6224 --- /dev/null +++ b/packages/docs/src/components/Footer.astro @@ -0,0 +1,125 @@ +--- +import EditLink from 'virtual:starlight/components/EditLink'; +import LastUpdated from 'virtual:starlight/components/LastUpdated'; +import Pagination from 'virtual:starlight/components/Pagination'; +import { logos } from 'virtual:starlight/user-images'; +import config from 'virtual:starlight/user-config'; +--- + + + + diff --git a/packages/docs/src/content/docs/api-reference/overview.mdx b/packages/docs/src/content/docs/api-reference/overview.mdx index 2a0187c..a1a73d5 100644 --- a/packages/docs/src/content/docs/api-reference/overview.mdx +++ b/packages/docs/src/content/docs/api-reference/overview.mdx @@ -1,56 +1,79 @@ --- title: API Reference -description: Complete reference for APIs, providers, permissions, and TypeScript types. +description: Complete reference for functions, lifecycle, and TypeScript exports in one page. --- -## Primary entry points - -Open Agent SDK exposes two primary usage styles: - -1. `prompt()` for one-shot requests -2. `createSession()` / `resumeSession()` / `forkSession()` for stateful workflows +Open Agent SDK exports one-shot and stateful APIs from the package root. ```ts -import { prompt, createSession, resumeSession, forkSession } from 'open-agent-sdk'; +import { + prompt, + createSession, + resumeSession, + forkSession, + type PromptOptions, + type Session, +} from 'open-agent-sdk'; ``` -## Prompt API +## In This Reference + +- [Core Functions](#core-functions) +- [Session Lifecycle](#session-lifecycle) +- [Types](#types) +- [Tool Input/Output Types](#tool-inputoutput-types) + +## Provider Notes + +- Supported providers: OpenAI, Google Gemini, Anthropic +- Provider can be explicit via `provider`, or inferred from model naming +- `baseURL` can be used for compatible/proxy endpoints +- API key can be set per call or resolved from env vars + +## Core Functions + +### prompt + +Single-call API for one-shot tasks. ```ts import { prompt } from 'open-agent-sdk'; -const out = await prompt('Summarize this repository.', { +const result = await prompt('Summarize this repository.', { model: 'gpt-5.3-codex', provider: 'openai', apiKey: process.env.OPENAI_API_KEY, maxTurns: 8, - permissionMode: 'default' + permissionMode: 'default', }); ``` -`prompt()` returns: +Signature: + +```ts +prompt(prompt: string, options: PromptOptions): Promise +``` + +Key `PromptOptions` fields: + +- `model` (required) +- `provider`, `apiKey`, `baseURL` +- `maxTurns`, `systemPrompt`, `allowedTools` +- `permissionMode`, `allowDangerouslySkipPermissions`, `canUseTool` +- `storage`, `resume`, `forkSession` +- `outputFormat`, `mcpServers`, `logLevel` + +Returns: - `result: string` - `duration_ms: number` -- `usage: { input_tokens; output_tokens }` +- `usage: { input_tokens: number; output_tokens: number }` - `session_id?: string` - `structured_output?: unknown` -Common `PromptOptions` fields: +### createSession -- `model: string` (required) -- `provider?: 'openai' | 'google' | 'anthropic'` -- `apiKey?: string` -- `baseURL?: string` -- `maxTurns?: number` -- `allowedTools?: string[]` -- `permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'` -- `storage?: SessionStorage` -- `resume?: string` -- `forkSession?: boolean` -- `outputFormat?: OutputFormat` - -## Session API +Creates a new stateful session for multi-turn workflows. ```ts import { createSession } from 'open-agent-sdk'; @@ -62,84 +85,122 @@ const session = await createSession({ 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(); +Signature: + +```ts +createSession(options: CreateSessionOptions): Promise ``` -Lifecycle methods: +Notes: + +- If `provider` is omitted, provider may be inferred from model naming. +- API key can be provided directly or resolved from env variables. +- Storage defaults to `FileStorage`, scoped by current working directory. -- `await session.send(message)` -- `for await (const event of session.stream()) { ... }` -- `session.getMessages()` -- `await session.close()` +### resumeSession -Resume and fork: +Resumes an existing session from storage. ```ts -import { resumeSession, forkSession, FileStorage } from 'open-agent-sdk'; +import { resumeSession, 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.3-codex' }); +const session = await resumeSession('session-id', { storage }); ``` -## Providers and authentication +Signature: -Supported providers: +```ts +resumeSession(sessionId: string, options?: ResumeSessionOptions): Promise +``` -- OpenAI -- Google Gemini -- Anthropic +Use when you need to continue a prior run with preserved conversation state. -Provider can be explicit (`provider`) or auto-detected from model naming conventions. +### forkSession -### Base URL behavior +Creates a new session by copying history from an existing session. -- 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 +```ts +import { forkSession, FileStorage } from 'open-agent-sdk'; -## Permissions +const storage = new FileStorage({ cwd: process.cwd() }); +const forked = await forkSession('session-id', { + storage, + model: 'gpt-5.3-codex', +}); +``` -Permission modes: +Signature: -- `default` -- `acceptEdits` -- `bypassPermissions` -- `plan` +```ts +forkSession(sessionId: string, options: ForkSessionOptions): Promise +``` + +Use when you want a branch experiment without mutating the original session. -`bypassPermissions` requires `allowDangerouslySkipPermissions: true`. +## Session Lifecycle -Custom permission callback: +The `Session` API is used for multi-turn and resumable workflows. + +### Typical Flow ```ts -import type { CanUseTool } from 'open-agent-sdk'; +import { createSession } from 'open-agent-sdk'; + +const session = await createSession({ + model: 'gpt-5.3-codex', + provider: 'openai', + apiKey: process.env.OPENAI_API_KEY, +}); -const canUseTool: CanUseTool = async (toolName, input) => { - if (toolName === 'Bash') { - return { - behavior: 'deny', - message: 'Bash is disabled in this runtime.', - interrupt: false, - }; +await session.send('List key modules in this repo.'); + +for await (const event of session.stream()) { + if (event.type === 'assistant') { + console.log(event.message); } +} - return { - behavior: 'allow', - updatedInput: input, - }; -}; +await session.close(); ``` -Attach with `prompt({ canUseTool })` or `createSession({ canUseTool })`. +### Core Methods + +- `await session.send(message: string)`: appends a user turn. +- `for await (const event of session.stream())`: consumes stream events. +- `session.getMessages()`: returns current session messages. +- `await session.close()`: closes session and releases resources. + +### Resume and Fork + +- `resumeSession(id, options)`: continue the same timeline. +- `forkSession(id, options)`: start a new timeline from copied history. + +Use `resume` when you need continuity, and `fork` when you need alternative branches. + +### Storage + +Session lifecycle depends on `SessionStorage`: + +- `InMemoryStorage`: process-local, ephemeral. +- `FileStorage`: persisted to disk, resumable across process restarts. -## Type reference +### Permission and Hooks During Session -Frequently used exported types: +Session execution still respects: + +- `permissionMode` and `canUseTool` +- hooks configuration for lifecycle and tool events + +If you pass overrides during `resumeSession()` or `forkSession()`, those overrides apply to the resumed/forked runtime behavior. + +## Types + +### Prompt and Session Types + +Common types: ```ts import type { @@ -149,52 +210,173 @@ import type { CreateSessionOptions, ResumeSessionOptions, ForkSessionOptions, +} from 'open-agent-sdk'; +``` + +These types define: + +- input options for one-shot and stateful execution +- result payload shape for `prompt()` +- session configuration for create/resume/fork flows + +### Permission Types + +```ts +import type { PermissionMode, + PermissionOptions, + PermissionResult, CanUseTool, - OutputFormat, +} from 'open-agent-sdk'; +``` + +`PermissionMode` union: + +- `default` +- `acceptEdits` +- `bypassPermissions` +- `plan` + +`CanUseTool` returns a typed allow/deny decision and can optionally update input/permission state. + +### Structured Output Types + +```ts +import { Schema, type OutputFormat } from 'open-agent-sdk'; + +const outputFormat: OutputFormat = { + type: 'json_schema', + name: 'summary', + description: 'Structured task summary', + schema: Schema.object( + { + title: Schema.string(), + bullets: Schema.array(Schema.string()), + }, + { required: ['title', 'bullets'] } + ), +}; +``` + +`OutputFormat` is currently based on JSON Schema object output. + +### Tool and Message Types + +```ts +import type { Tool, ToolDefinition, + ToolInput, + ToolOutput, SDKMessage, + SDKUserMessage, + SDKAssistantMessage, +} from 'open-agent-sdk'; +``` + +Use these exports to strongly type custom tool integrations and event pipelines. + +### Hook Types + +```ts +import type { + HookEvent, + HookInput, + HookCallback, + HooksConfig, + PreToolUseHookInput, + PostToolUseHookInput, + SessionStartHookInput, + SessionEndHookInput, } from 'open-agent-sdk'; ``` -Built-in tool IO types include: +Hook type exports cover lifecycle and tool-execution interception points. -- `ReadInput`, `ReadOutput` -- `WriteInput`, `WriteOutput` -- `EditInput`, `EditOutput` -- `BashInput`, `BashOutput` -- `WebSearchInput`, `WebSearchOutput` -- `WebFetchInput`, `WebFetchOutput` +### Storage and Provider Types -Session and storage types include: +```ts +import type { + SessionStorage, + SessionData, + ProviderConfig, + ChatOptions, + TokenUsage, +} from 'open-agent-sdk'; +``` -- `SessionStorage` -- `SessionData` -- `FileStorageOptions` -- `InMemoryStorage` -- `FileStorage` +Use these for custom persistence and provider-level integrations. -Hook-related types include: +## Tool Input/Output Types -- `HookEvent` -- `HookInput` -- `HookCallback` -- `SessionStartHookInput` -- `PostToolUseHookInput` -- `PermissionRequestHookInput` +Open Agent SDK exports typed input/output interfaces for built-in tools. -Structured output: +### File and Shell Tool Types ```ts -import { Schema, type OutputFormat } from 'open-agent-sdk'; +import type { + ReadInput, + ReadOutput, + WriteInput, + WriteOutput, + EditInput, + EditOutput, + BashInput, + BashOutput, + BashOutputInput, + BashOutputOutput, + KillBashInput, + KillBashOutput, +} from 'open-agent-sdk'; +``` -const outputFormat: OutputFormat = { - name: 'summary', - description: 'Structured summary', - schema: Schema.object({ - title: Schema.string(), - bullets: Schema.array(Schema.string()), - }), -}; +### Search and Web Tool Types + +```ts +import type { + GlobInput, + GlobOutput, + GrepInput, + GrepOutput, + GrepMatch, + WebSearchInput, + WebSearchOutput, + WebFetchInput, + WebFetchOutput, +} from 'open-agent-sdk'; +``` + +### Task Tool Types + +```ts +import type { + TaskListInput, + TaskListOutput, + TaskCreateInput, + TaskCreateOutput, + TaskGetInput, + TaskGetOutput, + TaskUpdateInput, + TaskUpdateOutput, + TaskInput, + TaskOutput, + TaskToolConfig, +} from 'open-agent-sdk'; ``` + +### Ask-User Tool Types + +```ts +import type { + AskUserQuestionInput, + AskUserQuestionOutput, + AskUserQuestionItem, + AskUserQuestionOption, +} from 'open-agent-sdk'; +``` + +### Why Use These Types + +- Keep app-level tool wrappers consistent with SDK contracts. +- Avoid duplicated local interfaces that drift from SDK updates. +- Improve autocomplete and compile-time validation for tool payloads. diff --git a/packages/docs/src/content/docs/index.mdx b/packages/docs/src/content/docs/index.mdx index 7446767..c3980ae 100644 --- a/packages/docs/src/content/docs/index.mdx +++ b/packages/docs/src/content/docs/index.mdx @@ -1,42 +1,54 @@ --- title: Open Agent SDK Documentation description: Open-source docs for Claude Agent SDK-style APIs, TypeScript integration, and multi-provider agent workflows. +tableOfContents: false --- -Open Agent SDK is an open-source TypeScript agent SDK implemented around Claude Agent SDK API patterns, with broader provider and extension options for production teams. +import { LinkCard, CardGrid, Steps } from '@astrojs/starlight/components'; -Use this documentation to move from install to production-ready workflows: +Open Agent SDK is an open-source TypeScript SDK for building production agent workflows with Claude Agent SDK-style APIs, plus multi-provider support and extension points for real systems. -- Learn the runtime model and API surface quickly -- Implement tools, sessions, permissions, and hooks with confidence -- Migrate Claude Agent SDK-style code with minimal friction +## What You Can Build -## Quick links +Use Open Agent SDK when you need: -- [Installation](/getting-started/installation/) -- [Quickstart](/getting-started/quickstart/) -- [Provider & Auth Strategy](/guides/provider-auth-strategy/) -- [Permissions & Safety](/guides/permissions-and-safety/) -- [API Reference](/api-reference/overview/) -- [Diff vs Claude Agent SDK](/migration/claude-agent-sdk-diff/) -- [Quick Migration Guide](/migration/quick-migration/) +- Stateful or one-shot agent workflows in TypeScript +- Built-in tools, permission controls, and session persistence +- Provider routing across OpenAI, Gemini, and Anthropic +- A migration-friendly path from Claude Agent SDK style integrations -## Why teams adopt Open Agent SDK +## Start Here -- **Open-source by default:** MIT-licensed core and transparent implementation -- **Claude-style API ergonomics:** Familiar mental model and aligned workflow patterns -- **Provider flexibility:** Integrate OpenAI, Gemini, and Anthropic without architecture rewrites -- **Production controls:** First-class tooling for sessions, permissions, hooks, and MCP + + + + + + -## Notes +## API Reference -- Engineering workflows and ADRs still live in repository root `docs/`. -- Current release line: `0.1.0-alpha.x`. + + + + + + + -## Suggested path +## Migration -1. [Install the SDK](/getting-started/installation/) -2. [Run Quickstart](/getting-started/quickstart/) -3. [Set provider/auth defaults](/guides/provider-auth-strategy/) -4. [Configure permissions and safety](/guides/permissions-and-safety/) -5. [Review migration details](/migration/quick-migration/) + + + + + +## Recommended Learning Path + + +1. Install and run [Quickstart](/getting-started/quickstart/). +2. Lock provider defaults in [Provider & Auth Strategy](/guides/provider-auth-strategy/). +3. Add guardrails with [Permissions & Safety](/guides/permissions-and-safety/). +4. Use [Core Functions](/api-reference/overview/#core-functions) and [Types](/api-reference/overview/#types) while integrating. +5. If you are migrating, finish with [Quick Migration Guide](/migration/quick-migration/). + diff --git a/packages/docs/src/styles/custom.css b/packages/docs/src/styles/custom.css index 02e323c..1845d2a 100644 --- a/packages/docs/src/styles/custom.css +++ b/packages/docs/src/styles/custom.css @@ -79,12 +79,21 @@ main .sl-markdown-content h1 { font-weight: 700; } -main .sl-markdown-content :is(pre, .expressive-code) { +main .sl-markdown-content pre { border: 1px solid var(--sl-color-hairline); border-radius: 10px; box-shadow: var(--sl-shadow-sm); } +main .sl-markdown-content .expressive-code { + border: 0; + box-shadow: none; +} + +main .sl-markdown-content .expressive-code .frame.is-terminal .header { + display: none; +} + .card, .sl-link-card { border-radius: 10px;