LLM agent steps
Let Claude do an agent step's work — a structured answer checked against your schema, tool calls through your connectors, irreversible actions only proposed for a person to sign, every call recorded with its cost, and spend bounded by budgets.
An agent step is scored by deterministic rules unless it declares an llm block. With one,
the run asks Claude to do the step: it reads the step, the instructions you wrote and the
case (the run state), may call the connector tools you bound to it, and answers with a JSON
object that must match the output schema you declared. The answer becomes run state for the
steps and decisions after it.
The product rule does not change: a model proposes, a person disposes. A model never signs a gate, and never sends an irreversible action on its own — it can only propose one, and the step then waits for a person's signature.
Declare the block
On the canvas, select an agent step and press Use Claude in the inspector. Pick the model,
write the system prompt and the instructions, and edit the output schema (the editor parses as
you type and keeps the last valid schema until your edit parses). In a minctrl.process/v1
file or a canvas graph the block sits on an agent node:
{
"id": "classify",
"kind": "agent",
"label": "Classify the ticket",
"agent": "triage",
"tools": ["order-lookup", "payment-rails"],
"tier": "low",
"llm": {
"model": "claude-sonnet-5-5",
"system": "You triage customer support tickets for Acme.",
"instructions": "Decide whether the ticket asks for a refund. Look the order up first.",
"output_schema": {
"type": "object",
"properties": {
"category": { "type": "string", "enum": ["refund", "question"] },
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
"summary": { "type": "string" }
},
"required": ["category", "confidence", "summary"]
},
"tools": ["order-lookup", "payment-rails"],
"route_field": "category",
"max_tokens": 4000,
"max_tool_rounds": 5
}
}| Key | Meaning |
|---|---|
model | claude-sonnet-5-5 (the default), claude-opus-5-5 or claude-haiku-5-5. Left out: the company's default model (Settings → AI models). |
system, instructions | Required text, at most 20,000 characters each. |
output_schema | A JSON Schema whose type is object with declared properties. The answer is constrained to it by the API and checked against the full schema by Minctrl (constraints the API does not enforce, such as minimum or maxLength, are checked here). |
tools | Connector tool ids the model may call (at most 10). |
route_field | A property of the output: its value becomes decision, which the next exclusive gateway routes on (refund / question above). |
max_tokens | Output tokens per call, 1–64,000 (default 16,000). |
max_tool_rounds | Rounds of tool calls before the step fails, 1–10 (default 5). |
temperature | Not supported: the current Claude models sample with their defaults and the API refuses the setting. A block that sets it is refused at save. |
A broken block is refused at save (422 naming the step), like a broken gate form. The
block travels with BPMN export/import (a minctrl:llm attribute on the serviceTask).
What the run does with the answer
- The answer is written to run state as
llm.<step_id>(the object) andllm.<step_id>.<field>(each field) — a connector'sbody_mapor a later step reads it. - A numeric
confidencefield in the answer is the confidence the resolver reads: a low one parks the step for a person, exactly as a scored step does. - An answer that does not match the schema is sent back once with the validation error; a second invalid answer fails the step ("the model's output did not match the output schema twice — …").
Tools: reversible run, irreversible are proposed
The model sees each bound tool with the catalog action's input schema when the connector came from the catalog. When it calls one:
- a reversible action runs through the run's connectors — the same rules as a declared
tool: shadowed when the run is shadowed or the tool is not bound live, credentials resolved
per connector, SSRF guard. Its result goes back to the model. A tool bound live counts as
reversible only when its connector says so —
reversible: trueon the connector, or a catalog action declared reversible; unknown is not reversible; - an irreversible action (a known irreversible tool id, a catalog action declared irreversible — even when an owner bound it live — any tool of a step marked irreversible, or a live tool whose reversibility is not declared) is never performed by the model. It is recorded as a proposal, the model is told it was not performed, and when the model has answered, the step parks with "the model proposes an irreversible action (…) — a person must sign it".
A person signs the parked step from the sign-off queue, the phone screen or an embed widget —
each card shows what the model proposes (the tool and a summary of its arguments), and
approving it needs the gate id typed, whether the tool is live or shadowed. Slack and Teams
show the proposal too but offer no buttons for it ("Open in Minctrl"). The sign tier counts the
step's llm.tools and the proposals: a proposed tool bound live makes it a high-tier signature
(gate.approve.high_tier). On approve, the
proposed action runs through the connectors with the model's input (and is shadowed exactly as
any irreversible tool is, until an owner binds it live). On deny, nothing runs and the step
stays parked. The model is not asked again either way.
Every call is recorded
Each model call is in the run trace (model, tokens, cost, latency, stop reason, prompt hash,
output hash) and in the audit chain as an llm_call entry with the same fields — hashes,
never text. The Runs page shows the tokens and cost on the step's row and the answer, the
proposals and each call when you expand it.
The full prompt and output text of a call is kept with its usage record (never in the
trace or the audit chain) while Keep the full prompt and output text is on — the same switch
as Store model text in Settings → Compliance, on by
default — for the retention you set (1–3650 days; older text is cleared). Turning it off clears
the text already kept. In PHI mode text is never kept and the switch cannot be turned on
(409). Turning the switch from this page also needs settings.governance, as on the Compliance page. The step's structured answer is part of the run, like any step result.
A resume never re-calls the model. The answer is part of the run's replay memo: a step that answered and parked (a proposal, a low confidence) reuses that answer when the run is signed and driven again.
Spend is bounded
Settings → AI models (the llm.manage permission — owners and admins by default, or a custom role; every member reads it) sets:
- a monthly budget in USD for the company (default $50), and
- a per-run cap in USD (default $2).
Both are checked before every call. When one is reached the step fails with
"LLM budget reached: …" — there is no fallback to the rules. The monthly budget is not read
once per drive: each call first reserves its estimate (max_tokens at the model's output
price) in the database, atomically and only while budget remains, and settles to its real cost
after — so runs at the same moment together overrun the budget by at most one call. A blank
limit means the platform default, never "no limit": the monthly budget falls back to
MINCTRL_LLM_MONTHLY_BUDGET_USD ($50 unless the operator set another) and the per-run cap to
MINCTRL_LLM_RUN_CAP_USD ($5 unless set) — a company's and a run's spend are always bounded.
Settings → AI models shows the default in force next to each blank field. Every change is an llm_settings_changed audit entry with each value from → to.
Prices come from the cost table (Sonnet 5.5 $2 / $10, Opus 5.5 $4 / $20, Haiku 5.5 $0.10 /
$0.50 per million input / output tokens; cache reads and writes priced separately).
Keys
A step calls Claude with the company's own Anthropic key when one is set
(Settings → AI models → Anthropic API key, write-only: stored sealed, shown only by its last
four characters), otherwise with the server's ANTHROPIC_API_KEY. A company key that cannot
be read (for example after the secrets key was rotated) fails the step saying so — it is never
replaced by the platform key. With no key at all, an LLM step fails with "no Anthropic API
key".
When a step fails
A failed LLM step stops the run with status failed, the step's sentence in
trace.error and a code in trace.error_code: llm_budget, llm_key, llm_schema,
llm_tool_rounds, llm_rate_limited, llm_unavailable (429 / 5xx after the retries with
backoff), llm_auth, llm_refusal (the model declined), llm_max_tokens. Calls made before
the failure are recorded and billed. The Temporal runtime does not run LLM steps in this
release: such a step fails there with "this runtime has no model client".
Test suites
In a test suite an LLM step answers from its fixture's
llm_output (and proposals) — no call, nothing billed, and the same path every time:
{ "fixtures": { "classify": { "llm_output": { "category": "refund", "confidence": 0.95, "summary": "x" } } } }A case with no recorded output for an LLM step fails saying so; Record runs the case
live once (connectors still shadowed; the calls are audited and billed against the budgets)
and stores each answer as llm_output. An output assertion reads $.llm_output.<field>.
Operating it
ANTHROPIC_API_KEY— the platform key.ANTHROPIC_BASE_URLpoints the client somewhere else (the tests and the local E2E stack point it at a fake server).MINCTRL_LLM_MAX_RETRIES(default 3) andMINCTRL_LLM_TIMEOUT(seconds, default 120).scripts/llm-live-smoke.pywithMINCTRL_LIVE_LLM=1is the one check that calls the real API (a few cents, capped at $0.50); it printsSKIPPEDotherwise.
Testing processes
Write test cases for a process — inputs, the answer each gate gets, the path and outcome the run must take — run them against any version without touching a live system, compare two versions on the same suite, and make publishing require a green suite.
Document extraction
Attach PDFs, images and emails to a run, let Claude fill a schema you declare — every field with a confidence and the page it was read from — and have a person review the uncertain fields at a gate, side by side with the document, before any step uses them.