Mastra adapter

@astropods/adapter-mastra wraps a Mastra Agent and connects it to the Astro messaging sidecar. It translates Mastra’s fullStream chunks into the shared StreamHooks lifecycle, wires STT/TTS through Mastra’s voice provider, and auto-configures OTEL tracing when an exporter endpoint is set.

Install

$
bun add @astropods/adapter-mastra
$
# or: npm install @astropods/adapter-mastra

Requires @mastra/core >= 1.14.0 as a peer dependency.

Quick start

1
import { Agent } from '@mastra/core/agent';
2
import { serve } from '@astropods/adapter-mastra';
3
4
const agent = new Agent({
5
  name: 'My Agent',
6
  instructions: 'You are a helpful assistant.',
7
  model: 'openai/gpt-4o',
8
});
9
10
serve(agent);

serve(agent) connects to the messaging sidecar at localhost:9090 (or GRPC_SERVER_ADDR) and runs until the process exits. Under ast dev and in production the address is injected for you.

API

serve(agent, options?)

Connects a Mastra Agent to the messaging service and starts listening.

ServeOptions

MastraAdapter

The class behind serve(). Use it directly if you need custom lifecycle control:

1
import { MastraAdapter } from '@astropods/adapter-mastra';
2
import { serve } from '@astropods/adapter-core';
3
4
serve(new MastraAdapter(agent));

How Mastra chunks map to hooks

Other chunk types are ignored. Add new mappings by subclassing MastraAdapter and overriding stream() if you need custom behavior.

Memory

The adapter passes per-request context into Mastra’s memory and tracing, so conversation memory and per-user traces work out of the box. The Mastra memory thread is set to the conversation ID and resource is set to the user ID — no extra wiring needed.

Voice (STT + TTS)

If the wrapped Agent has a voice provider configured, the adapter handles audio messages automatically:

filetype is derived from the incoming AudioStreamConfig.encoding (see Messaging SDK — Audio).

To enable voice, configure a Mastra voice provider when constructing the agent (see Mastra’s voice docs). If voice is absent, audio messages are rejected with a friendly error.

Tracing

When OTEL_EXPORTER_OTLP_ENDPOINT is set, serve() automatically wires Mastra observability so every LLM call and tool invocation produces a trace span. No code changes needed — Astro sets the env var on deployed agents.

Example: an agent with tools

1
import { Agent } from '@mastra/core/agent';
2
import { createTool } from '@mastra/core/tools';
3
import { serve } from '@astropods/adapter-mastra';
4
import { z } from 'zod';
5
6
const lookup = createTool({
7
  id: 'customer_lookup',
8
  description: 'Look up a customer by ID',
9
  inputSchema: z.object({ id: z.string() }),
10
  execute: async ({ context }) => {
11
    return await fetch(`https://api.example.com/customers/${context.id}`).then(r => r.json());
12
  },
13
});
14
15
const agent = new Agent({
16
  name: 'Support Agent',
17
  instructions: 'Help the user troubleshoot. Use customer_lookup when you need account details.',
18
  model: 'anthropic/claude-sonnet-4-6',
19
  tools: { lookup },
20
});
21
22
serve(agent);

Tool names and descriptions show up in the playground via getConfig(). When a tool runs, the user sees Running customer_lookup → Finished customer_lookup as a status indicator.

Local development

$
ast dev project start

ast dev runs the messaging sidecar on localhost:9090, sets GRPC_SERVER_ADDR, and opens the bundled playground at http://localhost:8080. The same serve(agent) code works locally and in production with no changes.

Troubleshooting