# Processing rules

Tell Brizz which model call compacts the history, which steps are background jobs, which user messages your app wrote, which tool runs other tools, which tool starts another agent, and which tool loads other tools — so conversations read the way your agent really works.

Processing rules shape how a service's sessions read. They live on the service's **Session configuration** tab, under **Processing rules**, and any **Admin** of the service can edit them.

There are six kinds of rule. Almost every rule is filled the same way, in two parts:

1. **Which spans** — the conditions that pick the spans (steps) the rule looks at.
2. **What to do with them** — what Brizz does with the spans it picked. This is the only part that differs between the kinds.

An **App messages** rule can pick its messages by their opening words instead of by spans; see [App messages](#app-messages).

:::info
**Rules apply to new data.** A compaction, background job, agents-started-by-a-tool or tools-that-load-other-tools rule, and an app messages rule that picks spans, is checked as each span arrives, and a saved change reaches arriving spans within about 10 minutes. A tools-that-run-other-tools rule, and an app messages rule that picks by opening words, is applied when a session's conversation is built, so an older session rebuilt later shows it too. Sessions captured before you saved a rule keep the shape they had until they are rebuilt, and removing a rule doesn't change sessions it already shaped; runs a removed agents rule grouped stay grouped.
:::

Under each rule, a preview shows what it picks in the service's last hour, and what it would do there. An app messages rule that picks by opening words has no preview: the preview reads spans, not message words. On a busy service the preview reads only the newest 1,000 spans for the rule and says how far back that reached. It matches spans as they were stored, so a rule on a value that masking hid, or that was trimmed from a large span, can preview as no match and still match as spans arrive.

## 1. Which spans

A rule starts with **When all / any of these match**, then one or more conditions:

- **all** — a span is picked only when every condition matches it.
- **any** — a span is picked when at least one condition matches it.

Each condition is a key, then how to compare it, then a value.

**The key** is something every span has, or one of the attributes your service sends:

| Key | What it reads |
|---|---|
| Span name | The step's name, such as `summarize_history`. |
| Kind, Status | Picked from a fixed list (`SERVER`, `CLIENT`, … / `OK`, `ERROR`, `UNSET`). |
| Scope | The library that recorded the span. |
| Your attributes | The attributes you set yourself, such as `user_role`. |
| Instrumentation | The attributes your SDK or framework sets, such as `tool.name` or `output.value`. |

The attribute lists show only the keys your service has actually sent. A key you haven't sent yet doesn't appear.

**Reading inside a value.** When an attribute holds JSON, a **+ JSON key** link appears next to it. Each step goes one level in, and offers the keys found at that level of your data, so `request_context › agent › name` reads the `name` inside `agent`. The link goes away once you reach a plain value, and never appears for an attribute whose values aren't JSON.

**How to compare** is one of:

- **equals** — the value is exactly what you typed.
- **contains** — the value includes what you typed anywhere.
- **matches regex** — the value matches a regular expression, such as `^summarize`. An invalid pattern is marked **Not a valid pattern** and can't be saved.

## 2. What to do with them

### Compaction

Picks the **step** your agent summarizes its own history in when the conversation grows long, such as a span named `summarize_history`. The model calls inside that step are your app's instruction and the summary, not turns your user typed, so Brizz shows them as one compaction. Model calls outside it are left alone. There's nothing more to fill in.

### Background jobs

Picks a **step** your app runs beside the conversation, such as a guardrail check on the user's message or a step that picks a model. The model calls inside it are your app's own questions, not turns of the conversation, so Brizz runs the step and every span under it as one background job, kept out of the conversation. Pick the step itself, for example Span name · equals · `check_guardrails`. There's nothing more to fill in. The preview counts the model calls inside each step it picks; a step with none still runs as a job, but no model call leaves the conversation.

### App messages

Picks the user messages your app wrote, such as a deploy notice or a mode reminder sent as the user, so they read as your app's messages and not as something the person asked. **Which messages** picks them one of two ways:

- **Text starts with** — every user message whose words start with what you typed, for example `[deploy]`. The match is case-sensitive, and the text is saved exactly as typed: a space before or after the words is part of what it matches.
- **Span they ran on** — every user message on or under the spans the conditions pick, for example Span name · equals · `cron_trigger`. The preview lists the spans it picks; it doesn't check that a user message sits under them.

### Tools that run other tools

For an agent that runs its tools through one shared tool, for example `run_tool(tool="search", input={…})`. Without a rule, every call shows as the shared tool; with one, Brizz shows and counts the tool that actually ran.

- **Which spans** reads the tool call itself: **Tool name** or its **Arguments**. For example, Tool name · equals · `run_tool`.
- **Tool that ran** is where its arguments name the real tool: **Arguments › `tool`**.

### Agents started by a tool

For a tool that starts another agent as a separate run, which isn't linked to the call that started it. Brizz uses one shared id to group the started agent's steps under the tool call.

- **Which spans** picks the tool's span, for example Span name · equals · `run_agent`.
- **Started agent's id** is where the tool's span records the id of the run it started, for example **output.value › `run_id`**.
- **That agent's spans carry it in** is where the started agent's own steps record the same id, for example **metadata › `run_id`**.

### Tools that load other tools

For an agent that looks a tool up before running it through a shared tool, for example `search_tools("create a column")` returning the definition of `create_column`, then `run_tool(tool="create_column", …)`. The model read the tool's definition from the lookup's result, not from its own tool list, so without a rule Brizz can't say which version of the definition a call was given. With one, each call run through the shared tool records the version the latest earlier lookup in the same session returned, and the lookup's definitions are added to the service's tool versions.

- **Which spans** picks the lookup tool's span, for example Span name · equals · `search_tools`.
- **Tool definitions** is where its result lists the definitions, each with a `name`, a `description` and an `input_schema` or `parameters`, for example **output.value › `results`**.

A call whose tool no earlier lookup in the session returned records no version. If Brizz doesn't already show the shared tool's calls as the tool that ran, add a **Tools that run other tools** rule for it too.

## Saving

**Save** appears once you change something. It stays disabled until every condition has a value and every value has its key. Removing the last rule and saving clears the service's rules.

## Build rules with your agent

**Build rules with your agent**, beside the **Processing rules** heading, hands the job to your own coding agent (Claude Code, Cursor, Codex, or any agent connected to [Brizz MCP](/docs/integrations/mcp-server/overview.md)). Say what the rules should do, then copy the prompt or open it in your agent. The agent reads the service's rules with `brizz_list_processing_rules` and its attribute keys with `brizz_list_span_attribute_keys`, tries each rule with `brizz_preview_processing_rule` and shows you what it picks, and adds each one with `brizz_add_processing_rule` once you agree; it changes or removes a rule by its id, leaving the others as they are. Saving needs Brizz MCP connected with write access. Close the dialog afterwards and the editor shows the saved rules.

## See also

- [Mute messages](/docs/instrument/mute.md) — leave a step's content out of the conversation from your code.
- [Subagents](/docs/instrument/subagents.md) — how Brizz shows agents that run inside other agents.
- [Services & configuration](/docs/admin/services-and-configuration.md) — the other per-service settings.
- [MCP server tools](/docs/integrations/mcp-server/tools.md#processing-rules) — the processing-rule tools in full.

---

[All Brizz documentation](https://docs.brizz.ai/llms.txt) · [Full documentation (single file)](https://docs.brizz.ai/llms-full.txt)
