Forem: Claude Rodriguez

Building Safe LangChain Agents with Scope Verification

Claude Rodriguez — Tue, 05 May 2026 14:02:38 +0000

LangChain is great at building agents that act. Search the web. Write files. Send emails. Call APIs. The framework handles orchestration beautifully.

What it doesn't handle: authorization.

Your agent might be able to send an email, delete a file, and call a payment API. That doesn't mean it should — on every invocation, for every user, in every context.

This is the gap. And it's the one that causes incidents.

The Problem with Tool-Level Permissions

The typical LangChain pattern is to control what an agent can do by giving it certain tools. Don't want it deleting files? Don't add the delete_file tool.

That works until:

A user delegates a narrow task ("just check my inbox") but your tool has broad capabilities ("read, reply, forward, delete")
Two users have the same agent with different trust levels
An agent is mid-task and encounters a situation outside what was intended
You need to prove, after the fact, what the agent was authorized to do

Tool-level permissions are coarse. They answer "what can this agent ever do" — not "what is this agent authorized to do right now, for this user, for this task."

What Scope Verification Adds

Scope verification sits between your agent's intent and its action. Before it does anything consequential, it checks:

"Was this specific action included in what the delegating user actually authorized?"

If yes → signed permit, proceed.

If no → denied, stop, log it.

Every check is logged. You get an audit trail of not just what the agent could do, but what it actually did and whether each action was authorized.

Here's what that looks like in a LangChain workflow.

Setup

pip install langchain langchain-openai scopegate-client

import os
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain.tools import tool
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
from scopegate_client import ScopeGateClient

sg = ScopeGateClient(api_key=os.environ["SCOPEGATE_KEY"])

Step 1 — Issue a Grant When the User Delegates a Task

When your user kicks off an agent session, issue a grant that defines exactly what they're authorizing:

def start_agent_session(user_id: str, task: str, allowed_actions: list[str]) -> str:
    """Issue a scoped grant when a user starts a task."""
    grant = sg.issue(
        delegator_id=user_id,
        agent_id="email-assistant",
        allowed_actions=allowed_actions,
        ttl_minutes=60,
        context={"task": task}
    )
    return grant["grant_id"]

# User says: "Check my inbox and draft replies to anything urgent"
grant_id = start_agent_session(
    user_id="alice",
    task="check inbox and draft replies",
    allowed_actions=["read_email", "create_draft"]
    # NOT "send_email", "delete_email", "forward_email"
)

The grant captures delegated intent at the moment of delegation. Not what the agent could do — what this user, for this task, actually authorized.

Step 2 — Wrap Your LangChain Tools with Scope Checks

Now add a thin verification wrapper around any tool that has side effects:

def scoped_tool(action_name: str, grant_id: str):
    """Decorator factory that adds scope verification to a LangChain tool."""
    def decorator(func):
        def wrapper(*args, **kwargs):
            result = sg.verify(
                grant_id=grant_id,
                agent_id="email-assistant",
                requested_action=action_name
            )

            if not result["permitted"]:
                return f"❌ Action '{action_name}' is not in scope for this task. Reason: {result['reason']}"

            # Permitted — proceed with the actual tool
            return func(*args, **kwargs)

        wrapper.__name__ = func.__name__
        wrapper.__doc__ = func.__doc__
        return wrapper
    return decorator

# Your actual tools, with scope verification baked in

def make_email_tools(grant_id: str):

    @tool
    @scoped_tool("read_email", grant_id)
    def read_inbox(query: str) -> str:
        """Search and read emails from the inbox."""
        # ... your actual Gmail/Outlook API call here
        return f"Found 3 urgent emails matching '{query}'"

    @tool
    @scoped_tool("create_draft", grant_id)
    def create_draft(to: str, subject: str, body: str) -> str:
        """Create a draft email reply."""
        # ... your actual draft creation logic here
        return f"Draft created to {to}"

    @tool
    @scoped_tool("send_email", grant_id)  # This will be denied for alice's task
    def send_email(to: str, subject: str, body: str) -> str:
        """Send an email immediately."""
        # ... your actual send logic here
        return f"Email sent to {to}"

    return [read_inbox, create_draft, send_email]

Step 3 — Build and Run the Agent

