NeuronLens
Browse the documentation
Agent Lens

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:

  1. Before a tool runs, it sends the tool call to Agent Lens and waits for the decision.
  2. 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.

THE MODELModelOpenAI, Anthropic,vLLM, Bedrock…YOUR AGENTAgentClaude Code, LangGraph…hook · SDK · middlewareTHE TOOLSToolsMCP servers, APIs,shell, filesLiteLLMMCP gatewayOTel, after it ranAgent Lens · api.neuronlens.comchecks each step and answers allow · review · block
Solid lines can stop a step: the integration waits for the answer before the tool runs. The dashed line (OpenTelemetry) only reports steps that already ran.

Pick one

IntegrationSitsCoversCan stop a stepCode change
Claude Code hookinside Claude Codeevery tool: shell, file edits, web, MCPyesnone: one file and settings.json
MCP gatewaybetween the agent and its MCP serversevery MCP tools/callyespoint the agent at the gateway
LiteLLM guardrailbetween the agent and the modelevery tool call the model returns through your proxyyesa few lines of proxy config
LangGraph / LangChaininside the agenteach tool call in the graphyesone middleware line
Google ADKinside the agenteach tool call in an ADK agentyestwo callbacks
SDK (aegis)inside the agentthe model's answersanswers only (raises on deny)one line at start-up
OpenTelemetryyour tracing pipelinewhatever you already traceno, scored after it rantwo environment variables
HTTP APIwherever you call itanythingyesone 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 decisionSame as /v1/scoreWhat the integration does
allowallowruns the tool
reviewescalateholds the tool until a person answers, or asks you at the keyboard (Claude Code)
blockdenydoes 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 modeAgent Lens unreachable or too slow
open (default)the tool runs, as if Agent Lens were not there
closedthe 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:

ModeWhat the integration sees
enforce (new agents start here)the real decision: holds and blocks stop the step
shadowalways allow. Monitor records what enforce would have done
observealways allow. Every step is checked and recorded
pausedalways 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.

Claude Codeagentlens_hook.pyAgent LensBEFOREPreToolUse: Bash "rm -rf build/"POST /v1/pre-actionallow · review · blockcarry on · ask you · refuse with the reasonthe tool runs, if allowedAFTERPostToolUse: what came backPOST /v1/post-action
One Claude Code session is one run in Monitor. If a held call ran because you said yes at the prompt, the hook marks the hold as approved before it reports the result.

Set it up

  1. Download the hook. It is one Python file with no dependencies:
curl -fsSLo ~/.claude/agentlens_hook.py https://neuronlens.com/integrations/agentlens_hook.py
  1. Register it in .claude/settings.json in your project, or in ~/.claude/settings.json for 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.

  1. 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)
  1. 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

DecisionWhat happens
allownothing changes. Your own Claude Code permission rules still apply
reviewwith 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
blockthe call is refused, and Claude reads Agent Lens refused this call: <reason>

Settings

VariableDefaultMeaning
AGENTLENS_URLhttps://api.neuronlens.comwhere to send checks
AGENTLENS_API_KEY(none)your nl_ key
AGENTLENS_AGENT_IDclaude-codethe agent's name in Monitor
AGENTLENS_REVIEWaskask: ask at the keyboard. wait: wait for Monitor
AGENTLENS_REVIEW_TIMEOUT_S300how long wait waits before "not approved"
AGENTLENS_FAIL_MODEopenopen or closed when Agent Lens can't be reached
AGENTLENS_TIMEOUT_S60how 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.

  1. Download agentlens_guardrail.py next to your proxy config.
  2. 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, or metadata.session_id.
  • Streaming works: text streams through as usual, and tool-call chunks are held until they are checked.
  • on_refusal: rewrite replaces the refused tool call with a message that explains why, so the agent's loop carries on. block fails 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:

AttributeUsed as
gen_ai.tool.namethe tool
gen_ai.tool.call.arguments, gen_ai.tool.call.resultwhat was sent and what came back (turn on content capture in your instrumentation)
gen_ai.conversation.idthe run (otherwise the trace id)
gen_ai.agent.namethe 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:

  1. Connect → Agents lists the agent with its first step.
  2. Monitor → Agents shows the run. Open it to see each step, its decision and the probes that fired.
  3. 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.