Mastra agent guard

Mastra agents run authored tools, processors, and MCP/workspace/toolset tools. Arcjet Guard sits at those boundaries so a remote policy can allow or deny the action before a side effect runs.

What is Arcjet?

Arcjet is the runtime security platform that ships with your code. Enforce budgets, stop prompt injection, detect bots, and protect personal information with Arcjet's AI security building blocks.

Use protect() on HTTP routes. Use the helpers on this page for agent tools and other actions that have no HTTP request.

You need an Arcjet account and an ARCJET_KEY. Launch one client at module scope and reuse it.

Framework wrappers take an action string such as email.sent. That slug selects the matching remote policy and names the event in the Arcjet Console. Direct guard() calls use the field name label for the same slug. Don’t pass label to a wrapper such as guardTool().

You can submit SDK rules in code, rely on a published remote policy, or combine both. For more information about the decision model, see Agent guards.

Vercel AI SDK, LangChain, Eve, and LangGraph wrappers are on Framework integrations.

Install

Install the Guard SDK and Mastra:

npm install @arcjet/guard @mastra/core

Import helpers from the versioned path @arcjet/guard/mastra/v1. There is no unversioned alias. @arcjet/guard/mastra does not resolve. The Mastra integration requires @mastra/core 1.x and Node.js 22 or later.

Launch one client at module scope:

1
import { launchArcjet } from "@arcjet/guard";
2

3
export const arcjet = launchArcjet({ key: process.env.ARCJET_KEY! });

Helpers

The integration exposes four surfaces:

guardTool() wraps a Mastra createTool({ execute }). On DENY the tool never runs. The model receives a structured ArcjetDenialResult ({ arcjetDenied, reason, message, retryable, retryAfterSeconds? }). Don’t throw. A throw becomes a generic tool error and drops the fields.
guardProcessor() is a Mastra Processor for inputProcessors / outputProcessors. On DENY, processInput / processInputStep call abort() (tripwire). processInputStep screens later agentic steps so tool continuations cannot skip the inbound gate.
guardHooks() provides beforeToolCall / afterToolCall for MCP / workspace or toolset tools that were not authored through guardTool. beforeToolCall can return { proceed: false, output } on DENY. afterToolCall is observe-only.
mastraAgentContext() reads MASTRA_THREAD_ID_KEY, then resource, then workflow.runId. It never mints an ID.

There is no guardInbound. Mastra channels already hit processInput. There is no guardApproval. Mastra requireApproval is human-in-the-loop (HITL) confirmation, not policy.

Never call createAgentContext inside a Mastra callback. Don’t also wrap these tools with @arcjet/guard/vercel-ai/v7.

The Mastra integration skill ships with @arcjet/guard. After npm install, copy or symlink it into your coding agent’s skills directory:

mkdir -p ~/.claude/skills
cp -r node_modules/@arcjet/guard/skills/integrate-arcjet-guard-mastra ~/.claude/skills/

Then ask the agent to add Arcjet Guard to this Mastra project. In Claude Code, run /integrate-arcjet-guard-mastra. The skill source is integrate-arcjet-guard-mastra.

Helper options

Option	Helpers	Description
`action`	All	Guard label and capture name. A string, or for hooks a function of `{ toolName }`.
`rules`	All	SDK rules, or a function of processor `{ text }` or tool input. Omit to submit none.
`metadata`	All	Nested JSON, or a function of the same input as `rules`.
`onGuardError`	All	`"deny"` (default) or `"allow"`.

Screen inbound with `guardProcessor`

Mastra channels already run through processInput. There is no guardInbound. Screen for prompt injection with guardProcessor in inputProcessors.

On DENY, processInput / processInputStep call abort() and Mastra raises a tripwire. Use a separate action name for outbound text on outputProcessors. processInputStep screens later agentic steps so a tool continuation cannot skip the inbound gate.

Helpers default to onGuardError: "deny". "allow" is a legitimate choice on the inbound processor, because failing closed there stops the agent answering during an outage.

1
import { Agent } from "@mastra/core/agent";
2
import { guardProcessor } from "@arcjet/guard/mastra/v1";
3
import { detectPromptInjection } from "@arcjet/guard";
4
import { arcjet } from "./arcjet.js";
5

6
const inbound = guardProcessor(arcjet, {
7
  action: "message.received",
8
  rules: ({ text }) => [detectPromptInjection()(text)],
9
});
10
const outbound = guardProcessor(arcjet, {
11
  action: "message.completed",
12
  rules: ({ text }) => [detectPromptInjection()(text)],
13
});
14

15
export const agent = new Agent({
16
  id: "support-agent",
17
  name: "support-agent",
18
  instructions: "Help the user.",
19
  model: "openai/gpt-4o",
20
  inputProcessors: [inbound],
21
  outputProcessors: [outbound],
22
});

Human approval is not a policy gate

