Common integration scenarios

The integration pattern depends mainly on three questions: whether input continues after a task starts, whether tool actions require an external decision, and whether a session must survive process or host changes. This page maps common product shapes to the recommended TypeScript and Python entry points, capability combinations, and runtime boundaries.

Quick selection

Task
 |
 +-- One input is enough -----------> one-off query()
 +-- Follow-up input is required ---> TypeScript async message stream
 |                                    Python QoderSDKClient
 +-- Actions require approval ------> canUseTool / can_use_tool + Hooks
 +-- Sessions cross service hosts --> sessionStore / session_store + resume
 `-- Business systems are needed --> MCP tools, Skills, or custom Agents

Product shape	Recommended entry point	Key capabilities
Batch script or CI job	`query()` with a string task	`cwd`, tool scope, non-interactive permissions, Result
Interactive developer tool	TypeScript async message stream; Python `QoderSDKClient`	streaming output, added input, interrupt, session ID
Backend API or job service	create or resume a session per task	service authentication, concurrency control, external session storage
Human-approved automation	`canUseTool` / `can_use_tool`	allow/deny rules, approval UI, Hooks
Domain workflow	MCP, Skills, Agents, Plugins	business tools, domain instructions, reusable extension packages

Batch scripts and CI

Code inspection, test generation, migration reports, and documentation tasks often need one clear input and one final result. Call query() with a string and let the session end when the task completes.

CI job or scheduled task
          |
          v
   query("complete task")
          |
          +-- structured messages and tool activity
          `-- Result: success, failure, or interruption

Recommended configuration:

Use a PAT or Service Account authentication method intended for automation instead of a developer workstation sign-in.
Set cwd explicitly so file and command operations stay in the job workspace.
For reporting tasks, expose only read-oriented tools such as Read, Glob, and Grep. Add Edit, Write, or Bash only when changes are required.
Background jobs cannot open a confirmation UI. Combine explicit allow/deny rules with dontAsk so unapproved actions fail closed. acceptEdits fits jobs that may modify a controlled workspace.
Consume the stream through the Result and classify the outcome with subtype, errors, and error_code when available.

Skipping all permission checks is appropriate only when containers, disposable workspaces, or equivalent controls already isolate the task. See Permissions and Error handling and error codes.

Interactive developer tools

Chat-based coding assistants, IDE features, and internal engineering portals need to accept more input after a task starts and display Agent text, tool activity, and status as they arrive.

TypeScript: pass an AsyncIterable<SDKUserMessage> to query().
Python: create a session with QoderSDKClient, send messages with query(), and receive each turn with receive_response().
Drive interface updates from streaming events and use interrupt() to stop the active turn.
Store the session_id that belongs to each product conversation. Use resume to continue it or fork when the original branch must remain unchanged.
Assign an explicit delivery time to added input: change direction immediately, handle it at the next opportunity, or wait until the active turn finishes.

Chat or IDE
   |  input, follow-ups, interrupt
   v
long-lived session -----> streaming messages -----> interface
   |
   `--------------------> session_id

See Input Modes, Streaming Output, and Session Control.

Backend APIs and job services

A backend service can turn an HTTP request, queue message, or scheduled job into an Agent session. Each active local session owns a qodercli process, so capacity planning must cover process count, model requests, file systems, and command execution resources.

HTTP API / Queue
       |
       v
application service -----> Agent SDK -----> qodercli
       |                                      |
       +-- session index or external store    +-- workspace and commands
       `-- logs, timeout, and cancellation    `-- Qoder model service

A service integration commonly needs these constraints:

The runtime must allow qodercli child processes and provide the task workspace, commands, and dependencies.
Automated services use explicit credentials. Local sign-in is intended for developer workstations.
Map requests to stable session_id values. A single host can use local sessions; multiple hosts, containers, or ephemeral disks should mirror sessions through sessionStore / session_store.
Cross-host resume requires consistent project-directory semantics and project content on every eligible host.
A streaming endpoint can forward Agent events to the caller. An asynchronous job can persist progress and the final Result.
A timeout should call interrupt() or close the session while retaining useful error and process diagnostics.

See SDK Authentication and External Session Storage.

Human-approved workflows

Code changes, command execution, release actions, or business-system writes may require a product interface, approval system, or policy service to decide. Permission control has a static boundary and a runtime decision path:

tools determines which tools are visible in the session.
allowedTools / allowed_tools and disallowedTools / disallowed_tools define preapproved and prohibited operations.
canUseTool / can_use_tool receives an unapproved tool request and returns allow or deny.
Hooks validate, audit, or alert before and after tool execution.

Agent requests a tool
          |
          v
static rules ----deny----> denied tool result
          |
       approval
          v
product UI / policy service
    | allow          | deny
    v                v
execute tool      denied tool result

An approval view should present the tool name, important arguments, impact scope, and session context. Unattended jobs need a clear deny policy and timeout so a session cannot wait indefinitely. Approval callbacks and Hooks do not replace workspace isolation or least-privilege credentials. See Permissions and Hooks.

Business tools and domain capabilities

Extensions let the Agent read business data, call internal systems, and reuse domain-specific working methods. Select the extension type by its purpose:

Goal	Recommended capability	Suitable content
Call a function in the host process	in-process MCP tool	data lookup, ticket actions, internal API wrappers
Connect an existing tool service	external MCP server	independently deployed standardized tool sets
Reuse operating instructions	Skills	team conventions, diagnostic procedures, delivery templates
Define a specialist role	Agents	code review, test analysis, migration planning
Distribute a set of extensions	Plugins	a package of Skills, Agents, MCP servers, and commands

Tool inputs should use explicit structured fields, and responses should contain only the data required by the task. Business credentials should remain in the tool implementation or host service instead of being added to task text. Write operations should still pass through permission rules or approval callbacks. See Tools, MCP, Agents, Skills, and Plugins.

Production checklist

Runtime: qodercli starts successfully, cwd points to the correct isolated workspace, and required commands and dependencies are available.
Authentication: credentials come from environment variables or a secret manager, and logs and task text do not contain secrets.
Permissions: the tool set follows least privilege, and background jobs do not depend on an unavailable confirmation interface.
Lifecycle: the message stream is consumed through Result, with handling for timeout, interruption, process exit, and application shutdown.
Sessions: session_id is stored when resume is required, and multi-host deployments use shared session storage.
Concurrency: capacity accounts for active qodercli processes, workspaces, model requests, and tool resources.
Observability: Result, tool activity, and necessary diagnostics are recorded while credentials and sensitive business data are filtered.
Versions: use the runtime bundled with the SDK, or keep a separately configured qodercli executable compatible with the SDK version.

Quick Start — run the first TypeScript or Python task
How it works — understand processes, communication, and the Agent loop
SDK References — find the exact API for each language

​Quick selection

​Batch scripts and CI

​Interactive developer tools

​Backend APIs and job services

​Human-approved workflows

​Business tools and domain capabilities

​Production checklist

​Related documentation