Mastra Integration

@sentrial/mastra wraps the generate() and stream() methods of an existing TypeScript Mastra agent. Keep the agent’s model, instructions, tools and memory configuration.

Install

npm install @sentrial/mastra@0.1.3 @sentrial/sdk@0.6.0

Keep your application’s installed @mastra/core and provider packages. The adapter preserves the framework’s method types; package metadata alone does not establish compatibility with every Mastra release. Verify the methods and execution modes your application uses.

Connect your existing agent

This factory takes your existing agent and returns its instrumented proxy. Use the returned agent at the actual call site.

import { instrumentAgent } from '@sentrial/mastra';

type AgentInput = Parameters<typeof instrumentAgent>[0];

export function trackAgent<T extends AgentInput>(agent: T) {
  return instrumentAgent(agent, {
    apiKey: process.env.SENTRIAL_API_KEY,
    apiUrl: process.env.SENTRIAL_API_URL,
    agentName: 'my-agent',
  });
}

For example, replace the reference used by your request handler with trackAgent(yourExistingAgent). Continue passing its usual input and options. Wrapping one agent does not instrument unrelated agents or calls made through the original reference. After an awaited generate() call, use await trackedAgent.sentrialFlush() to drain queued telemetry before a short-lived request or process exits. The wrapper also exposes sentrialShutdown() for application shutdown; do not shut down a shared agent after every request.

Tools and callbacks

Use the tools already registered on the agent. The wrapper records available model steps and tool calls/results and chains the existing callbacks. Keep receipt IDs, retries and pending/rejected tool states intact. A tool result saying that work was queued is not a completed action. Test your existing onStepFinish, onFinish, error and abort callbacks after integration. A callback that performs application work still needs the application’s own error handling.

Streaming

Consume the returned stream before flushing. For a terminal program, the pattern is:

const stream = await trackedAgent.stream(userInput, existingOptions);
try {
  for await (const chunk of stream.textStream) {
    process.stdout.write(chunk);
  }
} finally {
  await trackedAgent.sentrialFlush();
}

Use your installed Mastra version’s stream/result types when adapting this pattern. For an HTTP response, retain the wrapper until the host’s stream completion lifecycle has finished, then flush. A created stream object, approval suspension or cancellation must not be treated as a completed business action.

User and conversation identity

When your agent already uses Mastra memory, memory.resource maps to Sentrial’s user ID and memory.thread maps to its conversation ID. Sentrial groups telemetry using those values; it does not create a memory store or remember messages on the model’s behalf. You can also pass Sentrial-specific identity and metadata in the existing call options:

const options = {
  ...existingOptions,
  sentrial: {
    userId: authenticatedUserId,
    convoId: authorizedConversationId,
  },
};
const result = await trackedAgent.generate(userInput, options);
await trackedAgent.sentrialFlush();

These are application-resolved values; preserve your existing user and conversation authorization. Use the options supported by the Mastra version in your project.

Errors, privacy and cost

The SDK defaults to failSilently: true for telemetry failures. Set it to false during integration checks when you want those failures to surface. Application/provider errors still require normal error handling, and an agent response does not prove successful delivery to Sentrial. Pass pii: true to instrumentAgent to load the workspace’s redaction configuration. Redaction acts on supported captured fields; verify a synthetic sensitive value in your own integration and review PII configuration. Do not assume every arbitrary metadata field is covered. Usage and cost depend on the model information and token counts returned by the framework and Sentrial’s pricing coverage. A pricing entry is not a statement that a provider still serves that model. Keep using your application’s working model configuration.

Verify the integration

Run a test through the returned agent, including one recognizable tool result.
Inspect the run in Telemetry. Compare the response, original tool inputs/results and completion state with your application.
Repeat for streaming if your application uses it; verify callbacks and flushing.
Read back the selected session with the published CLI:

npx --yes --package @sentrial/sdk@0.6.0 sentrial doctor --session <session-id> --json

Use the same workspace/API URL and a key with read access. Trace delivery and signal accuracy are separate checks.

Support agent walkthrough

Inspect recorded Mastra runs with exact tool receipts, recovery and pending outcomes.

TypeScript SDK reference

Client and telemetry APIs.

Getting Started

Core Concepts

SDKs

Integrations

API Reference

Mastra Integration

Install

Connect your existing agent

Tools and callbacks

Streaming

User and conversation identity

Errors, privacy and cost

Verify the integration

Support agent walkthrough

TypeScript SDK reference

​Install

​Connect your existing agent

​Tools and callbacks

​Streaming

​User and conversation identity

​Errors, privacy and cost

​Verify the integration

Support agent walkthrough

TypeScript SDK reference

Install

Connect your existing agent

Tools and callbacks

Streaming

User and conversation identity

Errors, privacy and cost

Verify the integration