Loading the documentation…

Oda as an automation server (ACP)

A DataMind Oda process can serve a program instead of a person. In the automation profile it speaks the Agent Client Protocol (ACP) over standard input and output, and your client creates, drives and closes persistent Oda sessions through it. This page covers running that server and working with it: connecting, sessions, MCP tools, permissions, model settings and limits.

Starting a profile is on Oda profiles and launchers, and the serving modes are compared on Automation with Oda. The Oda SDK overview and The Oda Remote API cover the other ways a program can drive Oda.

Start the server and connect

Start Oda in the automation profile (acp) for your client. One process serves one client and runs until that client disconnects; the profile can name a default provider and model for the sessions it creates.
Send initialize. The answer names the protocol version, the server's name and version, and what the connection supports: MCP servers over HTTP, image prompts when the runtime has them (audio and embedded context are not supported), sessions that can be closed, listed and resumed, and no authentication methods. A request for a version the server does not support still gets an answer that names the version the server speaks.
Send authenticate. It succeeds immediately: the server requires no authentication of its own.

Note

Standard output carries protocol messages only. Keep everything else, such as a logger, off that stream: your client reads every byte of it.

The calls

Your client drives the server with these calls:

Call	What it does
`initialize`	Opens the connection; names the protocol version and the server.
`authenticate`	Succeeds immediately; no authentication is required.
`session/new`	Creates a session, with its working folder and MCP servers.
`session/prompt`	Sends one prompt to a session.
`session/cancel` (`$/cancel_request`)	Cancels the prompt in flight.
`session/list`	Lists the sessions that can be resumed.
`session/resume`	Reopens a stored session.
`session/set_config_option`	Changes the Model or the Reasoning effort for the next turn.
`session/close`	Closes the session.

The server sends two kinds of message of its own: session/update, with what the session is doing while it works, and session/request_permission, a request to allow or reject one action (see Permissions).

Manage sessions

Create. session/new and session/resume need an absolute working folder (cwd must be an absolute path: <cwd>), and a session keeps one folder only (additionalDirectories is not supported). Declare its MCP servers here. An empty session is stored before the call returns.
Run several. One connection can carry several sessions at once; each session runs one prompt at a time.
List. session/list returns the sessions that can be resumed, newest first, with a cursor for the next page (up to 100 summaries per page by default). It leaves out sessions that are live in the process, subagent sessions, forked sessions, and sessions whose folder is missing or relative. A cursor it cannot read is refused: session/list cursor is invalid.
Resume. session/resume reopens a stored root session: it checks the folder, restores the latest model route, reconnects the MCP servers the request declares, and does not replay earlier updates. Its refusals: session is already active: <id>, session is not resumable: <id>, session cwd does not match: <cwd>.
Close. session/close cancels what is running, lets the session's updates and subagent work drain, flushes what is stored and releases the session. A failure in that sequence is reported (session close failed: <detail>), and new work sent during the close is refused with session is closing: <id>. After a close, the session can be listed and resumed again.
Unknown ids. A call that names a session the server does not know is refused with unknown session: <id>.
Across restarts. Listing, resuming and closing survive a restart of the server process. Deleting a session and forking one are not supported.

Send prompts and follow the work

session/prompt carries text, images, or both. Text blocks next to each other are joined, and a resource link is rendered into the message text. A prompt that ends up with no text and no images is refused as empty prompt.
Images are raster only: PNG, JPEG, WebP or GIF, sent as canonical base64. Anything else is refused with image mimeType must be image/png, image/jpeg, image/webp, or image/gif or image data must be canonical base64. An image is admitted only when the connection advertised image support, the runtime can store it, and the selected model accepts image input. Otherwise the prompt is refused with inline image prompts were not advertised by this connection or model "<model>" does not declare image input.
The whole prompt is checked before anything is stored: a partly valid image batch is refused in full.
One prompt at a time per session: a second prompt is refused with a prompt is already in flight for this session until the first settles.
session/cancel (or $/cancel_request) cancels the prompt in flight, and it settles as cancelled. With nothing in flight, it cancels autonomous work, and an unknown session id makes it a no-op.
While work runs, your client receives session/update messages: thought chunks, message chunks, tool calls that start and then complete or fail, and a usage update when usage can be measured.
A prompt settles after its ordered updates have drained, with one of these reasons:

The turn ends	Your client is told
Completed	`end_turn`
At its token limit	`max_tokens`
Cancelled by your client	`cancelled`
Interrupted	`cancelled`
Blocked or failed	`end_turn`
Aborted by a hook or another owner	`end_turn`

A turn that stopped at its token limit keeps the text it had already committed. A turn that failed reports its reason and publishes nothing partial: turn failed: <detail>.

Attach MCP servers

