Feature: Per-tool authorization middleware for agent tool calls

[stevenkozeniesky02]

Problem

VoltAgent provides guardrails and tool management, but there's no built-in mechanism for per-tool authorization based on agent identity.

When building multi-agent systems with VoltAgent, different agents in the workflow need different tool access levels. An orchestrator agent might need broad access, while a sub-agent it delegates to should only have read permissions.

Use Case

const agent = new Agent({
  name: 'research-bot',
  tools: [searchDocs, saveNote, deleteNote, deployProd],
});

This agent can call all four tools. In production, you want:

• research-bot can call searchDocs only
• content-bot can call searchDocs + saveNote
• admin-bot can call everything
• Every tool call logged with who called what and whether it was allowed

Proposal

A tool authorization hook in the agent or tool configuration:

const agent = new Agent({
  name: 'research-bot',
  tools: [searchDocs, saveNote, deleteNote],
  toolGuard: async (toolName, context) => {
    // Check against permission rules
    const allowed = context.permissions?.some(
      pattern => matchGlob(pattern, toolName)
    );
    if (!allowed) {
      return { denied: true, reason: `${toolName} not in allowed tools` };
    }
    return { denied: false };
  },
});

This would integrate with VoltAgent's existing guardrails system and enable:

• Per-agent tool restrictions
• Integration with external permission engines (like AgentsID for deny-first agent permissions)
• Audit trail of tool call authorization decisions
• Delegation with automatic scope narrowing

Since VoltAgent already has MCP support, this becomes especially relevant — MCP servers expose many tools, and agents connecting to them need per-tool authorization.

Would this fit within VoltAgent's guardrails architecture, or is there an existing pattern I should use?

[0xbrainkid]

This is a really important feature request — especially with MCP tool proliferation. Just at RSAC 2026, Unit 42 + Adversa.ai found that 38% of 500+ public MCP servers have no authentication at all, and there were 30 CVEs filed against MCP implementations in just 60 days.

Per-tool authorization within a single agent framework is step one. But the harder problem comes when agents from different organizations call each other's tools — different auth systems, different identity claims, no shared trust.

We've been working on this at AgentFolio with SATP (Solana Agent Trust Protocol) — on-chain verifiable identity and behavioral reputation that agents can carry across platforms. The idea is that your toolGuard could check not just local permissions, but also query an external trust score for the calling agent before authorizing tool access.

Something like:

toolGuard: async (toolName, context) => {
  const callerTrust = await verifyAgentIdentity(context.callerDID);
  if (callerTrust.score < MINIMUM_TRUST && toolName === 'deployProd') {
    return { denied: true, reason: 'Insufficient cross-org trust score' };
  }
  return { denied: false };
}

Would VoltAgent be open to supporting pluggable external trust providers alongside local permission rules? Happy to share what we've learned building cross-org identity verification.

[0xbrainkid]

Strong proposal. Per-tool authorization is the right abstraction — and the middleware pattern means it composes cleanly with VoltAgent's existing guardrails.

One extension worth considering: external trust signals as authorization inputs. The current proposal scopes authorization to static role definitions (agent.identity.role). This works within a single VoltAgent deployment, but breaks down when agents cross organizational boundaries — a delegated sub-agent from an external system has no role in your local RBAC.

A pluggable TrustProvider interface would let the authorization middleware query external trust data alongside local roles:

const authMiddleware = createToolAuth({
  providers: [
    localRBAC({ roles: agentRoles }),
    externalTrust({
      // Query cross-org behavioral trust score
      provider: 'satp',
      endpoint: 'https://agentfolio.bot/api/profile',
      minScore: 60
    })
  ],
  policy: 'all'  // all providers must pass
});

This pattern is being implemented across several frameworks right now:

• browser-use #4563 (85K⭐) — multi-provider TrustProvider for browser agents
• LangChain #36232 (96K⭐) — pluggable TrustProvider for tool execution
• A2A #1672 (23K⭐) — trust providers in Agent Cards

The ToolAuthMiddleware interface you proposed is a clean fit for this — it just needs a TrustProvider as an additional input alongside the local role check. Same middleware, richer trust signals.

[sapkra]

wouldn't it make more sense to provide or not to provide tools depending on access level?

e.g. using prepareStep
i just proposed it here #1187

currently you could also just do the authentication in the tools itself

export const getUserInfoTool = createTool({
  name: 'getUserInfo',
  execute: async ({ context }, options?: ToolExecuteOptions) => {
    const token = context?.get('token') as number | undefined;
    const isAuthenticated = checkToken(token);

    if (!isAuthenticated) {
      return {
        authenticated: false,
        message: 'Token is invalid',
        user: null,
      };
    }

    // do stuff to get user

    return {
      authenticated: true,
      message: null,
      user,
    };
  },
});

[m13v]

the toolGuard middleware pattern is the right level of abstraction here. we deal with this in our tool execution layer where different agent roles (orchestrator vs worker) have different tool access. the prepareStep suggestion from sapkra is valid for simple cases but it fails when you need audit logging of denied attempts, which you absolutely need in production multi-agent systems. one pattern that worked well for us: define tool permissions as a simple allow-list per agent identity, but make the authorization check a middleware that runs before tool execution and logs the decision (allowed/denied, which agent, which tool, timestamp). this way you get the access control plus the audit trail without coupling it to the tool implementation itself. for MCP tools specifically, the schema overhead of registering tools the agent can't use wastes tokens. filter at registration time, not at execution time.

[m13v]

our tool execution layer where we handle the per-tool authorization and audit logging I described: https://github.com/m13v/fazm/blob/main/Desktop/Sources/Providers/ChatToolExecutor.swift

[stevenkozeniesky02]

sapkra's prepareStep point and m13v's filter-at-registration pattern are both valid but they solve different problems.

Filtering tools at registration time saves tokens. The agent never sees tools it can't use. But you lose the ability to give the agent context about why it can't do something, which matters for multi-turn conversations where the user might ask "can you delete that?" and the agent needs to say "I don't have delete permissions in this session" rather than not knowing deletion exists.

The pattern that covers both:

1. Registration-time filtering for tools the agent should never reason about (admin tools for a read-only agent)
2. Execution-time guards for tools the agent can see but may not be allowed to invoke depending on context (rate limits, time-of-day restrictions, parameter constraints)
3. Audit logging on both. Denied attempts are signal, not noise.

m13v is right that the guard should log denied attempts. In our permission spec every decision (allow or deny) goes to a tamper-evident audit chain. The audit trail is what makes the system debuggable when an agent does something unexpected. You can trace back through every tool call and every policy evaluation.

The fazm tool executor pattern is interesting. Doing this in Swift for desktop agents is a use case we haven't tested against yet.

[zrosenbauer]

related to #1182 and #1194