# Mastra

> Check every tool call a Mastra agent makes with Thoth before the tool runs.

Source: https://docs.atensecurity.com/docs/sdks/mastra

`governMastraTools` returns governed copies of the tools you give a
[Mastra](https://mastra.ai) `Agent`. Each tool call is checked with Thoth
before the tool's `execute` runs. It needs `@atensec/thoth` 0.2.0 or later,
and is tested with `@mastra/core` 1.81.0
([framework compatibility](https://docs.atensecurity.com/docs/sdks/framework-compatibility)).

## Install

```bash
npm install @atensec/thoth @mastra/core zod
```

Register the agent in Thoth first, and give your app its connection settings:

```bash
export THOTH_TENANT_ID="your-tenant-id"
export THOTH_API_URL="https://api.atensecurity.com"  # trial and self-serve; Enterprise: your enforce. host
export THOTH_API_KEY="..."                                     # a runtime key for this agent
```

[Your first governed agent](https://docs.atensecurity.com/docs/getting-started/quickstart) covers
registering an agent and creating its key.

## Govern an agent's tools

```typescript title="agent.ts"
import { Agent } from "@mastra/core/agent";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { governMastraTools } from "@atensec/thoth/mastra";

const lookupOrder = createTool({
  id: "lookup-order",
  description: "Look up an order by ID",
  inputSchema: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => orders.get(orderId),
});

const sendRefund = createTool({
  id: "send-refund",
  description: "Refund an order",
  inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
  execute: async ({ orderId, amount }) => payments.refund(orderId, amount),
});

// Build the agent per request, for the user it serves.
function supportAgent(userId: string) {
  return new Agent({
    id: "support-agent",
    name: "Support agent",
    instructions: "Help customers with their orders.",
    model: "openai/gpt-5-mini",
    tools: governMastraTools(
      { lookupOrder, sendRefund },
      {
        agentId: "support-agent",
        tenantId: process.env.THOTH_TENANT_ID!,
        approvedScope: [],
        userId,
      },
    ),
  });
}

const result = await supportAgent("alice@example.com").generate(
  "Refund order A-1, it arrived damaged.",
);
```

Thoth sees each tool by its key in the object you pass, the name the model
calls it by (`sendRefund` above), with the tool's input as its arguments.
Mastra's execution context reaches `execute` unchanged. The governed copies
keep each tool's fields and class, and the tools you pass in aren't changed.
Tools without an `execute` are returned as they are and aren't checked.

## What each decision does

| Decision  | What happens                                                                                                                                                                                 |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ALLOW`   | `execute` runs.                                                                                                                                                                              |
| `DENY`    | `execute` never runs. The governed tool throws `ThothPolicyViolation`, and Mastra passes the refusal to the model as the tool's error output ("Thoth blocked tool 'sendRefund': …"). `generate` carries on, so the model can tell the user. |
| `STEP_UP` | The call waits for a person to approve it, up to `stepUpTimeoutMinutes` (15 by default). If it's approved, `execute` runs; otherwise it's refused as for `DENY`.                              |

If Thoth can't be reached, calls are refused unless you set `failOpen: true`.

Start a new agent in [observe](https://docs.atensecurity.com/docs/operations/enforcement-modes): Thoth
records what it would have decided and every call runs. Switch the agent to
enforce when the observe summary shows it's ready.
