workflow.md

title: Workflows maturity: stable description: Group agent calls into a named workflow, propagate parent_trace_id, and bind cost to a logical unit instead of a single session.

Workflows

A workflow is one agent you run. In the dashboard it shows up under Workflows in the left sidebar. Each workflow has its own budget and its own list of API keys.

What you see in the dashboard

The Workflows page lists every workflow you've created. Each row shows:

• The workflow's name (you picked this when you created it)
• Whether it's Active, Paused, or Killed
• Total spend for the current billing period
• How many API keys are bound to it
• When it last saw traffic

Click a workflow to open its detail page. The detail page has six tabs:

Tab	What it shows
Overview	Name, status (Active / Paused / Killed), current spend vs. the installed budget cap, applied policies, and the Pause / Resume / Kill / Delete controls. This is where you change the budget cap.
Policies	The policies scoped to this workflow. Rate limit, budget limit, and tool block entries — same primitives as the org-level Policies page, filtered to this workflow.
Executions	Every gate call your agent made — allowed, blocked, rate-limited. The raw list the gate uses to decide what your agent can do.
Traces	Hierarchical view of one agent run — each LLM call, each tool call, with timing and cost.
API keys	The API keys bound to this workflow. Use Generate API key in the top-right to mint one; the raw key value is shown only once at creation.
Coverage	MCP servers and tools observed on this workflow in the last 30 days, with the "discovered but not registered" panel for un-enrolled servers.

How to create one

1. In the dashboard sidebar, click Workflows.
2. Click New workflow in the top right.
3. Give it a name (e.g. "production-support-bot"). The name shows up everywhere — keep it short. Names are 1–255 characters: letters, digits, space, and _ . , - & ( ) are allowed.
4. Optionally set an External ID — alphanumeric with - and _, up to 64 characters — for integrations that need to look up the workflow from your own systems (e.g. a GitHub repo name or a customer account id).
5. Click Create. The budget cap is configured on the Overview tab after creation via a budget-limit policy or the installed budget control — there is no starting budget on the dialog itself.

Workflows · New workflow

Workflows · Create dialog

Workflows · Workflow detail

You'll land on the new workflow's detail page. From there:

• Mint an API key under the API keys tab. The key value (nr_live_...) is shown once — copy it into your secret manager immediately.
• Point your SDK at it: nullrun.init(api_key=...) picks up the key; the workflow binding happens server-side.

How to control one

Each workflow has three states that you control from the dashboard or via the API: Active, Paused, and Killed. Both Pause and Kill reach your running SDK over a WebSocket push; the agent doesn't have to wait for the next call to learn. See Control plane for the full contract, the exceptions each state raises, and how the signal travels over the WebSocket.

The workflow's settings

Five things you control per workflow:

• Budget — the per-period cap in cents. Set this first. The dashboard shows a horizontal bar of how much you've spent vs. the cap.
• Enforcement mode — Hard (block on budget exceeded) or Soft (allow over-budget up to an overdraft cap, when there's an active chain). Full configuration in Policies → BudgetLimit extra fields.
• Human approvals — turn on to require operator approval for dangerous tools (payments, deletes, external API mutations). Available on Growth+ plans.
• Tool block list — the patterns the agent must not call. See Tool policies.
• Trace retention — how long to keep detailed per-call traces (default 30 days, plan-gated up to 90).

Chain context

A chain is a logical grouping across multiple @protect calls inside one user request, declared via with chain(...). Chains are auto-registered on the first /gate call: the chain transitions from null → ACTIVE atomically.

When chains end

A chain dies on the first of:

• op="end" is reached in the context manager
• 5 minutes of /gate inactivity (idle TTL)
• max_chain_duration_seconds exceeded (default 3600)

For long streams, send a POST /heartbeat every 30 seconds — see Heartbeat → how-to.

Why chains exist

Chains exist primarily to enable soft-mode budget gating: with an active chain, the gate allows the agent to run past its budget up to an overdraft cap (max_overdraft_cents or max_overdraft_percent, whichever is lower). Full soft-mode contract in Policies → BudgetLimit extra fields.

How the workflow ends

A workflow doesn't have an explicit "end" state in the sense of a final commit. Instead:

• The workflow stays Active across many agent runs. Each run is a sequence of @protect calls.
• A run is logically ended when the agent's loop returns or throws.
• A workflow is paused or killed when you decide, or when plan limits (max workflows per plan) cause auto-pause.

There is no "clean up the workflow when done" step. Active workflows keep their policy, budget, and key bindings. Re-run the agent next week and the same workflow handles it.

See also

• Budgets — the budget cap and how rollover works
• Policies — what rules attach to a workflow
• Control plane — how Kill / Pause reach your agent
• API keys — how to mint a key bound to this workflow