Configure your agent

An Agent SDK session reads configuration from settings files, environment variables, and the options object you pass when you start it. This page shows how to compose the options object and what settings files and environment variables control. For every option’s type and default, see the Options (TypeScript) and ClaudeAgentOptions (Python) references.

Pass options to a session

Every query() call accepts an options object: Options in TypeScript, ClaudeAgentOptions in Python. Each field is optional, and a session started with no options runs with the SDK’s defaults. The example below configures a read-only session that summarizes a project’s open TODOs. Pairs read as TypeScript / Python where the spellings differ:

model: picks the model
allowedTools / allowed_tools: pre-approves a read-only tool list
maxTurns / max_turns: caps the turn count
cwd: sets the working directory

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

for await (const message of query({
  prompt: "Summarize the open TODOs in this repo",
  options: {
    model: "claude-sonnet-5",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8,
    cwd: "/path/to/repo",
  },
})) {
  if (message.type === "result" && message.subtype === "success" && !message.is_error) {
    console.log(message.result);
  }
}

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
        cwd="/path/to/repo",
    )

    async for message in query(
        prompt="Summarize the open TODOs in this repo",
        options=options,
    ):
        if isinstance(message, ResultMessage) and not message.is_error:
            print(message.result)

asyncio.run(main())

Point cwd at one of your own projects and run the example. The summary of that project’s open TODOs prints when the result message arrives. allowedTools (TypeScript) or allowed_tools (Python) pre-approves the listed tools, so calls to them run without stopping for approval. Tools outside the list stay available. When Claude calls an unlisted tool, the permission mode decides whether the call runs. For more information, see Allow and deny rules.

Load settings files

Settings files supply configuration beyond the options object. Two options control how they load:

settingSources / setting_sources: controls which filesystem sources load: user, project, and local. Settings files and CLAUDE.md files arrive through these sources.
settings: loads a settings file path or an inline JSON string in either language, and TypeScript also accepts a settings object. Whichever form you pass overrides user, project, and local filesystem settings; only managed policy settings rank higher. The references document the full precedence order under Settings precedence for TypeScript and Settings precedence for Python.

Pass [] to disable user, project, and local settings. For more information, see Use Claude Code features in the SDK.

Choose a model

Unless the model option, your settings, or your environment selects a model, a new session starts on Claude Code’s default model. For the order of those sources, see Setting your model. Set model to pin a specific model, or to pick a smaller one for faster, cheaper agents. The value takes a model alias or a full model name; aliases and the versions they resolve to are listed under Model aliases. Set fallbackModel (TypeScript) or fallback_model (Python) to name a backup model. When the primary is overloaded or unavailable, the session switches to the backup. The primary is retried at the start of each user turn, so the session returns to it once the outage passes. In either language, the option accepts a single model or a comma-separated list of backups. For the order and the chain cap, see Fallback model chains. In TypeScript, a fallback equal to model throws an error at startup. The examples below show a fallback list in TypeScript and a single fallback in Python:

const options = {
  model: "claude-fable-5",
  fallbackModel: "claude-opus-5,claude-sonnet-5",
};

options = ClaudeAgentOptions(
    model="claude-fable-5",
    fallback_model="claude-opus-5",
)

The Messages API request parameters temperature, top_p, and max_tokens have no fields on the options object in either language. Set the effort level or a spend cap instead, or call the Messages API when you need those parameters directly.

Set environment variables

The env option sets environment variables for the Claude Code process that runs your session. Whether your values replace the inherited environment or merge over it differs by language:

TypeScript: env replaces the subprocess environment
Python: the SDK merges your values over the inherited environment, and your values override the inherited ones

In TypeScript, spread process.env into env to keep inherited variables such as PATH, HOME, and ANTHROPIC_API_KEY. When you leave env unset, the subprocess inherits your environment in both languages. The example routes API traffic through a gateway by setting ANTHROPIC_BASE_URL.

