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:
| 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 | FI_BASE_URL or 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 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.
Questions & Discussion