Check agent steps
Check each tool call before it runs, hold risky steps for a person, and see every run in Monitor.
An agent's risk is in what it does: a wire, an order, a deleted file, a disabled account. Agent Lens checks each tool call before it runs. Your code only runs the tool if the verdict is allow.
If you would rather not change your agent's code, use an integration (Claude Code hook, MCP gateway, LiteLLM, LangGraph, Google ADK). They make this same check for you.
The call
Send the conversation so far, with every tool result, and the tool call that is about to run:
import os, requests
API = "https://api.neuronlens.com"
H = {"Authorization": f"Bearer {os.environ['NEURONLENS_API_KEY']}"}
def check(messages, tool, args, run_id, step):
return requests.post(f"{API}/v1/score", headers=H, timeout=5, json={
"messages": messages, # the conversation so far, tool results included
"tool_call": {"name": tool, "arguments": args},
"offered": ["lookup_vendor", "check_sanctions", "send_wire"],
"tool_map": {"lookup_vendor": "validate_vendor",
"check_sanctions": "sanctions_screening",
"send_wire": "wire_transfer"},
"agent": "payments-agent", "run_id": run_id, "step": step,
}).json()
r = check(messages, "send_wire", args, run_id, step)
if r["verdict"] == "allow":
result = send_wire(**args)
else:
result = f"Not run: {r['verdict']} by Agent Lens ({r['reason']})" # tell the model; it carries on
messages.append({"role": "tool", "name": "send_wire", "content": str(result)})
| Field | Why it matters |
|---|---|
messages | what the agent saw: the task, its own words, and every tool result. Send tool results as {"role": "tool", "name": ..., "content": ...}. Each message takes role, content and name only: drop tool_call_id and tool_calls first (example) |
tool_call | the step about to run |
run_id, step | group the steps of one task into a run in Monitor. Use your own task or session id |
offered | the tools the agent was given. The omission probe reads which checks it skipped |
tool_map | your tool names mapped to the probes' tool classes (below) |
A full example
A payments agent looked up the vendor, ran the sanctions screen, got a potential match, and now wants to send the wire anyway:
{
"messages": [
{"role": "system", "content": "You are the accounts-payable agent. Look up the vendor and run the sanctions screen before every wire."},
{"role": "user", "content": "Pay invoice INV-3381 from Northwind Freight Ltd, USD 48,200, today."},
{"role": "tool", "name": "lookup_vendor", "content": "Northwind Freight Ltd: approved vendor since 2021. Open invoice INV-3381, USD 48,200."},
{"role": "tool", "name": "check_sanctions", "content": "POTENTIAL MATCH: Northwind Freight FZE on the OFAC SDN list, 92% name similarity. Status HOLD: no payment until Compliance clears the match."}
],
"tool_call": {"name": "send_wire", "arguments": {"vendor": "Northwind Freight Ltd", "amount": "USD 48,200", "invoice": "INV-3381"}},
"offered": ["lookup_vendor", "check_sanctions", "send_wire"],
"tool_map": {"lookup_vendor": "validate_vendor", "check_sanctions": "sanctions_screening", "send_wire": "wire_transfer"},
"agent": "payments-agent", "run_id": "run-001", "step": 3
}
{
"verdict": "deny",
"reason": "failed check risk 1.00 (threshold 0.50)",
"probes": [
{"name": "failed_check", "risk": 0.999, "fired": true, "status": "scored"},
{"name": "omission", "risk": 0.0, "fired": false, "status": "scored"},
{"name": "harmful_io", "risk": 0.0, "fired": false, "status": "not_applicable"},
{"name": "injected_intent", "risk": 0.157, "fired": false, "status": "scored"}
],
"decision_id": "act-79a0e5cad887",
"latency_ms": 513
}
The wire is not sent. If the agent had skipped check_sanctions altogether, omission would have fired instead (risk 0.60, escalate), because the screen was offered and not used.
Map your tools: tool_map
The failed-check and omission probes need to know which of your tools is a check and which is an action. Map your tool names to the classes listed by GET /v1/probes:
| Class | Examples |
|---|---|
| Checks | sanctions_screening, validate_vendor, verify_purchase_order, pep_check, adverse_media_search, preview_order_risk |
| Actions | wire_transfer, place_equity_order, disable_account, delete_suspicious_file, isolate_endpoint |
| Reports | send_message, send_report |
For example, a trading agent with check_limit and submit_order sends {"check_limit": "preview_order_risk", "submit_order": "place_equity_order"}. Without tool_map, an order placed after a failed check is only caught if your tools already use these names.
When a step is held
escalate means a person should decide. Your code holds the step, and Monitor lists it under Monitor → Agents → Open issues. A reviewer opens it, sees the run and the reason, and clicks Approve or Reject.
To wait for the answer in code, poll the decision:
import time
deadline = time.time() + 300 # 5 minutes
while time.time() < deadline:
d = requests.get(f"{API}/v1/decisions/{r['decision_id']}", headers=H, timeout=10).json()
if d["status"] != "pending":
break # approved, rejected or expired
time.sleep(2)
if d["status"] == "approved":
result = send_wire(**args)
else:
result = "Not run: a reviewer did not approve this payment."
status is pending, approved, rejected or expired. The integrations do this waiting for you.
Rules: always hold, or always block
Some steps should go to a person every time, whatever the probes say. Add a rule in Settings → Rules, for example always review send_wire, or block delete_file for the support agent. A rule can only make a verdict stricter. A rule match shows in the response as "detector": "rule".
Modes: roll out safely
Each agent has a mode. /v1/score always returns the real recommendation and reports the agent's mode next to it. The integrations apply the mode for you:
| Mode | What happens |
|---|---|
enforce (new agents start here) | holds and denials reach the agent |
shadow | every step is checked; the integrations always allow, and Monitor shows what enforce would have done |
observe | every step is checked and recorded; nothing is held |
paused | nothing is checked; every step is recorded as not evaluated |
When you call /v1/score yourself, you can get the same effect by acting on the verdict only when you are ready: log it for a week, read Monitor, then start holding. To change an integration's agent mode, ask us.
Score the final report too
When the agent reports back ("Payment sent", "No match found"), send that answer with the same run_id. It is scored for deception, goal drift and omission against the whole run, which catches an agent that says it did something it did not:
{"messages": [...], "response": "INV-3381 is paid and cleared compliance.", "agent": "payments-agent", "run_id": "run-001"}
Related
- Integrations and hooks: the same check with no code changes.
- Monitor: runs, holds and open issues.
- Probes: omission, failed check, harmful I/O and injected intent.