The Oda agent runtime

Behind every chat, DataMind Oda runs a live worker called an agent. The agent drives the chat's loop: it reads the session that records the conversation, builds each model request, runs tool calls and writes results back as they settle. This page describes the runtime itself: how agents are created, resumed and disposed, the states they move through, the operations that drive a conversation, and the options and limits that shape a run. The record an agent works on is described on Sessions and the transcript.

What an agent is

• A chat is backed by a session, its stored record, and by an agent, the worker that acts on it. The agent appends to the record as work settles, and the record can be read back to see what happened.
• An agent can create other agents. The creating agent is the parent, and the runtime keeps that relationship: it can find an agent by id (get), list the live agents (list), list the roots (roots), and check whether one agent belongs to another (isOwnedBy).
• An agent lives until it is disposed. When a stored session is resumed, a new agent picks up the same record.

Creating, resuming and disposing agents

1. Create or resume. Creating an agent returns a handle; resuming returns a handle that continues a stored session, repairing unfinished work first (see Recovering sessions after a crash).
2. Drive. The handle carries the operations described below, and work appends to the session as it settles.
3. Dispose. Disposing stops the loop, unregisters the agent, removes the session and unwinds the scope. Only the holder of the handle can dispose the agent.

• One id at a time. A second agent cannot join under an id that is in use: agent "<id>" is already registered.
• No half-created agents. Everything that listens for a new agent runs before the creation finishes, and a listener that refuses rolls the creation back.
• A clean ending. A disposal during a running turn closes that turn as aborted, with disposed as its cause.

Agents declared in configuration

Agents can also be declared in the profile the runtime loads, and declared agents start by themselves when it loads. Each declares:

• A fresh session id each start. An agent declared without sessionId or resumeSessionId mints a new session id on every startup, of the form <id>-session-<uuid>, so a restart never collides with an earlier run.
• One identity or the other. sessionId and resumeSessionId are mutually exclusive.
• No shared identities. Two declared agents cannot resolve to the same exact session identity: agents "<first>" and "<second>" use duplicate exact session identity "<id>". An empty id is refused.
• Validated caps. The token cap must be a positive safe integer: agent maxTokens must be a positive safe integer.
• Read at startup. The declared list is read when the runtime loads, so changing it takes a restart. The loop's own settings can change live, as described below.
• A failed start is contained. If a declared agent cannot start, no agent runs for it and a warning names it; a resume target that no longer exists warns config-driven resume of "<id>" failed instead of failing the whole start.

Driving a conversation

A handle drives the conversation through a small set of operations. They differ in where what they carry goes and whether the agent wakes for it.