const options = {
  env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

options = ClaudeAgentOptions(
    env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

The variables you pass can also configure Claude Code itself. For the variables the Claude Code process reads, see Environment variables. To tune API timeouts and stall detection this way, follow the Handle slow or stalled API responses section in the TypeScript reference or the Python reference.

Set the working directory

Set cwd to run the session in a specific directory. When you leave cwd unset, the session runs in your process’s working directory. Neither SDK has a setter for cwd. To run in a different directory, start another session with that cwd. Claude Code reads the working directory to determine:

Project settings and hooks: which project’s settings and hooks load
Skills: where session skills are discovered
Session storage: which project a stored session belongs to

To let tools reach files outside the working directory, add paths with additionalDirectories (TypeScript) or add_dirs (Python). For the scope of that grant, see Additional directories grant file access, not configuration.

Limit turns and spend

Cap turns and spend with maxTurns / max_turns and maxBudgetUsd / max_budget_usd. Both caps are off when unset. When a session hits a cap, the run ends with a result message whose subtype names the cap, error_max_turns or error_max_budget_usd. What happens next differs by input mode:

Single-shot query(): the SDK yields the cap result and then raises, so wrap the loop in a try block to continue past the error
Streaming input: the session stays alive past a cap result, and the max-turns count starts over for each queued message. The budget total accumulates across messages, and once spend reaches the cap, later messages in the same conversation end with the same budget result. A /clear starts the budget over

The two caps treat 0 differently:

maxTurns / max_turns: 0 runs the session without a turn limit, the same as leaving the option unset
maxBudgetUsd / max_budget_usd: the CLI rejects 0 as an invalid amount at startup, and the session never runs

For more information about both caps, including subagent spend, see Turns and budget.

Change configuration mid-session

When you start a session with streaming input, you can switch its model and permission mode while it runs. Where you call the setters differs by language:

TypeScript: methods on the object query() returns
Python: methods on ClaudeSDKClient, since query() returns a plain iterator without control methods

Both languages have the same setters:

setModel() / set_model(): switches the model. Call it with no model to switch to Claude Code’s default model rather than the model you passed in options.
setPermissionMode() / set_permission_mode(): switches the permission mode

TypeScript also has applyFlagSettings() and updateSettings():

applyFlagSettings(): applies settings at runtime, as in await session.applyFlagSettings({ effortLevel: "high" }). The method takes settings file keys rather than options fields, so check the applyFlagSettings() reference for the schema and for which keys take effect mid-session.
updateSettings(): writes an allowlisted set of keys to the project’s local settings file, as in await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). The written keys take effect on the session’s next request and persist for later sessions that load local settings. The method’s row in the methods table names the allowlisted keys and the version floor.

The example below runs a two-turn session, changes the configuration between the turns, and prints the model that answered each turn. In TypeScript, the prompt stream holds the second message until the setters have run, and the second turn runs on the new model.

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

function userMessage(text: string): SDKUserMessage {
  return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
  startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
  yield userMessage("Reply with exactly: ready");
  await secondTurnReady;
  yield userMessage("Reply with exactly: done");
}

const session = query({
  prompt: turnPrompts(),
  options: {
    model: "claude-sonnet-5",
  },
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
  if (message.type === "assistant") {
    turnModel = message.message.model;
  } else if (message.type === "result") {
    completedTurns += 1;
    if (completedTurns === 1) {
      console.log(`First turn model: ${turnModel}`);
      await session.setModel("claude-opus-5");
      await session.setPermissionMode("acceptEdits");
      startSecondTurn();
    } else {
      console.log(`Second turn model: ${turnModel}`);
      break;
    }
  }
}

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
    options = ClaudeAgentOptions(model="claude-sonnet-5")

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Reply with exactly: ready")
        first_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                first_model = message.model

        await client.set_model("claude-opus-5")
        await client.set_permission_mode("acceptEdits")

        await client.query("Reply with exactly: done")
        second_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                second_model = message.model

    print(f"First turn model: {first_model}")
    print(f"Second turn model: {second_model}")

asyncio.run(main())

On the Claude API, the program prints First turn model: claude-sonnet-5, then Second turn model: claude-opus-5 after the switch.

Each model has its own prompt cache, so after a mid-session switch the next request recomputes the full conversation uncached at the new model’s rates. For more information, see Switching models.

Configure specific features

The table below maps each option to the feature it configures. For options this page doesn’t cover, see the TypeScript and Python references. If you know your goal but not which option serves it, start from Choose the right feature.

TypeScript	Python	Controls	Covered in
`permissionMode`	`permission_mode`	What the agent can do without approval	Configure permissions
`allowedTools`	`allowed_tools`	Which tool calls are pre-approved	Configure permissions
`canUseTool`	`can_use_tool`	Your approval callback for tool calls	Handle tool approval requests
`systemPrompt`	`system_prompt`	The agent’s instructions	Modifying system prompts
`settingSources`	`setting_sources`	Which filesystem settings load	Use Claude Code features in the SDK
`mcpServers`	`mcp_servers`	External tool servers	Connect to external tools with MCP
`agents`	`agents`	Subagent definitions	Subagents
`hooks`	`hooks`	Callbacks at lifecycle points	Hooks
`skills`	`skills`	Which skills load	Extend agents with skills
`plugins`	`plugins`	Which plugins load	Plugins
`outputFormat`	`output_format`	Structured output schemas	Structured outputs
`resume`	`resume`	Continuing a stored session	Sessions
`forkSession`	`fork_session`	Branching a session	Sessions
`sessionStore`	`session_store`	External session persistence	Session storage
`enableFileCheckpointing`	`enable_file_checkpointing`	Rewindable file edits	File checkpointing
`effort`	`effort`	How much work Claude puts into responses	Effort level
`sandbox`	`sandbox`	Sandbox behavior for tool execution	TypeScript and Python references, with deployment context in Secure deployment

Next steps

To see configuration composed into working agents:

Quickstart: build and run a first agent end to end
Examples: find a complete, runnable project or a guided Claude Cookbook recipe that matches what you want to build
Multi-tenant isolation: isolate each tenant’s settings and memory with settingSources / setting_sources, env, and cwd

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Pass options to a session

Load settings files

Choose a model

Set environment variables

Set the working directory

Limit turns and spend

Change configuration mid-session

Configure specific features

Next steps

​Pass options to a session

​Load settings files

​Choose a model

​Set environment variables

​Set the working directory

​Limit turns and spend

​Change configuration mid-session

​Configure specific features

​Next steps

Pass options to a session

Load settings files

Choose a model

Set environment variables

Set the working directory

Limit turns and spend

Change configuration mid-session

Configure specific features

Next steps