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 with the package versions below. 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 @traceai/mastra with matching Mastra packages and compatible OpenTelemetry peers. Upgrade the three Mastra packages together rather than mixing newer observability packages with an older core.

npm install @traceai/mastra @mastra/core@1.81.0 \
  @mastra/observability@1.23.0 @mastra/otel-exporter@1.5.0 \
  @opentelemetry/api@~1.9.0 @opentelemetry/exporter-trace-otlp-proto@~0.201.1

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 observability = createFIObservability({
  serviceName: "support-agent",
  projectName: "customer-support",
  projectType: "observe",
});

export const mastra = new Mastra({
  // Keep your existing agents, workflows, storage, and other configuration here.
  observability,
});

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 in the customer-support project. If you omit projectName, createFIObservability uses serviceName.

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. Spans are batched, so a process that exits immediately may drop them. After all agent or workflow runs finish, shut down the observability instance created above:

await observability.shutdown();

For a long-running application, call this from your application shutdown lifecycle, not after every request. Shutdown flushes buffered spans and closes the exporter.


Configuration Options

createFIObservability(options) accepts:

OptionDefaultDescription
serviceName"mastra-app"Service name; also the default Future AGI project name.
projectNameserviceNameFuture AGI project the traces are filed under.
projectType"observe""observe" for tracing, "experiment" for eval runs.
apiKeyprocess.env.FI_API_KEYFuture AGI API key.
secretKeyprocess.env.FI_SECRET_KEYFuture AGI secret key.
baseUrlFI_BASE_URL or https://api.futureagi.comCollector 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).
timeout30000Export 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 your existing configuration’s exporters array. Do not add a second observability instance for the same spans. Pass projectName explicitly to this lower-level factory (or set FI_PROJECT_NAME); it does not default the project name to the service name.


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