Automation with Oda

DataMind Oda can work without the app window: a script can give it one task and read the answer, a program of yours can drive chats over standard input and output, and an automation client can manage sessions of its own. Use this page to pick the entry point and see what each one needs; the linked pages hold the full detail.

Pick the entry point

• No app window is involved. Each entry point runs Oda as its own process, and none of them serves the interface. How a mode is started, with its options, is on Command line and flags.

Run one task and read the answer

A one-off run (the headless mode) answers a single task and exits.

1. Give the task as words on the command line, or send it on standard input.
2. Read the answer on standard output; the working notes (the model's reasoning) and any diagnostics go to standard error, so a script reads the answer without filtering it.
3. Read the exit code: 0 when the task completed, 1 when it did not, including a run that finished without an answer.

• A blank task is refused before anything runs.
• Continue an earlier run. Name the chat the earlier run saved, and the new task runs as its next message; a chat Oda does not know fails before the task runs: session "<id>" does not exist; omit --session-id to start a new Session.
• A run can report events instead of an answer. When a one-off run is asked for a JSON event stream, it writes one event per line instead of the final answer, so a program can follow the run as it works. The events and their bounds are on Headless runs.
• A model connection is needed. A run needs a model credential before it can answer: sign in to your DataMind server, or provide a key through Settings > Models (Set up models and providers). Until a credential resolves, model requests fail.

Drive chats from your own program

The Oda SDK serves a program of yours: a client starts an Oda runtime and talks to it over standard input and output with newline-delimited JSON-RPC messages. One runtime serves one client, from the first message until the client disconnects.

1. The client sends initialize with the working folder and the model route: provider, model, and, optionally, a reasoning effort and a token cap. Prompts are refused until the handshake completes.
2. The client sends session/prompt; the message is queued and the reply is a receipt, not an answer.
3. The work arrives as session.event notifications, and session.status reports the whole agent as running until it is idle, which means the turn has settled.
4. The client sends shutdown; the runtime flushes what it wrote and exits.

• A token-limit stop is not a finished run. A run cut off at its token limit is reported as a failure by default, and a runtime can be configured to treat max-token endings as successful results.
• A small standalone runtime. The sdk-minimal runtime serves an SDK client with one model adapter and a single shell tool, and it runs with full access to the computer: use it only with an isolated workspace. Automation clients covers it.
• Limits to know before you build. This protocol has no way to cancel a run or to close a single session, and the client and the runtime must be the same version. The messages, fields and error codes are on the SDK wire protocol; the serving side is on Run an Oda runtime server.

Serve an automation client

The automation profile (acp) serves a client that speaks the Agent Client Protocol. One process serves one client, runs until the client disconnects, and keeps standard output for protocol messages only.

1. Initialize the connection.
2. Create a session; give it an absolute working folder.
3. Choose the model for the session, and a reasoning effort where the model offers one, from the options the connection advertises.
4. Send prompts, and read the session's updates while the session works.
5. Close the session when you are done; sessions can also be listed and resumed later.

• Access is asked per request. A permission request offers Allow once or Reject. Both are one-shot, and a request your client does not answer is settled as cancelled with nothing granted.
• A running prompt can be cancelled; it settles as cancelled. With nothing in flight, the same call cancels autonomous work.
• Every prompt settles with a reason. A completed run ends as end_turn, a cancelled run as cancelled, and a run cut off at its token limit as max_tokens.
• The full call set, the refusals and the limits are on Automation with ACP; the serving profiles and their rules are on Automation clients.

Deliveries that start work

A verified GitHub delivery can open a chat by itself, through the rules you set up. The chat is an ordinary chat in the folder the rule names; nothing is queued or retried behind a delivery. Webhook sessions covers what a delivery creates and its limits.

Questions, answered

Which way should I automate Oda?

Match the entry point to what you already have. For one task from a terminal or a script, use a one-off run. For a program that should drive chats itself, use the Oda SDK. For a tool that already speaks the Agent Client Protocol, use the automation profile. All of them run Oda as its own process, and none needs the app window.

Which modes does Oda ship for automation?

One-off runs (the headless mode), the SDK profile (sdk) with its small standalone sibling (sdk-minimal), and the automation profile (acp) for Agent Client Protocol clients. The profiles and how they are started are on Command line and flags.

Do I need to set up a model before an automated run works?

Yes. Oda needs a model credential: sign in to your DataMind server, or provide a key through Settings > Models (Set up models and providers). Until a credential resolves, model requests fail.

Can one automation process serve several clients?

No. A serving mode works with one client per process, and it runs until that client disconnects; give each client its own process. The same holds for an SDK runtime.

Which models and effort choices does an automation client get?

The options the connection advertises: the model selector lists the routes the deployment keeps visible, and a reasoning effort selector appears when the model declares reasoning levels. Automation with ACP covers how a change applies.

What happens if my client does not answer a permission request?

The request settles as cancelled and nothing is granted; an unknown choice never grants access either, and a failure on the client's side fails closed. The next request asks again, because no decision is remembered.

What can an integration not do?

The Oda SDK protocol has no cancel and no per-session close, and an automation client cannot fork or delete sessions. Standard output must carry only protocol messages in every serving mode. Each linked page lists its own limits and unsupported surfaces.

How can I follow an automated run while it works?

A one-off run streams its working notes to standard error, and it can emit a JSON event stream instead of the final answer. An SDK client reads session.event notifications and the running and idle statuses. An automation client receives session/update messages while the session works. The linked pages list each event vocabulary.