ELI5: The difference between Braintrust's 'agent' and 'scanner' modes

You're overcomplicating it. An agent does a specific task from start to finish. A scanner checks a bunch of things and reports back.

For your Salesforce reports, use an agent to automatically generate and email a weekly summary. Use a scanner to check 50 reports daily for missing data fields and flag the broken ones.

Scanner is for bulk checks. Agent is for a defined workflow. Pick based on whether you have one job or many items to review.

Oh that Salesforce example really helps, thank you! So an agent is like a single, automated procedure, and a scanner is more like a quality control pass.

I guess a scanner is basically asking "does this thing meet a condition?" across a list, while an agent is saying "go do this full task."

Follow-up question - can an agent *use* a scanner as one of its steps? Like, if my automated workflow needed to check those 50 reports first before doing something else?

Exactly, you've nailed the core distinction. And great follow-up question.

Yes, an agent can absolutely use a scanner as one of its steps. That's a very common pattern for building reliable workflows. Think of it as the agent orchestrating the scanner to do the "checking" part.

In your example, you could have an agent whose workflow is:
1. Trigger on Monday morning.
2. Run the scanner to check all 50 reports for completeness.
3. If the scanner flags any reports with missing fields, the agent branches to notify the report owners.
4. If all scans pass, the agent proceeds to compile and send the weekly summary.

The scanner becomes a conditional gate within the agent's larger task. It's a powerful way to combine them.

Yes, exactly. That's the main use case for scanners.

In practice, you'll define your scanner separately. Then your agent references it, waits for the result, and uses its output as a condition.

Your workflow would look like this in the agent config:
```yaml
steps:
- name: scan_reports
scanner: salesforce_report_completeness
args:
report_ids: ${report_list}
- name: evaluate_scan
if: ${scan_reports.has_failures}
action: send_alert
- name: generate_summary
if: ${not scan_reports.has_failures}
action: compile_and_email
```
The scanner runs, returns a structured result, and the agent logic branches on it.

That YAML example really clarifies the data flow. It's exactly the plumbing you need.

One cost thing to watch: if `report_list` is huge, your scanner step could get expensive. It's tempting to scan everything, but you should ask if you actually need to check all 50 reports every time, or just the ones changed since last scan. That conditional logic *before* the scanner call can save a lot of cycles.

Think of it like a carpenter's tools. An agent is your power drill - you use it to run a specific procedure from start to finish, like building a shelf. A scanner is your level - you use it to check many things against a standard, like seeing if all your shelves are straight.

For Salesforce reports:
* Use an agent to automatically generate and send the monthly commission report.
* Use a scanner to verify that every open opportunity in the pipeline has a next step date populated.

The real difference is intent: doing one thing versus checking many things.

Not wrong, but that "specific task" line is too fuzzy. An agent's cost profile is linear - it's one task, once. A scanner's is multiplicative.

You check 50 reports today, fine. If that list grows to 5000 next month, your scanner cost scales with it. An agent generating one weekly report doesn't. That's the real picker: is the workload list-based and variable? Scanner. Is it a fixed procedure? Agent.

That's a crucial, concrete point about cost scaling. I've seen teams get burned by ignoring it during design. A scanner on a growing inventory is a direct cost line item that needs monitoring.

Your "list-based and variable" versus "fixed procedure" is the right mental model, but I'd push back slightly on the "linear" cost of an agent. An agent's cost can spike too if its logic gets bloated or if it's triggered too frequently. I had a case where an agent's "one task" involved calling three external APIs and parsing a massive XML payload, and it ran every hour. The bill was not linear with the single execution count.

So the real picker is: does the *unit of work* scale with the size of an inventory list? If yes, scanner. If no, agent. But you still need to sanity-check the agent's internal complexity and trigger schedule.

You've got the right starting hunch! The other replies have nailed the big picture, but I can give you a solid, practical filter to decide in the moment.

Think of it as the difference between a **doer** and a **reviewer**.

An agent is your doer. It follows a recipe. "Go make me a sandwich" is an agent task - it knows the steps: get bread, add filling, wrap it up. In Salesforce, that's "generate and distribute the Q3 sales report."

A scanner is your reviewer. It has a checklist. "Look at all these sandwiches and tell me which ones have pickles" is a scanner task. In Salesforce, that's "review every lead created this week and flag the ones missing a phone number."

Your clue is in the question you ask the tool. Are you saying "go perform this process"? That's an agent. Are you saying "go examine these items and tell me what you find"? That's a scanner.

The core distinction is about the *shape* of the work, not complexity. An agent executes a linear sequence of steps to complete a single objective. A scanner applies a single evaluation across a set of items.

For your Salesforce reports, that means:
- An **agent** is for "generate the weekly forecast report." It has fixed steps: query data, format, email.
- A **scanner** is for "find all reports missing a close date." It takes a list and returns which items passed/failed.

The key question: does the work repeat per item in a list? If yes, it's likely a scanner task. If the work is a one-time procedure, it's an agent. The cost scaling other users mentioned stems directly from this design.

Love the tool analogy, it's a great way to picture the intent. I'd just add that the level (scanner) can sometimes be the final step in using the drill (agent). You might build the shelf with the drill, then use the level to verify your work, and if it's off, the drill goes back for adjustments. That's the workflow pattern earlier in the thread.

So your scanner checking "every open opportunity" could be the quality gate *within* an agent whose job is "clean up the sales pipeline every Friday." The agent runs the scanner, then branches to notify owners of failing items. The intent is still distinct, but they're rarely used in total isolation.

The replies have given you excellent analogies and cost models. The practical filter for your Salesforce work is this: count your nouns.

If your instructions have one singular, concrete output noun, you're describing an agent task. "Generate the report." "Update that record." "Send this email." One target.

If your instructions have a plural noun or a collective noun as the target, you're likely describing a scanner. "Check all reports." "Validate these leads." "Review every opportunity in the pipeline." The work repeats per item in that list.

Your clue is in the question you ask yourself. "What do I want done?" points to an agent. "Which items need something?" points to a scanner.

That noun trick is slick, I'm stealing that for our internal docs.

But be careful, the line blurs with batching. I built an "agent" last week that *updates a single configuration*, except that config is a list of 200 servers. The task is singular ("apply config"), but under the hood it loops. It's still an agent because the procedure is fixed, the list is a parameter, not the trigger.

So maybe the rule is: does the list define the *existence* of the job, or is it just an input? Scanner for the former, agent for the latter.

You've hit on the subtle but important distinction between the trigger and the input. The "list as a parameter" versus "list as the job" is a great way to frame it.

That's why I prefer looking at the *initial request*. If the request is "apply this patch to the server cluster," it's an agent. The list is just a detail. If the request is "find all servers missing the patch," it's a scanner. The list's existence is the entire point.

Your example shows why the "singular vs. plural noun" shortcut can break. It's a helpful starting cue, not a hard rule.