Loading the documentation…

The Oda Python SDK

The Oda Python SDK lets a Python program drive DataMind Oda as a subprocess: your program starts a bundled Oda runtime and talks to it over newline-delimited JSON-RPC on standard input and output. Use it when a script or an internal tool of yours should run Oda tasks from outside the app.

This page covers installation, a first run from the shipped example, the profiles and the settings you pass. The SDK family starts at the Oda SDK overview. The run results, the runtime's lifecycle, the wire surface and the error details are in the Python SDK reference.

Install the SDK

The Python side of the SDK is two packages, installed together: the SDK package (the client, which starts the bundled runtime for you and drives runs through it) and the runtime package (the bundled Oda runtime for one system, with its supporting files). The SDK package declares the runtime package as a dependency, so an install brings the package that matches your operating system and processor, and the two share one version.

Python 3.10 or later. Both packages install on Python 3.10 and newer.
No system Node.js. The runtime ships prebuilt inside the runtime package: using the SDK needs no system Node.js and no build step, and nothing extra is downloaded or compiled at install time.
Source builds are explicit. The released packages carry the production runtime only; running against a development source build takes an explicit request, and a normal launch never selects one, so a production deployment never runs on a source build by accident.
The right package for your system. A system with no published runtime package is refused rather than served by another system's build.

System	Runtime package
Linux, x64 and arm64	Yes
macOS, x64 and arm64	Yes, on macOS 14 or later
Windows, x64	Yes
Windows on Arm	No

These packages are independent of the DataMind Oda desktop app; Install and sign in covers the app itself. Platform support covers the app's sandbox on each system.

Your first run

