@agentified/mastra

Mastra adapter layer for Agentified — wraps SDK classes with Mastra-typed shells via composition, plus AG-UI streaming. See the Mastra guide for a full-stack walkthrough.

Install

npm install @agentified/mastra agentified

Peer dependencies: @mastra/core >= 1.0.0, @ag-ui/client >= 0.0.45, @ag-ui/mastra >= 1.0.0, zod >= 3.0.0

Quick Start

import { Agent } from "@mastra/core/agent";
import { Agentified } from "agentified";
import { mastra } from "@agentified/mastra";
import { openai } from "@ai-sdk/openai";

const ag = new Agentified().adaptTo(mastra());
await ag.connect("http://localhost:9119");

const instance = await ag.dataset("my-agent").register({
  tools: [
    { name: "get_weather", description: "Get weather", parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] }, handler: async (args) => ({ temp: 22 }) },
  ],
});

const session = instance.session("chat-1");
const agent = new Agent({
  name: "my-agent",
  model: openai("gpt-4o-mini"),
  instructions: "Use agentified_discover to find tools, then call them.",
});

// Simple — prepareStep is a property, includes discover by default
const result = await agent.generate(messages, {
  prepareStep: session.prepareStep,
  maxSteps: 10,
});

// With explicit tools via context chain
const ctx = await session.context
  .tools({ agentified_discover: session.discoverTool })
  .assemble();
// ctx.tools → { agentified_discover, ...discoveredTools }
// ctx.prepareStep → returns { tools } for Mastra injection
const result2 = await agent.generate(messages, {
  prepareStep: ctx.prepareStep,
  maxSteps: 10,
});

Note: @ai-sdk/openai must be ^3.0.0 (AI SDK v4). Mastra 1.11+ rejects v1.x.

Adapter Pattern

The mastra() factory returns an adapter for Agentified.adaptTo(). This wraps SDK classes in Mastra-typed shells via composition (not inheritance):

Agentified.adaptTo(mastra()) → MastraAgentified
  └─ .dataset(name) → MastraDatasetRef
       └─ .register({ tools }) → MastraInstance
            ├─ .discoverTool     — Mastra createTool
            ├─ .prepareStep      — property, returns { tools } for injection
            ├─ .session(id)      → MastraSession
            │    ├─ .discoverTool      — Mastra createTool
            │    ├─ .getMessagesTool  — Mastra createTool (conversation navigation)
            │    ├─ .prepareStep  — property, returns { tools }
            │    ├─ .context      → MastraContextBuilder
            │    │    ├─ .tools(Record<string, MastraTool>) — chainable
            │    │    ├─ .messages() / .recall()
            │    │    └─ .assemble() → MastraAssembledContext
            │    │         ├─ .tools — explicit + discovered
            │    │         └─ .prepareStep — returns { tools }
            │    ├─ .conversation (SDK passthrough)
            │    └─ .getMessages / .updateConversation
            └─ .namespace(id)    → MastraNamespace
                 └─ .session(id) → MastraSession

Import SDK classes from agentified, Mastra-specific adapters from @agentified/mastra.

API Reference

mastra()

Returns an adapter object for Agentified.adaptTo().

import { Agentified } from "agentified";
import { mastra } from "@agentified/mastra";

const ag = new Agentified().adaptTo(mastra());

MastraInstance

Wraps SDK Instance. discoverTool is a Mastra createTool result instead of a raw DiscoverTool.

MastraSession

Wraps SDK Session. discoverTool and getMessagesTool are Mastra createTool results. Delegates context, conversation, getMessages, updateConversation to the SDK session. prepareStep includes both agentified_discover and agentified_get_messages in the returned tools.

streamSSE(observable, res)

Pipes an AG-UI Observable into an HTTP SSE response.

import { streamSSE } from "@agentified/mastra";

jsonSchemaToZod(schema)

Converts a JSON Schema object to a Zod schema. Used internally to hydrate Mastra tools.

import { jsonSchemaToZod } from "@agentified/mastra";

Links

• Root README
• Documentation
• Mastra guide — Full-stack walkthrough
• Architecture
• TypeScript SDK
• Frontend Client
• React Bindings
• ts-mastra-smoke example — runnable smoke test
• QuickHR Example — full Mastra + React app

License

MIT