Declare your MCP servers when you create the session. A resume reconnects the servers its request declares.
Two transports are supported: a local server (an absolute command, with its arguments and environment) and a streamable HTTP server (an absolute URL, with its headers). Anything else is refused: mcpServers[N] transport <type> is not supported.
Your client is a trusted controller: a local declaration authorises that command and its environment, and an HTTP declaration authorises its URL and its headers. Declare only servers you trust.
The tools of a server reach the session as mcp__<server>__<tool>. A server name that does not match the simple pattern of letters, digits, underscores and hyphens is normalised.
Declarations are checked before the session starts, so nothing is left behind when one is invalid: mcpServers contains duplicate normalized name: <name>, mcpServers[N].command must be an absolute path, mcpServers[N] is invalid: <detail>, <field> must be an absolute HTTP(S) URL.
MCP servers give a session the tools of other services; how connectors work in the app is on Memory, skills and connectors.

Permissions

A session/request_permission request offers two one-shot choices, Allow once and Reject. Your client can answer it automatically; neither choice is a lasting grant, so the next request asks again.
With no answer, the request settles as cancelled and no access is granted. An unknown choice never grants access, and a failure on your client's side fails closed.

Choose the model and reasoning effort

session/set_config_option offers a Model selector and a Reasoning effort selector. The effort selector appears only when the exact model declares reasoning, and it includes a Provider default choice when the model declares no default effort of its own.
Only the routes the deployment keeps visible are offered, and a session already on a hidden route can keep it. The values are opaque: pass back the value the option gave you.
Unknown values are refused: unknown model option: <value>, unknown reasoning effort for <provider>/<model>: <value>, unknown session config option: <configId>.
A change applies to the next turn: a prompt already running keeps the model and effort it started with, including while its images are being admitted.

Limits and unsupported surfaces

One primary workspace per session, raster images only, and MCP servers for extra tools.
Not supported: session/load, session deletion, forks, additional directories, SSE and ACP transports for MCP, modes, commands, plans, terminals, client filesystem operations, and elicitation.
No transcript replay, and no interactive extensions.

Questions, answered

How do my MCP servers' tools appear in a session?

As mcp__<server>__<tool>, where the middle part is the server's name from the declaration. A name that does not match the simple pattern of letters, digits, underscores and hyphens is normalised to fit. Several servers can be attached to one session, and the same server can be used in independent sessions.

Why was my MCP declaration refused?

Declarations are checked before the session starts, and one invalid entry stops the whole request, so nothing is left behind. Common reasons: two names normalise to the same server name (mcpServers contains duplicate normalized name: <name>), a local command is not an absolute path (mcpServers[N].command must be an absolute path), the transport is not a local command or streamable HTTP (mcpServers[N] transport <type> is not supported), or an HTTP entry's address is not an absolute HTTP(S) URL (<field> must be an absolute HTTP(S) URL). The report names the failing entry by its index.

What happens to a running prompt if my client disconnects?

The connection closes in stages: the server cancels the prompt in flight, lets the session's updates drain, flushes what is stored and releases the session. The session itself stays stored, so it can be listed and resumed later.

Do my sessions survive a restart of the server?

Yes. Listing, resuming and closing work across process restarts, and a resume continues the stored session without replaying earlier updates. Deleting a session and forking one are not supported.

Can I delete or fork a session?

No. Session deletion and forks are not supported over ACP; a session is created, prompted, closed, and resumed again later.

Why did my prompt fail?

The call answers with its reason, such as turn failed: <detail> when the turn ended in failure, or prompt was not queued: <detail> when the prompt could not be accepted. A failed turn publishes no partial output, and the session is not stuck: the prompt slot is free again, so your client can send the next prompt.

Why was my session not resumed?

Three common reasons: it is active (session is already active: <id>), it is not a stored root session (session is not resumable: <id>), or the folder you gave differs from the session's (session cwd does not match: <cwd>). Sub-agent and forked sessions cannot be resumed.

Which images can a prompt carry?

PNG, JPEG, WebP or GIF, as canonical base64, and only when the connection advertised image support and the selected model accepts image input. Otherwise the prompt is refused with inline image prompts were not advertised by this connection or model "<model>" does not declare image input.

Why is there no usage update?

A usage update appears only when the server can measure usage and the session reports a context capacity. When either is missing, the update is left out, and the rest of the updates still arrive.

How do I go back to the model's default reasoning effort?

Choose Provider default in the Reasoning effort option. It is offered when the selected model declares no default effort of its own.

Can my client answer permission requests on its own?

Yes. A request offers Allow once and Reject, and your client can answer it without a person. The choice is one-shot: it never becomes a lasting grant, so the next request asks again. With no answer, the request settles as cancelled and no access is granted; an unknown choice never grants access either.

How do I page through the session list?

session/list returns one page of up to 100 summaries by default, newest first, and carries a cursor for the next page; send the cursor back to continue. A deployment can change the page size, and a cursor the server cannot read is refused with session/list cursor is invalid.