Run an Oda runtime server

A runtime server lets a program of yours drive DataMind Oda without the app window: the program talks to the runtime over standard input and output and speaks the Oda SDK messages. This page describes the runtime's side of that conversation, from the handshake to shutdown. For the parts of the SDK, see the Oda SDK overview; to connect a program of your own, see Automation clients.

Serve one client

• One client at a time. A runtime serves a single client over standard input and output, from the first message until the client disconnects. Give each client its own runtime.
• One message per line. The two sides exchange newline-delimited JSON-RPC messages. The message shapes and payloads are on the SDK wire protocol page.
• Only the served methods work. A request for a method the runtime does not serve is refused, and the error names the method.

Start with the handshake

• One handshake before prompts. Your client completes one initialize before it sends anything else. Until a handshake completes, prompts are refused: SDK server is not initialized.
• The handshake names the route. It carries the working folder and the model route: provider, model, and, optionally, a reasoning effort and a token cap. The server resolves the exact route before it accepts prompts.
• Refused routes. A provider the runtime cannot serve fails with no adapter registered for provider "<provider>". A route that cannot run with the effort you asked for fails with provider "<provider>" model "<model>" does not support reasoning effort "<effort>".
• Checked fields. The reasoning effort must be a non-empty string (initialize reasoningEffort must be a non-empty string), and the token cap must be a positive safe integer (initialize maxTokens must be a positive safe integer). Omit a field to keep its default.

Send a prompt

• One agent per session id. The first prompt that names a session id creates its agent; later prompts with the same id reuse it.
• A prompt is a receipt, not a result. An accepted prompt queues one identified user message and returns { messageId } immediately. Nothing later is attributed to it; the answer arrives in the session.event stream while the run works.
• Prompts queue. More work can be enqueued on the same session, prompts for one session wait their turn, and a busy session does not block prompts for other sessions.

Attach images

• An inline image is stored as a durable attachment before the prompt is queued; the session keeps a reference to the stored image, not the raw bytes.
• If the runtime has no attachment store, it refuses the prompt rather than lose the image: SDK image prompt requires an attachment store.

Events and statuses

• Events stream as they happen. Every session event reaches the client as session.event, and every whole-agent lifecycle change as session.status: running while the agent works, idle when it stops.
• Subagents, when they run here. subagent.finished is sent only for a subagent run that happened in this runtime's own process; a run elsewhere is not reported through it.
• A token-limit stop is a failure by default. A run that ends at its token limit is reported as an error unless the runtime is configured to treat max-token terminations as successful results.

Shut down cleanly

• Shutdown flushes first. On a shutdown request the server writes the response, disposes the runtime so the agents and data it owns settle, and exits with code 0.
• New sessions stop first. Once shutdown has begun, a prompt that needs a new session is refused with SDK server is shutting down.
• Teardown failures are reported, not hidden. If parts of the runtime do not dispose cleanly, the shutdown answer carries the failure; several failures together read SDK server teardown failed. Restart the runtime before the next run.
• Sessions can be disposed outside the server. If something else stops a session's agent, the server refuses that session with session agent was disposed outside the server: <id>; the session cannot continue.

Questions, answered

Can two clients share one runtime server?

No. A runtime serves one client from the first message until it disconnects; give each client its own runtime.

My prompt failed with SDK server is not initialized. What does that mean?

The runtime has not completed an initialize handshake, so it does not accept prompts yet. Complete a successful handshake before sending prompts; if the handshake itself failed, its error says why.

Can my client send another prompt while a run is still working?

Yes. More work can be enqueued on the same session; prompts for one session wait their turn, and a busy session does not block prompts for other sessions.

Why does an image prompt fail with SDK image prompt requires an attachment store?

The runtime has no attachment store to keep the image, so it refuses the prompt instead of losing the image. The image itself is fine; the runtime needs attachment storage before it can accept inline images.

Why did I not get a subagent.finished notification?

It is sent only for a subagent run that happened in this runtime's own process. A subagent that ran elsewhere is not reported through it.

What do the running and idle statuses describe?

The whole agent, not one turn: running while the agent works and idle when it stops.

A turn stopped at its token limit. Why does the server report a failure?

By default a max-token stop is not a success. A runtime can be configured to report max-token terminations as successful results.

What happens to a prompt while the server is shutting down?

A prompt that needs a new session is refused with SDK server is shutting down. The runtime is finishing its shutdown; start a new runtime for the next run.

The server answered SDK server teardown failed. What do I do?

Several parts of the runtime did not shut down cleanly at once. Stop the runtime process and start a new one before the next run.

A session stopped working with session agent was disposed outside the server. Why?

Something outside the server stopped that session's agent, so the server refuses to drive the session further. Continue in a new session.