Oda SDK overview

The Oda SDK lets your own program drive DataMind Oda from outside the app: a client process starts an Oda runtime and talks to it over standard input and output, so the work runs out of process. Use it when a script or an internal tool, rather than a person in the app, should start the work and follow it.

The three parts

The SDK family comes in three parts, and each has its own guide:

Part	What it is
Wire protocol	The newline-delimited JSON-RPC transport and the named request, result and notification types.
TypeScript client	A TypeScript package that starts the runtime for you and drives runs through a high-level and a protocol-level API.
Runtime server	The serving side: it answers an out-of-process client over standard input and output, one client at a time and one agent per session id.

Where you go next depends on your side of the connection:

TypeScript client guide: drive Oda from a TypeScript program.
SDK wire protocol: build a client of your own, or read and debug the messages.
Run an Oda runtime server: serve a client from a runtime you run yourself.

How a client starts a runtime

When your program uses the client, the client does the wiring:

It starts the runtime as a subprocess: the SDK profile, the runtime binary that comes with the CLI package, and any extra --patch <path> files you pass, applied in order.
It sends one start-up handshake (initialize) carrying the working folder and the model route: provider, model, and, optionally, a reasoning effort and a token cap.
The runtime resolves that exact route before it accepts any prompt. A provider, model or effort it cannot serve fails the handshake instead of falling back to a default.

Prompts are refused until the handshake completes.

The wire at a glance

The connection is newline-delimited: one JSON-RPC 2.0 message per line, over streams the caller owns. Three requests and four notifications:

Message	Kind	What it does
`initialize`	Request	Sets up the connection and resolves the model route.
`session/prompt`	Request	Queues one user message and returns its receipt (`messageId`) immediately.
`shutdown`	Request	Flushes what the runtime has written, winds its work down and exits.
`session.event`	Notification	A session event, as it is appended.
`session.status`	Notification	The whole agent's status: `running` or `idle`.
`subagent.started`	Notification	A subagent session started, with its parent lineage.
`subagent.finished`	Notification	A subagent run finished; sent only for runs in the same process.

The run lifecycle

The client owns one runtime across runs: it starts on first use and is kept until you close the client.
A run() settles when the whole agent next goes idle.
The client and the runtime must be the same version; the client checks this when it starts one.
Closing the client stops the runtime in stages: a shutdown request first, then a forced end if the process does not exit.

Limits to know before you build

No cancel, no session close. There is no method to cancel a running turn or to close a single session.
No version negotiation. A client and a runtime are matched versions; nothing negotiates between them.
No per-prompt result. Track answers through the session's event stream; the receipt confirms the queue, not the reply.
Standard output is protocol only. Keep loggers and every other writer off the runtime's standard output in a deployment.

The full list is on the SDK wire protocol page.

Questions, answered

Which part of the SDK do I need?

It depends on your side of the connection. To drive Oda from a TypeScript program, use the TypeScript client guide. To write a client in another language or read the messages, use the SDK wire protocol. To serve clients from a runtime of your own, read Run an Oda runtime server.

Can I drive Oda from another language?

Yes. The connection is newline-delimited JSON-RPC over standard input and output, and nothing about it is specific to TypeScript: implement the messages and you have a client. The SDK wire protocol documents every message for that work, and the TypeScript client is one implementation of it.

Who starts the runtime?

The client does. It starts the runtime as a subprocess the first time it is needed, with the SDK profile and your launch settings, and keeps it for later runs; you never launch the runtime by hand.

Does the SDK need the Oda app window open?

No. The runtime is a process of its own and the client talks to it over standard input and output; the app window is not involved.

What can I automate with the SDK?

A runtime is a complete Oda runtime, so an SDK session works like any other Oda session, with the same planning, tools and subagents. The connection changes how the work is started and followed, not what Oda can do.

Where do I look when a call fails?

Start where it failed. Failures on your side of the connection, like a timeout or a client that closed, are on the TypeScript client guide. Message-level failures, like an unknown method or a route that could not be resolved, are on the SDK wire protocol. Refusals the runtime itself reports are on Run an Oda runtime server.