> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # SDK References
## Functions
### `query()` The SDK's main entry function. Creates an async iterator that streams messages in arrival order. ```python theme={null} async def query( *, prompt: str | AsyncIterable[dict[str, Any]], options: QoderAgentOptions | None = None, ) -> AsyncIterator[Message]: ... ```
#### Parameters | Parameter | Type | Description | | :-------- | :---------------------------------------- | :------------------------------------------------------------------- | | `prompt` | `str \| AsyncIterable[dict[str, Any]]` | Pass a string for single-turn; pass an async iterable for multi-turn | | `options` | [`QoderAgentOptions`](#qoderagentoptions) | Optional session configuration |
#### Return Value Returns `AsyncIterator[Message]`, consumed via `async for`.
### `QoderSDKClient` Class-based multi-turn conversation API. Suitable for scenarios that need to keep session state across turns or dynamically switch the model or permission mode. ```python theme={null} client = QoderSDKClient(options=options) await client.connect("Initial prompt.") ``` | Method | Description | | :----------------------------------------------- | :------------------------------------------------------------------------ | | `client.query(prompt)` | Send a new round of user input | | `client.receive_response()` | Consume messages until `ResultMessage` | | `client.receive_messages()` | Background async iterator that receives the entire session message stream | | `client.connect(prompt)` / `client.disconnect()` | Manually manage the connection | | `client.interrupt()` | Interrupt the current generation or tool execution | | `client.set_model(model)` | Switch the model at runtime | | `client.set_permission_mode(mode)` | Switch the permission mode at runtime | | `client.stop_task(task_id)` | Stop a background task | | `client.apply_flag_settings(settings)` | Inject flag-level settings | | `client.supported_agents()` | List the agents currently available | | `client.get_mcp_status()` | Get the status of all MCP servers | | `client.set_mcp_servers(servers)` | Replace the MCP server configuration | | `client.reconnect_mcp_server(name)` | Reconnect a specific MCP server | | `client.toggle_mcp_server(name, enabled)` | Enable or disable an MCP server | | `client.get_available_models()` | Get the list of available models |
## Types
### `QoderAgentOptions` Configuration object for `query()` and `QoderSDKClient`. The Python SDK uses snake\_case field names. | Field | Type | Default | Description | | :----------------------------------- | :------------------------------------------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------- | | `auth` | `InternalAuthOptions \| dict \| None` | `None` | Authentication configuration | | `on_auth_expired` | `Callable \| None` | `None` | Callback when authentication expires; triggered at most once per session | | `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tool set. Pass a string array to restrict available tools; built-in tool names are listed in [Built-in Tool List](#built-in-tool-list) | | `allowed_tools` | `list[str]` | `[]` | Tool allowlist; listed tools are pre-authorized | | `disallowed_tools` | `list[str]` | `[]` | Tool blocklist; takes priority over `allowed_tools` and `permission_mode` | | `can_use_tool` | [`CanUseTool`](#canusetool) | `None` | Custom tool permission callback | | `permission_mode` | [`PermissionMode`](#permissionmode) | `None` | Session permission mode | | `allow_dangerously_skip_permissions` | `bool` | `False` | Allow skipping permission checks; used together with `permission_mode="bypassPermissions"` | | `permission_prompt_tool_name` | `str \| None` | `None` | MCP tool name for permission prompts; mutually exclusive with `can_use_tool` | | `model` | `str \| None` | `None` | Model to use | | `fallback_model` | `str \| None` | `None` | Fallback model when the main model fails | | `resolve_model` | [`ModelPolicyProvider`](#modelpolicyprovider) | `None` | Dynamic model-selection callback. Passing it switches into dynamic-callback mode; see [Model Policy](/en/cli/sdk/python/model-policy) | | `resolve_model_timeout_ms` | `int` | `500` | Callback timeout (milliseconds); only effective when `resolve_model` is passed | | `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | System prompt | | `cwd` | `str \| Path \| None` | `None` | Working directory | | `env` | `dict[str, str \| None]` | `{}` | Environment variables passed to the CLI process | | `cli_path` | `str \| Path \| None` | `None` | Path to the qodercli executable | | `session_id` | `str \| None` | `None` | Specify the session UUID | | `resume` | `str \| None` | `None` | Session ID to resume | | `continue_conversation` | `bool` | `False` | Continue the most recent session | | `fork_session` | `bool` | `False` | When used with `resume`, fork into a new session ID | | `max_turns` | `int \| None` | `None` | Maximum conversation turns | | `include_partial_messages` | `bool` | `False` | Include `StreamEvent` streaming fragments; see [Streaming Output](/en/cli/sdk/python/streaming-output) | | `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP server configuration; see [MCP](/en/cli/sdk/python/mcp) | | `allowed_mcp_server_names` | `list[str]` | `[]` | Restrict which MCP servers are available | | `strict_mcp_config` | `bool` | `False` | Strict MCP validation | | `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Lifecycle hooks; see [Hooks](/en/cli/sdk/python/hooks) | | `agents` | `dict[str, AgentDefinition] \| None` | `None` | Programmatically defined subagents; see [Agents Reference](#qoderagentoptionsagents) | | `agent` | `str \| None` | `None` | Agent name used by the main thread; see [Agents Reference](#qoderagentoptionsagent) | | `settings` | `str \| Path \| Settings \| None` | `None` | Inline settings object or settings file path | | `setting_sources` | `list[SettingSource] \| None` | `None` | Which filesystem settings to load | | `add_dirs` | `list[str \| Path]` | `[]` | Additional directories accessible to the AI | | `extra_args` | `dict[str, str \| None]` | `{}` | Additional arguments passed to the CLI | | `plugins` | `list[SdkPluginConfig]` | `[]` | Load local plugins; see [Plugins](/en/cli/sdk/python/plugins) | | `skills` | `list[str] \| Literal["all"] \| None` | `None` | Enabled skills; pass `"all"` to enable all | | `enable_file_checkpointing` | `bool \| None` | `None` | Enable file checkpointing | | `thinking` | `ThinkingConfig \| None` | `None` | Thinking configuration |
### Authentication ```python theme={null} from qoder_agent_sdk import access_token, access_token_from_env, qodercli_auth ``` | Factory function | Description | | :-------------------------------- | :----------------------------------------------------------------------- | | `access_token(token)` | Pass the PAT directly | | `access_token_from_env()` | Read from the default environment variable `QODER_PERSONAL_ACCESS_TOKEN` | | `access_token_from_env("MY_PAT")` | Read from a specified environment variable | | `qodercli_auth()` | Reuse the local `qodercli login` session | For convenience usage, see [SDK Authentication](/en/cli/sdk/python/authentication).
## Agents Reference This page summarizes the stable configuration items related to SDK Agents. For getting started and usage scenarios, see [Subagent Usage Guide](/en/cli/sdk/python/agents).
### Sources of Available Agents The agents available in the current session may come from multiple sources: | Source | Description | | --------------------- | ----------------------------------------------------------------- | | SDK registration | Registered for the current session via `QoderAgentOptions.agents` | | CLI built-in | Built-in Agents registered when qodercli starts | | User / project config | Agent definitions in the user or project configuration directory | | Plugin | Agents provided by loaded plugins | In the interactive CLI, you can run `/agents` to view the currently discovered Agents; on the command line, run `qodercli agents list`. In the Python SDK, after `QoderSDKClient` connects, call `client.supported_agents()` to get a summary of agents available in the current session.
### `QoderAgentOptions.agents` **Type:** `dict[str, AgentDefinition] | None` Registers custom Agents available in the current session. The dict key is the Agent name and the value is that Agent's definition. > **The `Agent` tool is required**: Custom subagents require the main session to delegate through the built-in `Agent` tool, so `allowed_tools` must include the `Agent` tool. ```python theme={null} from qoder_agent_sdk import AgentDefinition, QoderAgentOptions options = QoderAgentOptions( allowed_tools=["Agent"], agents={ "reviewer": AgentDefinition( description="Reviews code quality and reports actionable findings.", prompt="Review the requested code and report concrete issues.", tools=["Read", "Grep", "Glob"], ), }, ) ``` After registration, the model can invoke these subagents through the built-in `Agent` tool. The main session must include `Agent` in its tool set to delegate work; `allowed_tools=["Agent"]` is the required pre-authorization form. If you use `tools` to narrow the main session's available tools, include `Agent` there as well.
### `QoderAgentOptions.agent` **Type:** `str | None` Specifies which Agent identity the main session runs as. The value can be a name registered in `agents`, or a built-in / plugin Agent name discovered by the current CLI. ```python theme={null} options = QoderAgentOptions( agents={ "planner": AgentDefinition( description="Plans work before implementation.", prompt="Break work into steps, risks, and validation checks.", tools=["Read", "Grep", "Glob"], ), }, agent="planner", ) ``` When set, the main session uses that Agent's `prompt`, `model`, and tool restrictions. When omitted, the default main-session behavior is used.
### `AgentDefinition` Definition of a custom Agent. The Python SDK's `AgentDefinition` is a dataclass whose field names use the protocol-style camelCase. The fields below are the stable capabilities currently covered and verified by the SDK. ```python theme={null} from dataclasses import dataclass from typing import Any, Literal @dataclass class AgentDefinition: description: str prompt: str tools: list[str] | None = None disallowedTools: list[str] | None = None model: str | None = None skills: list[str] | None = None mcpServers: list[str | dict[str, Any]] | None = None initialPrompt: str | None = None maxTurns: int | None = None effort: Literal["low", "medium", "high", "max"] | None = None permissionMode: PermissionMode | None = None ``` | Field | Type | Required | Description | | ----------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `description` | `str` | Yes | Agent purpose description; the model uses it to decide when to invoke the Agent | | `prompt` | `str` | Yes | Agent system prompt | | `tools` | `list[str] \| None` | No | Tool allowlist for this Agent | | `disallowedTools` | `list[str] \| None` | No | Tools excluded from this Agent's tool set | | `model` | `str \| None` | No | Model override; `"inherit"` means inherit the main session model | | `mcpServers` | `list[str \| dict[str, Any]] \| None` | No | MCP server specs available to this Agent | | `skills` | `list[str] \| None` | No | Skill names preloaded into the Agent context | | `initialPrompt` | `str \| None` | No | First user input automatically submitted when this Agent is used as the main session Agent | | `maxTurns` | `int \| None` | No | Maximum API turns for the Agent | | `effort` | `"low" \| "medium" \| "high" \| "max" \| None` | No | Reasoning effort level | | `permissionMode` | `PermissionMode \| None` | No | Permission mode for tool execution inside this Agent | The Python SDK serializes `AgentDefinition` into the initialize request via `dataclasses.asdict()`; qodercli then parses it according to the current Agent schema.
#### `description` Describes what tasks the Agent is suitable for. It affects whether the model chooses this Agent. ```python theme={null} description="Runs project tests, analyzes failing output, and suggests fixes." ``` Prefer a clear triggering scenario. Avoid broad descriptions such as `Helpful assistant`.
#### `prompt` The Agent's system prompt. Use it to define the role, constraints, and output format. ```python theme={null} prompt="""You are a security reviewer. Check for authentication bypass, authorization bugs, injection risks, and secret leaks. Return findings sorted by severity.""" ```
#### `tools` Tool allowlist for the Agent. When set, the Agent can only use the listed tools. ```python theme={null} tools=["Read", "Grep", "Glob"] ``` When `tools` is omitted, the subagent default tool set is used. A subagent's tool set does not inherit trimming from the main session's `allowed_tools`.
#### `disallowedTools` Excludes specific tools from the Agent's tool set. ```python theme={null} disallowedTools=["Bash", "Write"] ``` When `disallowedTools` is omitted, the subagent does not inherit trimming from the main session's `disallowed_tools`. Usually avoid setting both `tools` and `disallowedTools` unless you explicitly know the final tool set.
#### `model` Specifies the model for the Agent; when omitted, the session default model is used. At the Python type level it is `str | None`; the SDK does not restrict specific strings locally. Common model tiers include: | Value | Tier | Description | Suitable for | Credit cost | | --------------- | ------------- | ------------------------------------------------------------------- | ----------------------------------------------------- | ----------- | | `"auto"` | Smart routing | Intelligently selects the best model, balancing capability and cost | Most daily development work; recommended default | \~1.0x | | `"ultimate"` | Ultimate | Expert-level deep reasoning and thinking capability | Complex system design and difficult analysis | \~1.6x | | `"performance"` | Performance | Advanced reasoning and high-quality output | Core implementation, architecture design, refactoring | \~1.1x | | `"efficient"` | Efficient | Standard reasoning with good cost efficiency | Basic code generation, unit tests, daily Q\&A | \~0.3x | | `"lite"` | Lite | Basic reasoning, free to use | Quick validation, simple logic, quick questions | 0x | Agents also support two special forms: | Value | Description | | ------------- | -------------------------------------------------------------------------- | | `"inherit"` | Inherit the main session model; usually not echoed in `supported_agents()` | | Full model ID | Directly specify a model ID supported by the current CLI / backend |
#### `mcpServers` ```python theme={null} mcpServers: list[str | dict[str, Any]] | None ``` Limits or adds MCP servers available to this Agent. Each entry can be a session-level server name, or an inline server configuration mapping. Reference a session-level MCP server: ```python theme={null} options = QoderAgentOptions( mcp_servers={ "orders": { "command": "python", "args": ["servers/orders.py"], }, }, allowed_tools=["Agent"], agents={ "support": AgentDefinition( description="Answers support questions using order tools.", prompt="Use order tools when needed and return a concise answer.", mcpServers=["orders"], tools=["mcp__orders__lookup_order"], ), }, ) ``` Configure a dedicated MCP server for a specific Agent: ```python theme={null} AgentDefinition( description="Searches the internal knowledge base.", prompt="Search the knowledge base and cite relevant entries.", mcpServers=[ { "kb": { "command": "python", "args": ["servers/kb.py"], }, }, ], tools=["mcp__kb__search"], ) ``` When you only want to expose a specific MCP tool, also configure `tools=["mcp__server__tool"]` to avoid exposing every tool of that server to the Agent.
#### `skills` A list of skill names preloaded into the Agent context. Plain skill names and plugin-qualified names are both supported. ```python theme={null} skills=["review", "sdk-test-plugin:sdk-echo"] ``` For session-level skill behavior, see [Skills](/en/cli/sdk/python/skills).
#### `initialPrompt` Automatically submitted as the first user input when this Agent becomes the main session Agent through `QoderAgentOptions.agent`. ```python theme={null} initialPrompt="Start by scanning authentication and session management code." ``` This field only takes effect for the main session Agent. It is ignored when the Agent is invoked as a subagent through the `Agent` tool.
#### `maxTurns` Limits the Agent's maximum API turns. Use it to control cost, execution time, and loop risk. ```python theme={null} maxTurns=6 ```
#### `effort` ```python theme={null} EffortLevel = Literal["low", "medium", "high", "max"] ``` Controls the Agent's reasoning effort level. Higher `effort` is usually suitable for complex reviews, architecture analysis, and high-risk changes, but increases latency and token usage.
#### `permissionMode` Controls the permission mode for tool execution inside this Agent. It uses the same semantics as the session-level `permission_mode`, but its scope is limited to this Agent. For the session-level permission chain, the priority of `allowed_tools` / `disallowed_tools` / `can_use_tool`, and examples, see [Permission Control](/en/cli/sdk/python/permissions#controlling-default-policy-permission_mode). ```python theme={null} PermissionMode = Literal[ "default", "acceptEdits", "plan", "bypassPermissions", "yolo", "dontAsk", "auto", ] ``` | Value | Meaning | Suitable for | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `"default"` | Standard permission behavior. Tool calls still pass through tool sets, allow / deny rules, runtime approval, or CLI default policy | Most interactive subagents | | `"acceptEdits"` | Automatically accepts file-edit operations; other sensitive operations still follow the permission flow | A subagent that is approved to modify workspace files | | `"bypassPermissions"` | Skips permission checks. High-risk mode, usually only for trusted automation or test environments | Controlled CI, temporary validation, one-off automation | | `"yolo"` | Compatibility alias for `"bypassPermissions"`; also skips permission checks | Compatibility with older configs; not recommended for new code | | `"plan"` | Plan mode. Suitable for producing a plan first; by default it does not perform real changes | Planning, design, review, or cases where the subagent should not modify files | | `"dontAsk"` | Does not ask interactively; operations that are not pre-authorized or allowed by rules are denied | Non-interactive environments, or workflows that should fail instead of prompting | | `"auto"` | Runtime capability decides allow or deny automatically | Reduce confirmation interruptions while retaining runtime judgment | For permission semantics, see [Permission Control](/en/cli/sdk/python/permissions).
### `AgentInfo` Agent summary returned by `QoderSDKClient.supported_agents()`. ```python theme={null} class AgentInfo(TypedDict): name: str description: str model: NotRequired[str | None] ``` The Python SDK does not currently export a TypedDict named `AgentInfo`; the return type of `supported_agents()` is `list[dict[str, Any]]`. The structure above is the stable field convention of the actually returned dicts. | Field | Type | Description | | ------------- | ------------- | ------------------------------------------------------------------------ | | `name` | `str` | Agent name | | `description` | `str` | Agent purpose description | | `model` | `str \| None` | Agent model override; usually empty when unset or when `model="inherit"` | ```python theme={null} from qoder_agent_sdk import AgentDefinition, QoderAgentOptions, QoderSDKClient options = QoderAgentOptions( agents={ "reviewer": AgentDefinition( description="Reviews code quality.", prompt="Review code and report findings.", ), }, ) client = QoderSDKClient(options=options) await client.connect("List agents.") agents = client.supported_agents() await client.disconnect() ``` The returned list may include Agents registered through `agents`, and may also include built-in, project, user, or plugin Agents discovered by the current CLI. The actual available entries depend on the qodercli version and current configuration.
### Context and Invocation Boundaries * Subagents use independent context and do not receive the parent session's full history. * The main information passed from the parent session to a subagent is the task prompt supplied to the `Agent` tool. * A subagent's intermediate tool results do not directly enter the parent session; the parent session receives the subagent's final response. * Subagents cannot spawn their own subagents, so do not put `Agent` in a subagent's `tools`. * `initialPrompt` only takes effect for the main session Agent specified by `agent`.