Oda SDK overview

The Oda SDK lets a program of yours drive DataMind Oda from outside the app: its client 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 of yours, rather than a person in the app, should start the work and follow it.

The three parts

The SDK comes in three parts. A common reading order is: this page, then the client guide, then the wire protocol, then the runtime server page.

Part	What it is
Wire protocol	The newline-delimited JSON-RPC connection between a client and a runtime: every message, its payload, the error codes and the limits.
Client library	The TypeScript package that starts the runtime for you and drives its turns from your program.
Runtime server	The serving side: it serves one client over standard input and output and keeps one agent per session id.

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

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

How a client starts a runtime

The client starts the runtime for you, the first time it is needed. You never start the runtime by hand.
It starts the runtime on the sdk profile and applies your configuration patch files in the order you list them. The profiles Oda ships are listed on Oda profiles and launchers.
It sends one start-up handshake carrying the working folder and the model route: the provider, the model, and, optionally, a reasoning effort and a token cap. The handshake is sent once and reused.
The runtime resolves that exact route before it accepts any prompt. A route it cannot serve fails the handshake instead of falling back to a default, and prompts are refused until the handshake has completed.
The client requires a runtime of the same version as itself, and checks this when it starts one.

The wire at a glance

The two sides exchange one JSON-RPC 2.0 message per line. 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 sub-agent session started, with its parent lineage.
`subagent.finished`	Notification	A sub-agent run finished; sent only for runs in the same process.

The run lifecycle

The client keeps one runtime across runs: it starts on first use and stays until you close the client. Each run works in its own session.
A run settles when the whole agent next goes idle. While it works, the session's events and the agent's status stream over the connection.
Closing the client stops the runtime in stages: a shutdown request first, then the close of its input, then a stop signal, and finally a forced end. It finishes only when the process has exited.

Limits to know before you build

No cancel, no session close. There is no method to cancel a turn or to close one 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 events; 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.

The full list is on The Oda SDK wire protocol.

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 Oda SDK client. To build a client of your own or read the messages, use The Oda SDK wire protocol. To serve clients from a runtime you run yourself, read Running 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 Oda SDK wire protocol documents every message, and the TypeScript client is one implementation of it.

Who starts the runtime?

The client does. It starts the runtime for you, the first time it is needed, 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?

The runtime a client starts is a complete Oda runtime, so an SDK session works like any other Oda session. The connection changes how the work is started and followed, not what Oda can do.

Do I need the wire protocol to use the client?

No. The client speaks it for you: you send prompts and follow the events. Read The Oda SDK wire protocol when you build a client of your own, read a trace, or debug a message.

Where do I look when a call fails?

Start where it failed. Failures on the client side, such as a timeout or a client that is closed, are on The Oda SDK client. Message-level failures, such as an unknown method or a route that could not be resolved, are on The Oda SDK wire protocol. Refusals the runtime itself reports are on Running an Oda runtime server.