Mastra requireApproval pauses for a human. It is not a remote policy. Use guardTool for authored tools or guardHooks for unwrapped tools.

On DENY the tool’s execute never runs. The model receives { arcjetDenied: true, reason, message, retryable, retryAfterSeconds? }. Don’t throw. A throw becomes a generic tool error and drops the fields. Scan free-text args (a note, reason, or body). An opaque orderId doesn’t trip email, phone, card, or IP detection, so don’t pass it to localDetectSensitiveInfo.

1
import { createTool } from "@mastra/core/tools";
2
import { z } from "zod";
3
import { guardTool } from "@arcjet/guard/mastra/v1";
4
import { tokenBucket, localDetectSensitiveInfo } from "@arcjet/guard";
5
import { arcjet } from "./arcjet.js";
6

7
const lookupLimit = tokenBucket({
8
  bucket: "lookups",
9
  refillRate: 10,
10
  intervalSeconds: 60,
11
  maxTokens: 10,
12
});
13
// Factory then text – same shape as `detectPromptInjection()(text)`.
14
const detectPii = localDetectSensitiveInfo();
15

16
export const lookupOrder = guardTool(
17
  arcjet,
18
  createTool({
19
    id: "lookup-order",
20
    description: "Look up an order by ID",
21
    inputSchema: z.object({
22
      orderId: z.string(),
23
      note: z.string(),
24
    }),
25
    async execute({ orderId, note }) {
26
      return { orderId, note, status: "shipped" };
27
    },
28
  }),
29
  {
30
    action: "order.looked-up",
31
    rules: (input) => [
32
      lookupLimit({ key: input.orderId, requested: 1 }),
33
      detectPii(input.note),
34
    ],
35
  },
36
);

Hooks can deny unwrapped tools

Unlike Eve (observe-only hooks), Mastra beforeToolCall can stop a call. Use guardHooks for MCP, workspace, or toolset tools you did not pass through guardTool. Applying both to the same authored tool double-calls the guard.

beforeToolCall returns { proceed: false, output } on DENY so those tools never execute. afterToolCall is observe-only.

1
import { guardHooks } from "@arcjet/guard/mastra/v1";
2
import { tokenBucket } from "@arcjet/guard";
3
import { arcjet } from "./arcjet.js";
4

5
const mcpLimit = tokenBucket({
6
  bucket: "mcp-access",
7
  refillRate: 20,
8
  intervalSeconds: 60,
9
  maxTokens: 20,
10
});
11

12
export const hooks = guardHooks(arcjet, {
13
  action: ({ toolName }) => `${toolName}.invoked`,
14
  rules: ({ toolName }) => [mcpLimit({ key: toolName, requested: 1 })],
15
});

Pass hooks to the Agent constructor (or to generate / stream).

Fail-closed default

Mastra helpers default to onGuardError: "deny". If Guard cannot be evaluated, the tool does not run and inbound processInput aborts the turn. "allow" is a legitimate choice on the inbound processor because failing closed there stops the agent answering during an outage.

Correlation

Set MASTRA_THREAD_ID_KEY / MASTRA_RESOURCE_ID_KEY on RequestContext before generate / stream. mastraAgentContext() reads them. It never calls createAgentContext. Preference order is thread, then resource, then workflow.runId. If none is a valid 1-256 printable-ASCII string, the call is uncorrelated rather than joined to a generated ID.

1
import {
2
  RequestContext,
3
  MASTRA_THREAD_ID_KEY,
4
  MASTRA_RESOURCE_ID_KEY,
5
} from "@mastra/core/request-context";
6

7
const requestContext = new RequestContext();
8
requestContext.set(MASTRA_THREAD_ID_KEY, conversationId);
9
requestContext.set(MASTRA_RESOURCE_ID_KEY, userId);
10

11
await agent.generate(message, { requestContext });

What not to use

There is no guardInbound. Channels already hit processInput.
There is no guardApproval. requireApproval is human HITL confirmation, not policy.
Don’t call createAgentContext inside a Mastra callback.
Don’t also wrap these tools with @arcjet/guard/vercel-ai/v7.
Don’t throw from guardTool to signal a denial. Return the payload so the model can inspect it.
Don’t import @arcjet/guard/mastra. The path is @arcjet/guard/mastra/v1.

Common patterns

Prompt injection on every step: guardProcessor in both inputProcessors and, if you want later tool continuations screened, rely on processInputStep (the same processor object handles both).
Rate limit plus PII on a tool: tokenBucket keyed on a trusted ID, plus localDetectSensitiveInfo() on a free-text note.
MCP tools you did not wrap: guardHooks with an action function of { toolName } that returns a past-tense slug per tool.

Framework integrations
Vercel AI SDK agent guard
LangChain agent guard
Vercel Eve agent guard
LangGraph agent guard
Agent guards
Example: arcjet/examples#193 (mastra-agent)