Getting started

mastra-effect wraps Mastra with Effect 4 — it does not replace Mastra's agent loop.

Install

Core library:

pnpm add @mastra-effect/core effect@rc @mastra/core @mastra/memory

Assistant UI integration:

pnpm add @mastra-effect/assistant-ui @assistant-ui/react react

Peer dependencies

Package	Role
effect@^4.0.0-rc.113	Effect 4 runtime
@mastra/core@^1.66.0	Agent, tools, stream types
@mastra/memory@^1.29.0	Memory implementation
@assistant-ui/react	Assistant UI runtime (assistant-ui package only)
react	UI runtime (assistant-ui package only)

Minimal example

import { Agent, MastraAgent, MastraTool, Toolkit } from "@mastra-effect/core"
import { Context, Effect, Layer, Schema } from "effect"

class ApiKey extends Context.Service<ApiKey, { readonly token: string }>()("app/ApiKey") {}

const SearchDocs = MastraTool.make({
  id: "search_docs",
  description: "Search project documentation",
  inputSchema: Schema.Struct({ query: Schema.String }),
  outputSchema: Schema.String,
})

const toolkit = Toolkit.make(SearchDocs)

const agentLayer = MastraAgent.layer({
  id: "docs-agent",
  name: "Docs Agent",
  instructions: "Be helpful.",
  model: "openai/gpt-4o",
  toolkit,
})

const handlersLayer = toolkit.toLayer(
  Effect.fn(function* () {
    return {
      search_docs: Effect.fn(function* ({ query }) {
        const api = yield* ApiKey
        return `${api.token}:${query}`
      }),
    }
  })(),
)

await Effect.runPromise(
  Agent.stream("Find docs").pipe(
    Effect.provide(Layer.merge(agentLayer, handlersLayer)),
    Effect.provide(Layer.succeed(ApiKey, { token: process.env.API_KEY! })),
  ),
)

Monorepo layout

packages/core         — @mastra-effect/core
packages/assistant-ui — @mastra-effect/assistant-ui
docs/                               — this documentation site

Development

From the repository root:

pnpm install
pnpm typecheck
pnpm test
pnpm docs:dev