Minctrl Docs
Guides

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
  }
}
KeyMeaning
modelclaude-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, instructionsRequired text, at most 20,000 characters each.
output_schemaA 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).
toolsConnector tool ids the model may call (at most 10).
route_fieldA property of the output: its value becomes decision, which the next exclusive gateway routes on (refund / question above).
max_tokensOutput tokens per call, 1–64,000 (default 16,000).
max_tool_roundsRounds of tool calls before the step fails, 1–10 (default 5).
temperatureNot 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) and llm.<step_id>.<field> (each field) — a connector's body_map or a later step reads it.
  • A numeric confidence field 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: true on 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_URL points the client somewhere else (the tests and the local E2E stack point it at a fake server).
  • MINCTRL_LLM_MAX_RETRIES (default 3) and MINCTRL_LLM_TIMEOUT (seconds, default 120).
  • scripts/llm-live-smoke.py with MINCTRL_LIVE_LLM=1 is the one check that calls the real API (a few cents, capped at $0.50); it prints SKIPPED otherwise.

On this page