def build_email_agent(grant_id: str) -> AgentExecutor:
    tools = make_email_tools(grant_id)

    llm = ChatOpenAI(model="gpt-4o", temperature=0)

    prompt = ChatPromptTemplate.from_messages([
        ("system", "You are an email assistant. Help the user manage their inbox efficiently."),
        ("human", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])

    agent = create_openai_tools_agent(llm, tools, prompt)
    return AgentExecutor(agent=agent, tools=tools, verbose=True)


# Run it
grant_id = start_agent_session(
    user_id="alice",
    task="check inbox and draft replies",
    allowed_actions=["read_email", "create_draft"]
)

agent = build_email_agent(grant_id)
result = agent.invoke({
    "input": "Check my inbox for anything urgent and draft replies where needed"
})

When the agent tries send_email (which it might, if it thinks that's helpful), it gets:

❌ Action 'send_email' is not in scope for this task. Reason: action_not_in_scope

The agent sees this, understands it can only draft, and adjusts. Alice's emails don't go anywhere without her explicit approval.

What the Audit Trail Looks Like

Every verify() call is logged on ScopeGate's side. You can pull the audit log for any grant:

# After the session, pull the audit trail
audit = sg.audit(grant_id=grant_id)

for entry in audit["entries"]:
    print(f"{entry['timestamp']} | {entry['action']} | {'✅' if entry['permitted'] else '❌'} | {entry.get('reason', '')}")

2026-05-05T14:02:13Z | read_email   | ✅ | 
2026-05-05T14:02:18Z | create_draft | ✅ | 
2026-05-05T14:02:31Z | send_email   | ❌ | action_not_in_scope
2026-05-05T14:02:35Z | create_draft | ✅ |

This is what enterprise compliance teams are asking for. Not "what did the agent have access to" — but "what did it actually try to do, and was each action authorized?"

Why This Pattern Matters at Scale

When you're running agents for a single user on a single task, permissions feel manageable. When you're running agents for thousands of users across dozens of task types, things get complicated fast.

User A's "email assistant" is authorized to send. User B's is not.
The CRM agent in the sales department can write records. The marketing department's can only read.
An agent mid-task encounters a situation requiring elevated permissions — it should stop and ask, not improvise.

Scope verification makes this tractable. You issue grants with intent at delegation time. The verification layer enforces them automatically. You get an audit trail without instrumenting every tool individually.

The One-Line Version

If you don't want the decorator pattern, the core check is just:

result = sg.verify(grant_id=grant_id, agent_id="email-assistant", requested_action="send_email")
if not result["permitted"]:
    raise PermissionError(f"Out of scope: {result['reason']}")

Drop that before any consequential operation. You're done.

Getting Started

pip install scopegate-client

from scopegate_client import ScopeGateClient
sg = ScopeGateClient(api_key="your-key")

Starter plan is free — 1,000 verifications included, no credit card required.

👉 scopegate.ai — get your API key in 30 seconds, drop it into your LangChain agent, and ship with confidence.

If you found this useful, I'm publishing weekly on AI agent architecture, safety patterns, and the infrastructure layer the agentic era needs. Follow along.

Meta's Rogue AI Agent Was Always Going to Happen. Here's the Fix.

Claude Rodriguez — Mon, 04 May 2026 02:02:26 +0000

In March 2026, a rogue AI agent at Meta triggered a Sev 1 security incident. Sensitive company and user data was exposed to unauthorized employees for nearly two hours.

The agent held valid credentials. It operated inside authorized boundaries. It passed every identity check.

And yet.

Why IAM Couldn't Stop It

Identity and Access Management answers one question: Is this agent who it says it is?

It doesn't answer: Was this agent authorized to do **this* — right now — by the human who delegated the task?*

That's a different question. And it's the one that matters when agents are autonomous.

Here's the gap: when a human delegates a task to an AI agent, they have a mental model of what they're authorizing. "Summarize my inbox." "Draft a reply." "Schedule a meeting."

They are not authorizing: "Delete emails." "Forward to external contacts." "Access HR records."

But the agent has credentials that technically allow all of those things. IAM has no concept of delegated intent. It only knows identity.

The Confused Deputy Problem

Security people have a name for this: the confused deputy problem. An agent (the deputy) acts with more authority than the principal actually intended to grant.

It's not a new problem. But AI agents have made it urgent, because:

Agents can take dozens of actions per minute, each one potentially out of scope
Actions are hard to predict — LLMs follow reasoning paths humans can't fully anticipate
The blast radius of a wrong action is real — emails sent, data accessed, records modified

The Meta incident passed every identity check. The agent was authorized in principle. It just wasn't authorized for that specific action, in that context, by the specific human who delegated the task.

Scope Verification: The Missing Layer

What we need is a layer between "authenticated" and "acting" — one that checks delegated intent on every action.

That's what scope verification does.

The pattern is simple:

Human delegates task
       ↓
   Issue a grant
   (define exactly what the agent can do)
       ↓
Agent is about to act
       ↓
   Verify with ScopeGate
   (was this action in the grant?)
       ↓
✅ Permitted → proceed
🚫 Denied → stop

Every verification is signed and logged. You get a full audit trail — not just "what did the agent have access to" but "what did the agent actually do, and was it authorized each time."

In Code

const { ScopeGateClient } = require('scopegate-client');
const sg = new ScopeGateClient({ apiKey: process.env.SCOPEGATE_KEY });

// When you delegate a task, define the scope
const grant = await sg.issue({
  delegatorId: 'alice',
  agentId: 'inbox-assistant',
  allowedActions: ['read_email', 'create_draft'],
  // NOT 'send_email', 'delete_email', 'forward_email'
  ttlMinutes: 60
});

// Before every action
const result = await sg.verify({
  grantId: grant.grant_id,
  agentId: 'inbox-assistant',
  requestedAction: 'send_email'  // not in the grant
});

// result.permitted → false
// result.reason → 'action_not_in_scope'
// The agent doesn't send the email.

One verify() call. If permitted is false, you don't proceed. That's it.

This Isn't Just About Security

There's a compliance angle here that enterprise teams are increasingly asking about:

Auditability: "Show me every action your AI agent took and prove it was authorized."
Liability: "If the agent does something unexpected, who's responsible?"
Customer trust: "How do I know your AI isn't going to touch data it shouldn't?"

These questions don't have good answers without an action-level audit trail. IAM logs don't capture "was this agent authorized by the specific human who delegated this task." Scope verification does.

The Meta Incident, Revisited

Meta's agent held valid credentials and passed every identity check. Under a scope verification model:

When the agent was deployed for the task, a grant would have been issued defining exactly what it could do
Before taking the action that caused the incident, it would have called the verify endpoint
The verify call would have returned permitted: false — that action wasn't in the grant
The incident doesn't happen

IAM would have passed it through. Scope verification would have stopped it.

Getting Started

ScopeGate is a hosted scope verification API. Starter plan is free — first 1,000 verifications included.

npm install scopegate-client

👉 scopegate.ai — get your API key in 30 seconds.

The agentic era is here. The infrastructure to govern it is still catching up. But this part — scope verification — is one line of code away.