# realm agent `realm agent` drives one run from the command line. It asks a model for the answer to each agent step, runs each `auto` step itself, and waits at each human gate. This page lists its 14 flags, what it prints, and its exit codes. The outputs on this page come from runs of `realm agent` against a local stand-in for the model, which returned answers chosen for the test. Everything on the Realm side is real. For a walk through a first run, see [Run a workflow with `realm agent`](https://realmengine.dev/docs/guides/realm-agent.md). The commands on this page that name a provider use Anthropic and the model `claude-sonnet-5-5`; any model Anthropic lists works. With an OpenAI key, use `--provider openai --model ` ([OpenAI's models](https://developers.openai.com/api/docs/models)). ## Synopsis ```text realm agent --workflow --model [--params ] [--register] [flags] realm agent --run-id --model [flags] ``` Give exactly one of `--workflow` and `--run-id`. With `--workflow` it starts a new run from a file. With `--run-id` it continues a run that exists. Give `--model` too, unless you give `--provider-module`: Realm has no default model. Version 0.45.0 has one (`gpt-4o`, or `claude-sonnet-4-5` for Anthropic). ## Flags ### Which run | Flag | Default | What it does | | ------------------- | ------- | --------------------------------------------------------------------------------------------------------- | | `--workflow ` | None | Starts a new run of the workflow in this folder or file. The workflow does not have to be registered. | | `--run-id ` | None | Continues this run. The run's workflow must be registered. | | `--params ` | `{}` | The new run's parameters. Checked against the workflow's `params_schema`. Cannot be used with `--run-id`. | | `--register` | Off | Also registers the workflow, as `realm workflow register` does, so that the run can be continued later. | ### Which model | Flag | Default | What it does | | -------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--provider ` | `openai` if `OPENAI_API_KEY` is set, else `anthropic` | `openai` or `anthropic`. Another word is refused; version 0.45.0 takes any other word as `anthropic`. | | `--model ` | None. Required, unless `--provider-module` is given. | The model's name, as the provider knows it ([Anthropic's models](https://platform.claude.com/docs/en/models/overview), [OpenAI's models](https://developers.openai.com/api/docs/models)). A name that is empty or holds only spaces counts as missing. Version 0.45.0 has a default: `gpt-4o`, or `claude-sonnet-4-5` for Anthropic. | | `--base-url ` | The provider's own address | Sends requests to another service that speaks the OpenAI chat-completions format. Only with `openai`. | | `--strict-base-url` | Off | States that the service at `--base-url` enforces strict structured output. See [Agent-step controls](https://realmengine.dev/docs/reference/workflow/agent-step-controls.md#structured_output). | | `--provider-module ` | None | Uses your own provider, loaded from this code file. Cannot be combined with the four flags above. | ### How steps are run | Flag | Default | What it does | | ---------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------- | | `--schema-retries ` | `2` | How many times the model is asked again when its answer does not fit the step's schema. `0` turns this off. | | `--llm-timeout ` | `600` | The longest one request to the model may take. A step's own `llm_timeout_seconds` takes precedence. | | `--mint-writer-nonce` | Off | Gives each attempt of a step a fresh identifier, which Realm records with the attempt's trace entries. | | `--project ` | The current folder | The project whose `realm.yaml` applies if the workflow has no project of its own. | | `--extensions-module ` | None | Loads this code file in place of the files named by the workflow's `extensions`. | ## Environment variables | Variable | What it does | | -------------------- | ------------------------------------------------------------------------ | | `OPENAI_API_KEY` | The key for OpenAI, and for a service at `--base-url`. | | `ANTHROPIC_API_KEY` | The key for Anthropic. | | `ANTHROPIC_BASE_URL` | Sends Anthropic requests to another address. Read by Anthropic's client. | One of the two keys must be set, unless `--provider-module` is given. If both are set and `--provider` is not given, OpenAI is used. With either key, `--model` is required. When you name a provider with `--provider`, its own key must be set. A key that is empty or holds only spaces counts as not set, both for choosing the provider and in the messages below. Version 0.45.0 counted it as set: with `OPENAI_API_KEY=` and an Anthropic key, it picked OpenAI. The key and the model are needed even for a workflow in which no step calls a model: `realm agent` checks its flags before it reads the workflow. ## What it prints ```bash realm agent --workflow ./ --register --params '{"ticket":"I was charged twice this month."}' --provider anthropic --model claude-sonnet-5-5 ``` ```text Realm Agent — Reply to a ticket v1 Run ID: 50e31961-baec-4e4e-ae6a-ef0af3754761 → [auto] fetch ✓ → running → [agent] classify Classify the ticket and say how urgent it is. ⏸ Gate: classify | ID: 8fd100bb-116e-44b7-80cf-3ed3eab5ed42 { "category": "billing", "urgent": true, "reason": "The customer was charged twice this month." } Send: realm run respond 50e31961-baec-4e4e-ae6a-ef0af3754761 --gate 8fd100bb-116e-44b7-80cf-3ed3eab5ed42 --choice send Discard: realm run respond 50e31961-baec-4e4e-ae6a-ef0af3754761 --gate 8fd100bb-116e-44b7-80cf-3ed3eab5ed42 --choice discard Waiting for approval... → [auto] file ✓ → completed Run complete: 50e31961-baec-4e4e-ae6a-ef0af3754761 Result (classify): { "category": "billing", "urgent": true, "reason": "The customer was charged twice this month." } ``` | Line | Printed when | Holds | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Realm Agent — v` | At the start | The workflow. | | `Run ID` | At the start | The run, new or continued. | | `→ [agent] ` or `→ [auto] ` | A step starts | The step, and under an agent step its `description`. | | `✓ → ` | A step completes | The run's phase after it. | | `• Step '' cannot run (): ` | An `auto` step cannot run | Printed once per drive; the drive goes on with any agent step that is ready. See below. Added after version 0.46.0. | | `⚠ output rejected (); repairing (attempt n/m)` | The model's answer was refused and it is asked again | The error code, and which of the `--schema-retries` attempts this is. | | `⏸ Gate: \| ID: ` | The run reaches a human gate | The answer waiting for approval, then one `realm run respond` command for each choice. | | `⚠ gate '' on '' had expired before this call — this agent call first carried out its declared …` | The run reaches a question whose time is already up and whose `on_expiry` the engine carries out | The expiry it carried out, in place of the gate's lines: such a question is not shown, since an answer could no longer be recorded. Added after version 0.46.0. | | `Run complete: ` | The run completes | The run. | | `Result ()` | The run completes | The last agent step's answer, through that step's `display` template if it has one, otherwise as JSON. When another program gave it: `Result () — given by , not by this drive`. | | `✗ Step '' …`, `✗ The drive stops: …`, `⚠ Step '' is blocked …` | The run cannot go on | The reason: a step that failed, a step refused before its claim with nothing else to run, or a handler or adapter this program has not registered. See [When it stops](#when-it-stops). | At a gate, `realm agent` waits until the gate is answered, by `realm run respond` from another terminal or by any other means, and then carries on: it runs the guards and `auto` steps the answer leaves owed (each `auto` step as `→ [auto] `), then the next agent step. Running the owed steps after the answer was added after version 0.46.0. An `auto` step that cannot run is named once per drive with the check that refused it: `• Step '' cannot run (): ` for an invalid `trust`, a failed precondition or an input its schema rejects (the refusal names the field and what it must be, or the property the schema does not allow), and `• Step '' cannot run here (capability): ` for a handler or adapter this program has not registered — judged with this program's own extensions. The drive goes on with any agent step that is ready. A step refused before its claim is never submitted. A step whose handler or adapter is missing is attempted once by each drive (`→ [auto] `), and each attempt adds an evidence entry and rewrites the step's entry in the run's `capability_blocks`: the first drive of a run attempts it as soon as it is owed, before any agent step that is ready; a later drive, once the run's record holds the block, attempts it only when it has nothing else to run; see [When it stops](#when-it-stops). When such a step comes right after an agent step, the agent step's call reaches it first: the agent step is said as completed (`✓ → running`), the step is named once, the drive goes on with any agent step that is ready, and its stop names that step and what it needs — never the agent step. This paragraph was added after version 0.46.0. If the project's `realm.yaml` sets up Slack, the gate is also posted there. See [Answer gates from Slack](https://realmengine.dev/docs/guides/slack-gates.md). An agent step that is refused before its claim — a failed precondition, or an invalid `trust` in a registered copy the loader never checked — is named the same way, `• Step 'ask' cannot run (precondition): Precondition failed for step 'ask'. …`, and is never sent to the model; when nothing else can run the drive stops on it (see [When it stops](#when-it-stops)). A `blocked` reply is never followed by `✓`: an `auto` step another process took between the drive's read and the engine's is said as taken (`• Step '' was taken by …; not run here.`), and an agent step as below; when another process opened a gate or ended the run in that moment, the drive goes on as it does at any gate or end (it waits at the gate, or prints `Run ended in phase: `); any other `blocked` reply prints its own reason (`✗ Precondition failed for step 'ask'.`) and stops the drive with exit code 1. Added after version 0.46.0, which asks the model for such a step again and again, printing `✓ → running` each time. When another process's answer to an agent step reaches the engine before the drive's own, the drive never prints `✓` for it: the line says the drive's answer was not recorded — `• Step '' was taken by at