Choose the folders. Pass the home folder: every launch needs one, and the SDK never falls back to a default home folder; the runtime keeps the profile it runs and the sessions it creates there (Oda's home folder and settings files). Pass the workspace folder the agent should work in (cwd); it defaults to the folder your program runs in and is resolved to an absolute path before the runtime starts.
Create the client. Construct it with the home folder, the workspace folder and the profile you want; the settings table below lists what else you can pass. The client starts the bundled runtime as a subprocess when it is first needed and reuses it for later runs; you never start the runtime by hand.
Run a prompt. Pass the task text, and a session id if you want to name the session. The call returns when the session goes idle; read the final response and the finish reason from the result.
Close when you are done. Closing stops the runtime in stages, from a shutdown request to a forced end, and it is safe to call again; a context manager closes it for you when the block ends.

Start from the shipped example

The SDK package ships a runnable minimal example: it drives the sdk-minimal profile, runs one task and prints the agent's final response. These are the choices it takes:

What you pass	What it decides
The task text	The prompt for the run.
The workspace folder	The folder the agent works in.
The home folder	Where the runtime keeps its profile and sessions; the example stops without one, with a message that an explicit home is required.
The profile	Which profile to drive; it defaults to `sdk-minimal`.
The session id	A name for the session; without one, the run gets its own.
The provider and model	The model route; without them, the built-in route applies, and the runtime resolves it before the first prompt.
The token cap	Optional; caps the output of each request.

Profiles

sdk is the default. A client you create runs the sdk profile unless you pass another; it answers SDK clients and carries the usual tool set.
sdk-minimal is a small standalone runtime. It carries one model adapter and exposes exactly one tool, a persistent shell, with none of the shared services. It is built as its own tree rather than an extension of the usual profile, so anything extra is an explicit change. Automation with Oda describes what it includes and leaves out.
A profile of your own must keep the JSON-RPC server. A profile you build must keep the part that answers SDK clients; without it the profile cannot serve a client, and the problem surfaces when the runtime starts or the SDK initializes, with no fallback to a working configuration.
The web application is separate. An SDK client cannot select it: it is not a serving profile.
Manage a profile's packages on the command line. The plugin command adds packages to a profile; DataMind Oda on the command line shows it. Managing external packages needs pnpm on your PATH; launching the SDK does not.

Settings and defaults

These are the settings you pass when you create the client, with their defaults:

Setting	Default	What it does
Home folder	required	Where the runtime keeps its profile and sessions; every launch needs one and the SDK never falls back to a default.
Working folder (`cwd`)	your program's folder	The folder the agent works in; resolved to an absolute path before launch.
Runtime folder (`runtime_cwd`)	the working folder	The folder the runtime process itself starts in.
Profile (`profile`)	`sdk`	The profile the bundled runtime runs.
Patch files (`patches`)	none	Absolute paths, applied in order after the profile's own layers; the later file wins.
Provider and model (`provider`, `model`)	the built-in route	The model route, resolved before the runtime accepts a prompt; a route it cannot serve fails the start instead of falling back.
Reasoning effort (`reasoning_effort`)	the model's default	How long the model thinks before it answers; omit it for the model's own default.
Token cap (`max_tokens`)	none	Caps the output of each request; sub-agents that run in the same process inherit the cap.
Service address and key (`base_url`, `api_key`)	your environment	Override the address and key the runtime starts with; without them the runtime inherits your program's environment, so credentials already set there keep working.
Start-up timeout (`initialize_timeout_seconds`)	30 seconds	How long the start-up handshake may take before the client gives up.
Shutdown timeout (`shutdown_timeout_seconds`)	1 second	How long the shutdown request may take before the client moves on.
Request timeout (`request_timeout_seconds`)	none	With no value, a run waits for the task, however long it takes, because a turn can run long.

Patches, Office and skills

Ordered patch files. Pass one or more patch files as absolute paths; they apply in order after the profile's own layers, and when two change the same entry the later file wins.
Applied at the next start. A patch change takes effect when the runtime process starts; there is no rebuild step, even for skills and other resources.
Office documents out of the box. The runtime package carries the Office document skills, so a session can author and check Word, PowerPoint and Excel files (Bundled skills).
Turn them off or replace them. A patch can disable the Office skill, or point it at a replacement resource folder through its assetRoot; both take effect at the next start.

yaml

- id: skill-office
  disabled: true

Your files win. A skill you keep on the filesystem overrides a bundled skill with the same name.

Questions, answered

How do I install the Python SDK?

Two packages, installed together: the SDK package (the client) and the runtime package for your operating system and processor. The SDK package brings the matching runtime package with it, and the two share one version. Both run on Python 3.10 or later.

Do I need a system Node.js?

No. The runtime ships prebuilt inside the runtime package, so using the SDK needs no system Node.js and no build step. Only a development source build needs a system Node.js, and that route is an explicit request.

What happens if I launch without a home folder?

The launch is refused: every launch needs an explicit home folder, and the SDK never falls back to a default one. The error says an explicit home is required.

Which profile should I use?

Start with sdk, the default: it answers SDK clients with the usual tool set. Choose sdk-minimal for exactly one persistent shell tool; Automation with Oda describes what it includes and leaves out. A profile you build must keep the part that answers SDK clients.

Which systems have a runtime package?

Linux x64 and arm64, macOS x64 and arm64 on macOS 14 or later, and Windows x64. Windows on Arm has none, and a system with no published runtime package is refused rather than served by another system's build.

Where do the sessions live?

Under the home folder you pass, as plain JSON lines, one record per line.

What happens if start-up takes too long?

The start-up handshake is bounded: the client gives it 30 seconds (initialize_timeout_seconds), and the timeout error carries the runtime's recent diagnostics. Ordinary runs are unbounded unless you set request_timeout_seconds, because a turn can run long.

When do patch changes take effect?

At the runtime's next start. There is no rebuild step, even for skills and other resources.

Can I disable the Office document features?

Yes. Disable the Office skill in a patch, or point it at a replacement resource folder; the change takes effect at the next start. A skill you keep on the filesystem still overrides a bundled skill with the same name.

What if the model I name cannot be served?

The start fails: the runtime resolves the route before it accepts a prompt, and a route it cannot serve does not fall back to a default. Name a provider and model this runtime can serve and start again.

Why can't my custom profile serve a client?

It is missing the part that answers SDK clients (the JSON-RPC server). Without it the profile cannot serve a client, and the problem surfaces when the runtime starts or the SDK initializes. Keep that part in the profile and try again.

Can I drive the web application with the SDK?

No. The web application is separate and is not a serving profile, so an SDK client cannot select it.