Guard agents with inspectors

Inspectors guard an agent while it runs. Each one checks the agent's input, its steps or its final answer, and when it finds a problem it stops the run, runs the agent again, rewrites the content or only logs it. This article explains how inspectors work, the guards that come built in, how to add a guard, a rule or a Python check, how to keep inspectors fast, and how to read what an inspector did in a run's trace and in Dashboard.

How inspectors work

An inspector has three parts: what it checks, how it judges, and what it does when it finds a problem.

What it checks

One inspector can check more than one target.

How it judges

• A guard: a guardrail model from the Marketplace, such as prompt-attack detection or sensitive-information redaction.
• A rule: a sentence in plain words that a judge model checks, such as "The answer must cite a source for every price." The judge answers pass or fail.
• A Python check: a function that returns True when it finds a problem. It runs in a sandbox and has 10 seconds.

What it does when it finds a problem

Order and severity

Inspectors run in the order you list them, and the first one that finds a problem acts. Each inspector also has a Severity: Low, Medium, High or Critical. Severity is a label for sorting and reporting. The action decides what happens.

Built-in guards

aixplain comes with three guards, each with a sensible default. You can change the target and the action after you add one.

aixplain also runs its own checks on every run, which you don't add or remove: it stops runs that loop, enforces the agent's time and credit limits, and pauses for your approval before a tool that needs it.

Add a guard in aixplain Desktop

1. Open the agent in Omni, or ask Omni to build one, and select Configure.
2. Scroll to Inspectors and select Add inspector.
3. Under Ready-made guards, select Add next to the guard you want.
4. Save the agent. A new inspector goes into the draft and takes effect when you save.

The guard appears in the list with what it checks, what it does and its severity. Select ⋯ on an inspector to edit or remove it.

Add a rule inspector

A rule is a check you write in plain words, and a judge model decides whether content breaks it.

1. In Configure, select Add inspector, then Write a rule.
2. Give it a Name, unique in this agent.
3. Under What it checks, choose Input, Steps or Output.
4. Write the Rule: what good content looks like, and when the judge should fail it.
5. Under Judge, keep Default judge or pick a model. A small, fast model is usually enough. See Keep inspectors fast.
6. Choose what happens When it fails: Stops the run, Runs again, Rewrites it or Only logs it. For Runs again, set Retries and what happens After the last retry. For Rewrites it, write a Rewrite rule that says how to fix the content.
7. Choose a Severity, then select Add inspector and save the agent.

Example rules

• "Every bullet ends with a link to its source. Fail the answer if a bullet has no link."
• "The answer must not promise a refund or a delivery date."
• "The answer is in the same language as the request."
• "No step sends an email to an address outside our company."

Write the rule as a correction when the action is Runs again: the judge's feedback goes to the agent's next try as written.

Add a Python inspector

A Python check is a function you write, for rules that code can decide exactly, such as a pattern, a length or a required field. Add it with the Agents SDK. aixplain Desktop shows it as Python · view only: you can keep it or remove it there, and change it in code.

The function must be named evaluator_fn, take the text and return True when it finds a problem. Put any imports inside the function.

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

def evaluator_fn(text: str) -> bool:
    import re
    bullets = [line for line in text.splitlines() if line.strip().startswith("-")]
    return any(not re.search(r"https?://", line) for line in bullets)

source_check = aix.Inspector(
    name="source-for-every-story",
    severity="high",
    targets=["output"],
    action={"type": "rerun", "max_retries": 2, "on_exhaust": "abort"},
    metric=evaluator_fn,
)

agent = aix.Agent(
    name="Weekly Topic News Brief",
    description="Finds this week's news on a topic and sums it up in five linked bullets.",
    instructions="Search the web for this week's news on the topic and return five bullets, each with a source link.",
    inspectors=[source_check],
).save()

• To rewrite instead of block: set action="edit" and add editor=edit_fn, a function named edit_fn that returns the new text.
• To write a rule in code: pass metric={"assetId": JUDGE_ID, "prompt": "..."}, where JUDGE_ID is the ID of the model that judges.
• To add a guard in code: get it with aix.Inspector.get(), for example aix.Inspector.get("aws/detect-prompt-attacks-guardrail/aws").

Define the function in a .py file: aixplain sends its source code, and code typed into an interactive shell can't be read, so the check is skipped. Avoid slow network calls inside it. An inspector added after save() does nothing until you save again. See Inspectors in the docs for every option.

Keep inspectors fast

Every inspector runs on every run, and a rule or a guard is a model call. Too many, or slow ones, make the agent slower and cost more.

• Use a small model to judge. A rule asks a simple pass-or-fail question, so a small, fast model is usually as good as a large one, and quicker and cheaper.
• Prefer Python for exact rules. A pattern or a length check in Python takes milliseconds and uses no credits.
• Check only what you need. An inspector on Steps runs after every step. Use Input or Output when that's enough.
• Put the cheapest checks first. The first inspector that finds a problem acts, so a fast check can save a slow one.
• Keep retries low. Each retry runs the agent again. Two is usually enough.

Test an inspector

Test the agent on a request the inspector should catch. On the Test tab, a run an inspector stopped reads Blocked by and the inspector's name, with its reason, and each run shows what every inspector did: Stopped the run, Ran again, Rewrote or Logged it.

Read what an inspector did

In the run's result

A run an inspector stopped still finishes with the status SUCCESS, and its answer is the inspector's reason. The run's governance record says what happened:

Source says who decided: INSPECTOR for your inspectors, SYSTEM for aixplain's own limits.

In the trace

Each inspector appears in the run's steps under its own name, with the action it took. A guard reports NONE when the content passed and GUARDRAIL_INTERVENED when it flagged it. A stopped run carries the code INSPECTOR_ABORT.

In Dashboard

Open Dashboard and pick the agent. Failure intelligence lists the most common codes, including INSPECTOR_ABORT for runs an inspector stopped and BUDGET_EXCEEDED for runs that hit a limit.

Select a run to open its trace. Governance shows Blocked by inspector, Codes shows INSPECTOR_ABORT, and the timeline shows the inspector that stopped it.

See Monitor your agents for the rest of Dashboard.

Limits and codes

When a run hits one of its limits, the agent stops planning and answers from the steps it finished. The run returns SUCCESS with the status BLOCKED_BY_BUDGET, and the limit's code says which one:

The run warns at 80% of a limit and starts wrapping up at 95%, so it can still give an answer. Because the last answer step still runs, the credits used can end slightly above the credit limit.

Limitations

• An agent can have up to 20 inspectors, each with a unique name.
• Severity doesn't change what an inspector does.
• Python checks are added and changed in code, not in aixplain Desktop.
• An inspector that errors lets the run continue.

Frequently asked questions

Get help

• Build an agent: see Build and deploy agents with Omni.
• Report a problem: email care@aixplain.com with the agent, the run and what you expected. Remove credentials and private data first.