The Ralph tool

The ralph tool runs a loop of fresh agent rounds toward one objective, until a round reports the work done or the rounds run out. This page is the developer reference for the tool in DataMind Oda: when Oda may call it, what a call carries, how rounds and reports work, and the limits that apply.

What the tool is

• One objective, fresh rounds. The loop works toward one immutable objective. Each round starts one fresh child agent, and a new round starts while the last report says there is more to do.
• A fixed loop. The call supplies data only: the loop itself, the route to the child agents, the shape of the round reports and the handoff checks are fixed by the deployment, and a call cannot change them.
• A card in the chat. A call appears as a card titled ralph, showing the call's objective, and it holds the turn until the whole loop settles (Tool calls in the chat).
• One result. The chat sees the call and one closing result, not the rounds' inner reports.
• One Activity row. In the app, a loop folds into a single Ralph row with its rounds as members (Background runs and jobs).

When Oda may use it

• Only on an explicit ask. Oda reaches for the tool only when the person explicitly asks for a Ralph loop or fresh-agent iteration. The model's own guidance reads: Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution.
• What it is not for. For ordinary long-running objectives Oda uses goals, and the Relentless preset keeps working until the task is done or it needs a decision (Presets); for bounded delegation and fan-out it uses plain helper calls or the workflow tool.
• The switch. The capability sits behind the Ralph autonomous loop feature. Every advanced feature stays off until you turn it on in Settings > Developer > Advanced features (Advanced features), and the feature's risk is described in the Advanced features catalog.

The call's fields

The call is checked before any round starts. It fails its checks, and starts nothing, when:

• the objective is empty: Ralph objective must be a non-empty string;
• the round cap is not a positive whole number: Ralph maxRounds must be a positive safe integer;
• the round cap passes the deployment ceiling: Ralph maxRounds <value> exceeds the deployment ceiling <ceiling>;
• there is no chat behind the call: Ralph tool requires a calling agent (exec.agent was undefined).

The configured child-agent provider is checked the same way. It must be registered (Ralph subagent provider "<name>" is not registered), support structured output (Ralph subagent provider "<name>" does not support structured output) and start fresh rather than inherit the parent context (Ralph subagent provider "<name>" inherits parent context; Ralph requires a fresh provider).

Rounds and reports

• A report ends each round. Every fresh child closes its round with a structured report whose state is continue, complete or blocked.
• What each state needs. A continue report lists the next steps and carries no blocker. A complete report carries evidence, no next steps and no blocker. A blocked report carries a concrete blocker.
• A report that does not fit ends the run. A missing or malformed report, or one past the handoff cap, ends the run, and the call comes back as Ralph workflow failed: followed by the failure.
• Only the report crosses. Each round starts from the objective and the bounded handoff alone: no conversation seed and no parent history reach the child, and it works in the calling chat's folder. The workspace is the only other memory the rounds share.
• A failed round ends the run. When a child fails before producing a structured report, the loop stops and the result reads Ralph round <n> child failed before producing a structured report., followed by Last successful handoff: and the last report, or No previous handoff was available. when there is none.

How a loop ends

• The worker reports. The loop ends when a round reports complete or blocked, or when the round limit is reached. Completion and blockers are the worker's own reports, not an independent check.
• Three endings. A loop settles as complete, blocked or budget-limited, and the result carries the last bounded report and how many rounds ran.

In these lines <n> reads as the number of rounds, such as 1 round or 2 rounds.

• Stopped or failed. Stopping the turn that runs the loop cancels it, and the call comes back as Ralph workflow was cancelled; a loop that fails comes back as Ralph workflow failed: followed by the failure.

The limits that apply

• Completion is self-declared. No independent evaluator checks a loop: Completion and blockers are worker reports, not independent evaluation.
• Only the rounds bound effort. No elapsed-time deadline stops a loop; the round count is what bounds its total work.
• Foreground only. A loop never becomes a background job: it holds the turn, and there is no job id, no background start and no resume for it.
• One round, one child. A round starts a single fresh child; it does not fan out inside the round.
• An ordinary child failure is terminal. Where a workflow script carries on past a failed helper, a Ralph run does not: a child that fails before its report ends the run.

The settings behind the tool

• The child-agent route. Which provider serves the fresh rounds is a deployment setting; a call cannot override it.
• The round cap. 256 rounds is the default and the ceiling for one run, so a call can ask for fewer rounds but not more.
• The caps on text. Round reports and the final result are each capped at 16,384 characters by default: a report past the handoff cap ends the run, and a longer result is cut with a … [truncated] notice.

Questions, answered

How do I get Oda to run a Ralph loop?

Ask for it in your own words, as a Ralph loop or fresh-agent iteration; Oda reaches for the tool only on that explicit ask. The capability also sits behind an advanced feature: the Ralph autonomous loop stays off until you turn it on in Settings > Developer > Advanced features (Advanced features catalog). The call then shows as a card titled ralph.

How many rounds can a loop run?

maxRounds is optional, and 256 rounds is the default and the ceiling for one run, so a call can set a smaller cap but nothing above it. A cap over the ceiling is refused: Ralph maxRounds <value> exceeds the deployment ceiling <ceiling>.

Why was my Ralph call refused before it started?

The checks run before any round starts, and each refusal names its reason: an empty objective, a round cap that is not a positive whole number or that passes the deployment ceiling, a child-agent provider that is not registered, does not support structured output or inherits the parent context, or a call with no chat behind it. The field and provider checks above quote each message.

Do the rounds see my conversation?

No. Every round starts a fresh child with no conversation seed and no parent history; only the round's bounded report crosses to the next round, and the workspace is the only other memory the rounds share.

What does a round's report contain?

A state, continue, complete or blocked, with the fields that state requires: next steps for a continuing round, evidence for a completed one, and a concrete blocker for a blocked one. A report that does not fit its state ends the run.

What happens if a round fails?

The loop stops. The result reads Ralph round <n> child failed before producing a structured report. and carries the last successful handoff, or No previous handoff was available. when there is none. An ordinary child failure is terminal for the run.

Can a Ralph loop run in the background?

No. A Ralph loop is foreground work: it holds the turn until the whole loop settles, and it has no job id, no background start and no resume. The workflow tool is the tool whose runs can start as background jobs.

What does the budget-limited ending mean?

The loop reached its round limit while the last report still had work remaining. The call renders Ralph reached its <n> limit; the worker reported work remaining., and the result carries the last bounded report and the rounds that ran.

Can I stop a running Ralph loop?

Yes. A loop holds the turn it runs in, so stopping that turn cancels it (Stopping Oda and queued messages); the call comes back as Ralph workflow was cancelled. In Activity, its Ralph row offers Stop like other running work (Activity rows and actions).