# Mastra

Instrument Mastra AI agents with OpenTelemetry for Kopai

# Integration

Add observability to your [Mastra](https://mastra.ai) AI agents using [Mastra's OpenTelemetry exporter](https://mastra.ai/docs/observability/tracing/exporters/otel). Capture the full lifecycle of agent runs — from LLM calls and tool executions to workflow steps — and inspect them in Kopai.

## Prerequisites

- Node.js 20+
- API key from a model provider (e.g. Anthropic, OpenAI)
- Kopai running locally:

**npm:**

```bash
npx @kopai/app start
```

**pnpm:**

```bash
pnpm dlx @kopai/app start
```

**yarn:**

```bash
yarn dlx @kopai/app start
```

## Create a Mastra Project

Scaffold a new project with the Mastra CLI:

**npm:**

```bash
npx create-mastra@latest
```

**pnpm:**

```bash
pnpm create mastra@latest
```

**yarn:**

```bash
yarn create mastra
```

Set your model provider key in `.env`:

```bash
ANTHROPIC_API_KEY=<your-api-key>
```

## Add an Agent

Define an agent in `src/mastra/agents/travelAgent.ts`:

```typescript
import { anthropic } from "@ai-sdk/anthropic";
import { Agent } from "@mastra/core/agent";

export const travelAgent = new Agent({
  name: "travel-agent",
  instructions:
    "You are a friendly travel assistant. " +
    "Help users plan trips, suggest destinations, and answer questions about travel logistics.",
  model: anthropic("claude-haiku-4-5-20251001"),
});
```

## Enable Observability

Install the OTel exporter and observability packages:

**npm:**

```bash
npm install @mastra/observability @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
```

**pnpm:**

```bash
pnpm add @mastra/observability @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
```

**yarn:**

```bash
yarn add @mastra/observability @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
```

Register the agent and wire up telemetry in `src/mastra/index.ts`:

```typescript
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { OtelExporter } from "@mastra/otel-exporter";
import { travelAgent } from "./agents/travelAgent";

export const mastra = new Mastra({
  agents: { travelAgent },
  observability: new Observability({
    configs: {
      otel: {
        serviceName: "my-mastra-app",
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: "http://localhost:4318/v1/traces",
              },
            },
          }),
        ],
      },
    },
  }),
});
```

This sends all agent and tool traces to Kopai's local OTLP endpoint on port 4318.

## Run and Verify

Start the Mastra dev server:

**npm:**

```bash
npm run dev
```

**pnpm:**

```bash
pnpm dev
```

**yarn:**

```bash
yarn dev
```

Open the playground at `http://localhost:4111` and send a few messages to your agent.

**Note:** Traces are sent to Kopai, not Mastra Studio's built-in trace viewer. Use the Kopai CLI or dashboard at `http://localhost:8000` to inspect them.

Verify that traces arrived using the Kopai CLI:

**npm:**

```bash
# List recent traces from your agent
npx @kopai/cli traces search --service my-mastra-app --json

# Inspect a specific trace (copy a traceId from above)
npx @kopai/cli traces get <traceId> --json
```

**pnpm:**

```bash
# List recent traces from your agent
pnpm dlx @kopai/cli traces search --service my-mastra-app --json

# Inspect a specific trace (copy a traceId from above)
pnpm dlx @kopai/cli traces get <traceId> --json
```

**yarn:**

```bash
# List recent traces from your agent
yarn dlx @kopai/cli traces search --service my-mastra-app --json

# Inspect a specific trace (copy a traceId from above)
yarn dlx @kopai/cli traces get <traceId> --json
```

Each trace contains spans for the full agent interaction — LLM calls, tool executions, and decision steps.

## Sending to Kopai.app in the cloud

Swap the `OtelExporter` config in `src/mastra/index.ts` to point at `https://otlp-http.kopai.app` with an auth header:

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: "https://otlp-http.kopai.app",
      headers: {
        authorization: "Bearer YOUR_BACKEND_TOKEN",
      },
    },
  },
});
```

## Working Example

For a complete working example with traces, logs, and metrics:

**[Mastra Example](https://github.com/kopai-app/kopai-integration-examples/tree/main/mastra)**