Mastra Integration with Future AGI TypeScript Agent Tracing

Integrate Mastra with Future AGI for TypeScript agent observability. Configure trace export using the @traceai/mastra package for LLM monitoring.

Trace Mastra agents and workflows in Future AGI to inspect agent runs, tool calls, and LLM interactions.

Note

This guide targets Mastra v1 (@mastra/core ≥ 1.16). Mastra v1 removed the old telemetry: config key, so the previous FITraceExporter setup no longer exports any spans. Use createFIObservability from @traceai/mastra as shown below. Still on Mastra v0.x? See Legacy (Mastra v0.x) at the bottom.

1. Installation

Install Mastra’s observability packages, the OTLP/protobuf exporter, and @traceai/mastra.

npm install @mastra/core @mastra/observability @mastra/otel-exporter \
            @opentelemetry/exporter-trace-otlp-proto @traceai/mastra

2. Set Environment Variables

Set your Future AGI credentials in the application environment. @traceai/mastra reads process.env; if you keep credentials in a .env file, your runtime or application tooling must load it before createFIObservability() runs.

FI_API_KEY=your-futureagi-api-key
FI_SECRET_KEY=your-futureagi-secret-key

3. Configure Observability

Wire Future AGI into your Mastra instance with createFIObservability. It points the exporter at Future AGI’s collector, authenticates with your keys, and exports traces only (Future AGI’s collector does not accept the OTLP logs signal).

import { Mastra } from "@mastra/core";
import { createFIObservability } from "@traceai/mastra";

export const mastra = new Mastra({
  // ... your agents, workflows, etc.
  observability: createFIObservability({
    serviceName: "traceai-mastra-agent", // appears in the Future AGI trace list
  }),
});

The exporter maps spans to OpenTelemetry gen_ai.* conventions and copies available input and output into the trace. This can include prompts, responses, tool arguments and results.

For sensitive runs, use Mastra’s native tracingOptions.hideInput and hideOutput as shown below. These control input/output capture, not every attribute, metadata field or error. Use Mastra’s SensitiveDataFilter for field-based redaction; field matching does not remove arbitrary sensitive text.

4. Run your Agent

Run your Mastra agent as usual. Traces appear in your Future AGI project under Observe (project traceai-mastra-agent, unless you set projectName).

const agent = mastra.getAgent("yourAgent");
const result = await agent.generate("What's the weather in Bangalore?", {
  tracingOptions: { hideInput: true, hideOutput: true },
});

Note

Short-lived scripts & serverless. Spans are batched, so a process that exits immediately may drop them. Keep a reference to the observability instance and flush before exit:

export const observability = createFIObservability({ serviceName: "traceai-mastra-agent" });
export const mastra = new Mastra({ observability /* , agents, ... */ });

// at the end of your script / request handler:
await observability.shutdown(); // flushes buffered spans

Configuration Options

createFIObservability(options) accepts:

Option	Default	Description
`serviceName`	`"mastra-app"`	Service name; also the default Future AGI project name.
`projectName`	`serviceName`	Future AGI project the traces are filed under.
`projectType`	`"observe"`	`"observe"` for tracing, `"experiment"` for eval runs.
`apiKey`	`process.env.FI_API_KEY`	Future AGI API key.
`secretKey`	`process.env.FI_SECRET_KEY`	Future AGI secret key.
`baseUrl`	`https://api.futureagi.com`	Collector base URL (`/tracer/v1/traces` is appended).
`endpoint`	—	Full traces endpoint URL; overrides `baseUrl`.
`headers`	—	Extra headers merged into the export request.
`excludeSpanTypes`	`[MODEL_CHUNK]`	Mastra span types to drop before export (chunk spans are noise).
`timeout`	`30000`	Export request timeout (ms).
`batchSize`	—	Spans per batch.

If you need to compose the exporter into your own Observability config, use createFIMastraExporter(options) instead — it returns a pre-configured exporter you can drop into new Observability({ configs: { otel: { exporters: [...] } } }).

Legacy (Mastra v0.x)

The old telemetry: + FITraceExporter integration is deprecated and does not work on Mastra v1. If you are still on Mastra v0.x, import it from the /legacy subpath:

import { FITraceExporter, isFISpan } from "@traceai/mastra/legacy";

We recommend upgrading to Mastra v1 and the createFIObservability setup above.

Was this page helpful?

Questions & Discussion