> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastra

> Run a Mastra agent on Tilde with the @trytilde/sdk-mastra-node adapter.

The Mastra adapter runs a Mastra `Agent` on Tilde. It works with Mastra 1.

<Card title="Example agent" icon="github" href="https://github.com/trytilde/tilde/tree/main/sdk/ts/examples/mastra-example-agent" horizontal>
  A complete Mastra agent with bundled tools and skills, in the Tilde open-source repository.
</Card>

## Install

```bash theme={"system"}
npm i @trytilde/sdk @trytilde/sdk-mastra-node @mastra/core ai @ai-sdk/openai
```

## How it works

Pass `tildeMastra(ctx)` to each `generate` or `stream` call. It adds a `tilde` toolset with the channel's tools and the agent's Tilde and bundled tools, the abort signal, and an input processor for new user input.

Mastra has no per-call skills option, so wrap the agent's skills with `tildeMastraSkills`. Mastra then loads your own skills and the agent's Tilde skills together.

```typescript src/agent.ts theme={"system"}
import { fileURLToPath } from "node:url";
import { inference, type AgentContext } from "@trytilde/sdk";
import {
  convertToMastraMessages,
  tildeMastra,
  tildeMastraSkills,
} from "@trytilde/sdk-mastra-node";
import { Agent } from "@mastra/core/agent";
import { createOpenAI } from "@ai-sdk/openai";
import { bundledTools } from "./bundled-tools.js";

const openai = createOpenAI(inference("default"));

export const agent = new Agent({
  id: "support-agent",
  name: "Support agent",
  instructions: "You are a support assistant. Reply with the channel tools.",
  model: openai.responses("gpt-4o-mini"),
  skills: tildeMastraSkills([
    fileURLToPath(new URL("../skills", import.meta.url)),
  ]),
});

export async function respond(ctx: AgentContext) {
  const history = await ctx.message.history();
  const messages = await convertToMastraMessages({
    messages: history.items,
    context: ctx,
  });
  await agent.generate(messages, {
    ...(await tildeMastra(ctx, { bundled: bundledTools })),
    maxSteps: 8,
  });
}
```

## Feature compatibility

| Feature | Support | Notes |
| - | - | - |
| Inference gateway | Yes | |
| Framework trace spans | Partial | Tilde records its own spans. Mastra's observability is not connected. |
| Tilde and channel tools | Yes | |
| Bundled tools | Yes | Write Mastra `createTool()` tools. |
| Prompt versioning | Yes | Registers `<agent id>/instructions`. Instructions written as a function become a dynamic prompt. |
| Native skills | Yes | Skill folders and `createSkill()` skills ship at deploy. Tilde skills load through `tildeMastraSkills`. |
| New input during a run | Yes | |

If you export a `Mastra` instance, `tilde deploy` registers the prompts of every agent in it.

## Limitations

* **Input processors.** Mastra replaces an agent's configured input processors with any you pass per call. `tildeMastra` passes one, so add your own processors to the same call.
* **Suspend and resume.** In [search mode](/docs/tools/overview#tool-discovery), a bundled tool called through `tools.execute` runs outside Mastra's agent loop. It cannot suspend and resume.
* **Private settings.** The adapter reads the agent's instructions through a method outside Mastra's public API. It is tested against Mastra 1.67.