• send hands the agent a message; it is the general delivery call that the named forms are built on.
• A follow-up queues a message for the next turn: an agent that is idle wakes for it, and one that is working takes it when the current turn finishes.
• A steer joins the turn that is running; the agent takes it at its next step and the turn continues. With nothing running, a steer starts a turn.
• An inject stages context without opening a turn: the agent stays idle, and the context goes with a later request.
• A cancel stops the turn that is running. Every cancel carries a cause (user for a person's stop, parent for a parent agent, hook with a reason string, disposed when the agent is torn down), and the first cause to arrive decides. A plain cancel also clears input that is still waiting; a cancel asked to keep the inbox leaves the waiting input for a later wake. With nothing running, a cancel changes nothing.
• Waiting until idle settles when the agent leaves the running state: it resolves at once if nothing is running, and it follows work that replaces the run it was watching.
• Maintenance starts only from true idle. While it runs, new input waits and is taken up after it settles, and the status stays idle. A maintenance run asked for while work is active is refused: agent "<id>" already has active work. Two maintenance runs never overlap.

How these appear in the app is on Prompts, queue and steering; what a stop leaves behind is on Stopping Oda and queued messages.

Status and faults

• An agent's status is one of two: idle or running.
• Behind the status, the driver moves between idle, maintenance and running; maintenance presents as idle, so an idle status can still mean housekeeping is in flight.
• A change is reported only when it happens: the same status is never reported twice in a row, and one completed turn reports a single change to running and a single change back to idle.
• A turn that was stopped or failed still returns the agent to idle.
• Faults are contained. A listener that throws or rejects is logged, and it cannot stop the loop or starve the other listeners. A registration that fails is rolled back, so nothing half-applied stays behind.

Options and live changes

• The route. A request needs a provider and a model. A provider must have a registered adapter when it is used, or the request cannot be served. An agent that reaches a request with no route is refused: agent "<id>" has no provider/model: set AgentOptions.provider and AgentOptions.model or supply both via the agent/request waterfall.
• Effort and cap. reasoningEffort is optional and a whole number of at least 1; maxTokens is an optional cap and must be a positive safe integer.
• Live changes. A running loop accepts a live update to its settings, such as the parallel tool-call cap (maxParallelToolCalls, ten by default, or 1 to run calls one at a time): the update keeps the same loop and the agents already composed, and nothing restarts. A value the loop cannot take is refused, and the previous value stays in force. The declared agent list is not part of this; it is read at startup. What the cap does is on Tools and how they are offered.
• A missing driver. If the runtime has no agent driver loaded, creating an agent is refused: no agent factory registered.

Known limits

• No turn budget. The loop does not stop itself after a set number of turns; it keeps going until the work ends, is stopped, or fails.
• Declared agents are plain. A declared agent has no persona of its own and no setup step. Persona comes from the deployment's prompt assembly, and a setup step is available to agents created in code.
• One default model. A fresh agent resolves from a single process-wide default model unless its session names a selection; see Model selection and defaults.

How agents are kept apart

• Per-agent registrations. Tools and prompt sections registered through one agent exist only for that agent and are removed when it is disposed.
• Down and up. A scope inherits from its ancestors, and the nearest definition wins; a listener for a scope hears the events of that scope and the scopes below it, never those above.
• One-way chains. A scope's parent chain cannot loop; a link that would form a cycle is refused.
• Not a security boundary. A scope keeps registrations tidy and routed. It is a bookkeeping boundary, not a sandbox: it is not a sandbox or an authority boundary.

Questions, answered

What is the difference between a chat and an agent?

A chat is what you see: its history, its name and its place in the sidebar. Under it sit a session, the stored record, and an agent, the live worker that acts on it. This page is about the worker; the record is described on Sessions and the transcript.

What happens when I dispose an agent?

The agent's loop stops, the agent unregisters, the session is removed and the scope unwinds, taking everything registered under the agent with it. Only the holder of the handle can dispose it, and a turn that was running is closed as aborted with disposed as its cause.

Can two agents share the same id or session?

No. A second agent cannot join under an id that is in use (agent "<id>" is already registered), and two declared agents cannot resolve to the same exact session identity (agents "<first>" and "<second>" use duplicate exact session identity "<id>").

Why did an agent fail with no provider or model?

It reached a model request with no route: no provider and model were set for it, and none were supplied while the request was built. The refusal says what to set: agent "<id>" has no provider/model: set AgentOptions.provider and AgentOptions.model or supply both via the agent/request waterfall.

What session id does a declared agent get?

Without sessionId or resumeSessionId, every startup mints a fresh id of the form <id>-session-<uuid>. sessionId pins one identity for the agent instead, and resumeSessionId resumes a stored session by id; the two cannot be combined (sessionId and resumeSessionId are mutually exclusive).

What statuses can an agent be in?

Two: idle and running. Maintenance presents as idle, and a change is reported only when it happens: the same status is never reported twice in a row.

Can settings change while an agent runs?

Yes. A running loop accepts a live update, such as the parallel tool-call cap, and keeps the same loop and the agents already composed. A value it cannot take is refused, and the previous value stays in force. The declared agent list is the exception: it is read at startup.

What is the difference between steering and injecting?

A steer joins the turn that is running and is taken at its next step, so the turn continues. An inject stages context without opening a turn: the agent stays idle, and the context goes with a later request.

What happens if a listener throws?

The failure is logged and contained: it cannot stop the loop or starve the other listeners. A registration that fails is rolled back, so nothing half-applied stays behind.

Does an agent stop on its own after some number of turns?

No. There is no built-in turn budget: the loop keeps going until the work ends, is stopped, or fails.

Do agents share what they register with each other?

No. Tools and prompt sections registered through one agent belong to that agent and are removed with it. Scopes pass definitions down, with the nearest one winning, and events up; a chain cannot loop, and a scope is not a security boundary.