Integrations and hooks
How the Claude Code hook, MCP gateway, LiteLLM guardrail, OpenTelemetry, the SDK, LangGraph and Google ADK each connect, what they can stop, and how to set them up.
An integration makes the Agent Lens check for you, so you don't have to change your agent's code. Every integration does the same two things:
- Before a tool runs, it sends the tool call to Agent Lens and waits for the decision.
- After the tool runs, it reports what came back, so Monitor shows the whole step.
What differs is where the integration sits. That decides what it can see and whether it can stop a step.
Pick one
| Integration | Sits | Covers | Can stop a step | Code change |
|---|---|---|---|---|
| Claude Code hook | inside Claude Code | every tool: shell, file edits, web, MCP | yes | none: one file and settings.json |
| MCP gateway | between the agent and its MCP servers | every MCP tools/call | yes | point the agent at the gateway |
| LiteLLM guardrail | between the agent and the model | every tool call the model returns through your proxy | yes | a few lines of proxy config |
| LangGraph / LangChain | inside the agent | each tool call in the graph | yes | one middleware line |
| Google ADK | inside the agent | each tool call in an ADK agent | yes | two callbacks |
SDK (aegis) | inside the agent | the model's answers | answers only (raises on deny) | one line at start-up |
| OpenTelemetry | your tracing pipeline | whatever you already trace | no, scored after it ran | two environment variables |
| HTTP API | wherever you call it | anything | yes | one call before each tool |
Rule of thumb. For Claude Code, use the hook. If your tools are MCP servers, use the MCP gateway. If every model call already goes through LiteLLM, use the guardrail. If you write the agent yourself, use the middleware for your framework, or the HTTP API. Use OpenTelemetry only to watch, not to stop.
The integration files are single Python files you download from https://neuronlens.com/integrations/. Each one defaults to https://api.neuronlens.com. Connect → Agents in the Pro console shows the same setup, with your key filled in.
What every integration does the same way
The decision
Integrations call POST /v1/pre-action, which answers with a decision. It is the same check as /v1/score, in the integrations' own words:
/v1/pre-action decision | Same as /v1/score | What the integration does |
|---|---|---|
allow | allow | runs the tool |
review | escalate | holds the tool until a person answers, or asks you at the keyboard (Claude Code) |
block | deny | does not run the tool, and tells the model why |
A refused tool comes back to the model as an ordinary tool result or error that explains why. The model reads it and carries on with another plan, so the agent does not crash.
Holds
When a step is held, it shows up in Monitor → Agents → Open issues. The integration waits until someone clicks Approve (the tool runs) or Reject (it doesn't). If nobody answers within the hold timeout (5 minutes by default), the step is treated as not approved.
When Agent Lens can't be reached
Each integration has a fail mode:
| Fail mode | Agent Lens unreachable or too slow |
|---|---|
open (default) | the tool runs, as if Agent Lens were not there |
closed | the tool is refused |
A rejected or revoked key always refuses, whatever the fail mode, so a wrong key is noticed at once.
Modes
Each agent also has a mode:
| Mode | What the integration sees |
|---|---|
enforce (new agents start here) | the real decision: holds and blocks stop the step |
shadow | always allow. Monitor records what enforce would have done |
observe | always allow. Every step is checked and recorded |
paused | always allow. Nothing is checked, and each step is recorded as not evaluated |
To roll out without risk, ask us to put a new agent in shadow for its first week, then read Monitor before you switch it to enforce.
Claude Code hook
The hook checks every tool call Claude Code makes, before it runs. That includes Bash commands, file edits, web fetches and MCP tools. It uses Claude Code's own hooks: PreToolUse before a tool runs, and PostToolUse after.
Set it up
- Download the hook. It is one Python file with no dependencies:
curl -fsSLo ~/.claude/agentlens_hook.py https://neuronlens.com/integrations/agentlens_hook.py
- Register it in
.claude/settings.jsonin your project, or in~/.claude/settings.jsonfor every project:
{
"hooks": {
"PreToolUse": [
{"matcher": "*", "hooks": [{"type": "command", "timeout": 330,
"command": "python3 ~/.claude/agentlens_hook.py"}]}
],
"PostToolUse": [
{"matcher": "*", "hooks": [{"type": "command", "timeout": 15,
"command": "python3 ~/.claude/agentlens_hook.py"}]}
]
}
}
The same file handles both events. "matcher": "*" means every tool. Use "Bash|Edit|Write" to check only those.
- Set the environment Claude Code starts with:
export AGENTLENS_URL=https://api.neuronlens.com
export AGENTLENS_API_KEY=$NEURONLENS_API_KEY
export AGENTLENS_AGENT_ID=billing-service # the name in Monitor (default: claude-code)
- Start Claude Code and ask it to do something. The session appears in Monitor → Agents with each tool call as a step.
What you see in Claude Code
| Decision | What happens |
|---|---|
allow | nothing changes. Your own Claude Code permission rules still apply |
review | with AGENTLENS_REVIEW=ask (the default), Claude Code asks you at the prompt and shows the reason. With AGENTLENS_REVIEW=wait, the call waits until someone answers in Monitor |
block | the call is refused, and Claude reads Agent Lens refused this call: <reason> |
Settings
| Variable | Default | Meaning |
|---|---|---|
AGENTLENS_URL | https://api.neuronlens.com | where to send checks |
AGENTLENS_API_KEY | (none) | your nl_ key |
AGENTLENS_AGENT_ID | claude-code | the agent's name in Monitor |
AGENTLENS_REVIEW | ask | ask: ask at the keyboard. wait: wait for Monitor |
AGENTLENS_REVIEW_TIMEOUT_S | 300 | how long wait waits before "not approved" |
AGENTLENS_FAIL_MODE | open | open or closed when Agent Lens can't be reached |
AGENTLENS_TIMEOUT_S | 60 | how long one check may take |
Keep the PreToolUse timeout in settings.json (330 s above) longer than AGENTLENS_REVIEW_TIMEOUT_S, or Claude Code stops waiting before the reviewer can answer.
MCP gateway
The gateway is a small proxy you put in front of your MCP servers. Your agent connects to the gateway instead of the server. Every tools/call is checked first, and tool lists, handshakes and every other message pass straight through. It works with any MCP client: Claude, Codex, Cursor and agent frameworks.
agent ──MCP──▶ gateway ──MCP──▶ your MCP server
│
└── /v1/pre-action before each tools/call, /v1/post-action after
The gateway runs on your side, not ours. Tool traffic never leaves your network: only the check goes to Agent Lens. It is not a public download yet. Ask us for agentlens_mcp_gateway.py.
# gateway.yaml
upstreams:
default: http://127.0.0.1:9100/mcp # your MCP server
auth:
required: true
agents:
payments-agent:
token_sha256: <sha256 of the token this agent sends>
AGENTLENS_URL=https://api.neuronlens.com AGENTLENS_API_KEY=$NEURONLENS_API_KEY \
AGENTLENS_CONFIG=gateway.yaml PORT=9000 python agentlens_mcp_gateway.py
The agent then calls http://<gateway>:9000/mcp/payments-agent with Authorization: Bearer <its token>. A refused call comes back as a tool result that starts with Blocked by Agent Lens: <reason>. If your client can, send the user's task as an X-Agent-Goal header: the probes read it.
LiteLLM
A guardrail in your LiteLLM proxy. After the model answers, the guardrail checks every tool call in the answer before your agent sees it.
- Download
agentlens_guardrail.pynext to your proxy config. - Add the guardrail to the proxy config:
guardrails:
- guardrail_name: neuronlens
litellm_params:
guardrail: agentlens_guardrail.AgentLensGuardrail
mode: post_call
default_on: true
api_base: https://api.neuronlens.com
api_key: os.environ/NEURONLENS_API_KEY
fail_mode: open # Agent Lens unreachable: open | closed
on_refusal: rewrite # rewrite: the model is told why | block: the request fails
- Agent name: the virtual key's alias (or the team alias, or the end user). Without one, send
metadata: {"agent_id": "..."}on the request. - Run:
litellm_session_id, ormetadata.session_id. - Streaming works: text streams through as usual, and tool-call chunks are held until they are checked.
on_refusal: rewritereplaces the refused tool call with a message that explains why, so the agent's loop carries on.blockfails the request instead.
LangGraph and LangChain
Middleware that checks each tool call inside the agent's own process. Download agentlens_client.py and agentlens_langgraph.py next to your code.
import os
from agentlens_langgraph import AgentLensMiddleware
guard = AgentLensMiddleware(
agent_id="payments-agent",
url="https://api.neuronlens.com",
api_key=os.environ["NEURONLENS_API_KEY"],
kit_tools={"check_sanctions": "sanctions_screening", "send_wire": "wire_transfer"}, # tool_map
)
# LangChain >= 1.0
agent = create_agent(model, tools, middleware=[guard])
# or a hand-built LangGraph
node = ToolNode(tools, wrap_tool_call=guard.wrap_tool_call, awrap_tool_call=guard.awrap_tool_call)
A refused call becomes an error ToolMessage with the reason. The run id is the graph's thread_id. By default a held call waits for a reviewer. Pass review="refuse" to refuse held calls at once instead.
kit_tools is the same as tool_map: it tells the failed-check and omission probes which of your tools is a check and which is an action.
Google ADK
Download agentlens_client.py and agentlens_adk.py next to your code.
import os
from agentlens_adk import AgentLensCallbacks
guard = AgentLensCallbacks(url="https://api.neuronlens.com", api_key=os.environ["NEURONLENS_API_KEY"])
agent = LlmAgent(
name="research_agent", model=..., tools=[...],
before_tool_callback=guard.before_tool,
after_tool_callback=guard.after_tool,
)
A refused call never runs, and the model reads {"status": "refused", "error": "<reason>"}. The run id is the ADK session id.
SDK
The aegis Python SDK wraps your model client in one line. Every answer is scored after the model replies, and a deny raises AegisBlocked.
import os
from aegis import initLogger
from openai import OpenAI
initLogger(project="payments-agent", api_key=os.environ["NEURONLENS_API_KEY"],
base_url="https://api.neuronlens.com", metadata={"run_id": run_id})
client = OpenAI() # created after initLogger, so it is already wrapped
OpenAI, Anthropic and Gemini clients are supported. The SDK sees model calls, not tool calls. To stop a step, add a /v1/score check before the tool with the same run_id, and Monitor shows the answers and the steps as one run.
OpenTelemetry
If your agent already emits OpenTelemetry traces, send them to Agent Lens as well:
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.neuronlens.com/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20${NEURONLENS_API_KEY}
Tool calls are scored after they ran, so nothing is stopped. Monitor shows what enforce would have done. Use OpenTelemetry to see your traffic, and one of the integrations above to stop it.
Agent Lens follows the OpenTelemetry GenAI conventions. A tool call is a span with gen_ai.operation.name = execute_tool (or a span name that starts with execute_tool). It also reads:
| Attribute | Used as |
|---|---|
gen_ai.tool.name | the tool |
gen_ai.tool.call.arguments, gen_ai.tool.call.result | what was sent and what came back (turn on content capture in your instrumentation) |
gen_ai.conversation.id | the run (otherwise the trace id) |
gen_ai.agent.name | the agent (otherwise service.name) |
If another integration already checked a tool call, its span counts as that step's result, not as a new step.
Check that it works
After the first call:
- Connect → Agents lists the agent with its first step.
- Monitor → Agents shows the run. Open it to see each step, its decision and the probes that fired.
- To test a hold, add a rule in Settings → Rules, for example always review
send_wire, and call that tool. The step waits in Monitor → Agents → Open issues until you click Approve or Reject.