or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

apis

agents.mdhooks.mdmcp.mdmessages.mdoptions.mdpermissions.mdquery-api.mdsandbox.mdtools.md
index.mdpatterns.mdquick-reference.mdtypes.md
tile.json

query-api.mddocs/apis/

Query API

Main API for creating agent queries. Includes both stable query API and experimental V2 session API.

Core Query Function

function query(_params: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

Creates an agent query returning an async generator of SDK messages.

Example:

import { query } from '@anthropic-ai/claude-agent-sdk';

const result = query({
  prompt: 'Find all TODO comments',
  options: {
    model: 'claude-sonnet-4-5-20250929',
    cwd: '/path/to/project',
    maxTurns: 10
  }
});

for await (const msg of result) {
  if (msg.type === 'result') {
    console.log(msg.subtype === 'success' ? msg.result : msg.errors);
  }
}

Query Interface

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
}

Control Methods

// Interrupt execution
await result.interrupt();

// Change permission mode (streaming input mode only)
await result.setPermissionMode('acceptEdits');

// Switch model (streaming input mode only)
await result.setModel('claude-opus-4-20250514');

// Limit thinking tokens
await result.setMaxThinkingTokens(1000);
await result.setMaxThinkingTokens(null); // Clear limit

Query Methods

// Get available slash commands
const commands = await result.supportedCommands();

// Get available models
const models = await result.supportedModels();

// Check MCP server status
const mcpServers = await result.mcpServerStatus();

// Get account info
const account = await result.accountInfo();

Streaming Input

For multi-turn conversations with programmatic control:

async function* userMessages(): AsyncGenerator<SDKUserMessage> {
  yield {
    type: 'user',
    message: {role: 'user', content: 'First question'},
    parent_tool_use_id: null,
    session_id: 'session-id'
  };

  await someCondition();

  yield {
    type: 'user',
    message: {role: 'user', content: 'Follow-up'},
    parent_tool_use_id: null,
    session_id: 'session-id'
  };
}

const result = query({
  prompt: userMessages(),
  options: {model: 'claude-sonnet-4-5-20250929'}
});

V2 Session API (Unstable)

Experimental persistent session interface for multi-turn conversations.

Create Session

function unstable_v2_createSession(_options: SDKSessionOptions): SDKSession;

Resume Session

function unstable_v2_resumeSession(_sessionId: string, _options: SDKSessionOptions): SDKSession;

One-shot Prompt

function unstable_v2_prompt(_message: string, _options: SDKSessionOptions): Promise<SDKResultMessage>;

SDKSession Interface

interface SDKSession {
  send(message: string | SDKUserMessage): Promise<void>;
  receive(): AsyncGenerator<SDKMessage, void>;
  close(): void;
  [Symbol.asyncDispose](): Promise<void>;
}

interface SDKSessionOptions {
  model: string;
  pathToClaudeCodeExecutable?: string;
  executable?: 'node' | 'bun' | 'deno';
  executableArgs?: string[];
}

Example:

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk';

const session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
});

await session.send('List TypeScript files');
for await (const msg of session.receive()) {
  if (msg.type === 'result') break;
}

await session.send('Analyze main.ts');
for await (const msg of session.receive()) {
  if (msg.type === 'result') break;
}

session.close();

// Or use async disposal
await using session2 = unstable_v2_createSession({model: '...'});
await session2.send('Task');
for await (const msg of session2.receive()) {
  if (msg.type === 'result') break;
}
// Auto-closed on scope exit

Resume Session

// Create and save session ID
const session1 = unstable_v2_createSession({model: '...'});
await session1.send('Remember: using React');
for await (const msg of session1.receive()) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    sessionId = msg.session_id;
  }
  if (msg.type === 'result') break;
}
session1.close();

// Resume later
const session2 = unstable_v2_resumeSession(sessionId, {model: '...'});
await session2.send('What framework do we use?');
// Agent remembers previous context

One-shot Usage

const result = await unstable_v2_prompt(
  'What files are here?',
  {model: 'claude-sonnet-4-5-20250929'}
);

if (result.subtype === 'success') {
  console.log(result.result);
}