Documentation Index Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
Use this file to discover all available pages before exploring further.
Your First Trace This guide walks you through tracing your first LLM call. By the end, you will see real trace data in your MutagenT dashboard.
Prerequisites
MutagenT CLI installed and authenticated (mutagent auth login)
An API key (mt_ prefix) — see API Keys
An existing project that uses an LLM framework
How Tracing Works Step 1: Generate Integration Code Run mutagent integrate in your project directory. The CLI detects your framework and generates the code you need.
OpenAI
LangChain
Vercel AI
LangChain
mutagent integrate openai
The CLI outputs the integration code and the package to install. Follow the instructions it provides.
Step 2: Install the Integration Package Install the integration package for your framework.
OpenAI
LangChain
Vercel AI
LangGraph
bun add @mutagent/openai @mutagent/sdk
Step 3: Set Your API Key Set the MUTAGENT_API_KEY environment variable. The SDK reads it automatically.
# .env MUTAGENT_API_KEY = mt_xxxxxxxxxxxx
If MUTAGENT_API_KEY is set in your environment, tracing initializes lazily on the first span — no explicit initTracing() call needed. For more control, call initTracing() explicitly at startup.
Step 4: Add the Integration Code Add the generated integration code to your LLM calls. Each integration follows the same pattern: initialize tracing, then use the framework adapter.
OpenAI (TypeScript)
OpenAI (Python)
Anthropic (Python)
LangChain
Vercel AI
Mastra
import OpenAI from 'openai' ; import { observeOpenAI } from '@mutagent/openai' ; import { initTracing } from '@mutagent/sdk/tracing' ; // Initialize tracing (or set MUTAGENT_API_KEY env var for auto-init) initTracing ({ apiKey: process . env . MUTAGENT_API_KEY ! }); // Wrap the OpenAI client for automatic tracing const client = observeOpenAI ( new OpenAI ({ apiKey: process . env . OPENAI_API_KEY , })); const response = await client . chat . completions . create ({ model: 'gpt-4o' , messages: [{ role: 'user' , content: 'What is observability?' }], });
pip install mutagent-openai
import os from mutagent.tracing import init_tracing from mutagent_openai import MutagentOpenAI init_tracing( api_key = os.environ[ "MUTAGENT_API_KEY" ]) client = MutagentOpenAI( api_key = os.environ[ "OPENAI_API_KEY" ]) response = client.chat.completions.create( model = "gpt-4o" , messages = [{ "role" : "user" , "content" : "What is observability?" }], ) print (response.choices[ 0 ].message.content)
pip install mutagent-anthropic
import os from anthropic import Anthropic from mutagent_anthropic import wrap_anthropic from mutagent.tracing import init_tracing init_tracing( api_key = os.environ[ "MUTAGENT_API_KEY" ]) client = wrap_anthropic(Anthropic()) msg = client.messages.create( model = "claude-opus-4-5" , max_tokens = 1024 , messages = [{ "role" : "user" , "content" : "What is observability?" }], ) print (msg.content[ 0 ].text)
import { initTracing } from '@mutagent/sdk/tracing' ; import { MutagentCallbackHandler } from '@mutagent/langchain' ; import { ChatOpenAI } from '@langchain/openai' ; initTracing ({ apiKey: process . env . MUTAGENT_API_KEY ! }); const handler = new MutagentCallbackHandler (); const llm = new ChatOpenAI ({ model: 'gpt-4o' }); const response = await llm . invoke ( 'What is observability?' , { callbacks: [ handler ], });
import { initTracing } from '@mutagent/sdk/tracing' ; import { createMutagentMiddleware } from '@mutagent/vercel-ai' ; import { wrapLanguageModel , generateText } from 'ai' ; import { openai } from '@ai-sdk/openai' ; initTracing ({ apiKey: process . env . MUTAGENT_API_KEY ! }); const model = wrapLanguageModel ({ model: openai ( 'gpt-4o' ), middleware: createMutagentMiddleware (), }); const { text } = await generateText ({ model , prompt: 'What is observability?' , });
// mastra.config.ts import { initTracing } from '@mutagent/sdk/tracing' ; import { defineConfig } from '@mastra/core' ; initTracing ({ apiKey: process . env . MUTAGENT_API_KEY ! }); export default defineConfig ({ agents: { 'my-agent' : { name: 'My Agent' , model: 'gpt-4o' , instructions: 'You are a helpful assistant.' , }, } , }) ;
initTracing() OptionsOption Type Default Description apiKeystring— Required. Your MutagenT API key (mt_ prefix)endpointstringhttps://api.mutagent.ioAPI endpoint URL environmentstring— Environment name (e.g., production, staging) batchSizenumber10Number of spans to buffer before flushing flushIntervalMsnumber5000Flush interval in milliseconds debugbooleanfalseLog span start/end events to console sourcestring"sdk"Source identifier for traces
Step 5: Run Your Application Run your application as you normally would. The integration sends traces to MutagenT automatically in the background, batching spans and flushing every 5 seconds or when 10 spans accumulate.
Step 6: View Your Traces Open the MutagenT dashboard at app.mutagent.io to see your traces, or use the CLI.
You should see your LLM call with:
Input prompt and output response
Model used and token counts
Latency and timing data
Span hierarchy (parent/child relationships)
Traces are sent asynchronously in batches and typically appear within a few seconds. If you do not see traces, check that your MUTAGENT_API_KEY is valid with mutagent auth status.
Graceful Shutdown For server applications or scripts that exit after tracing, call shutdownTracing() to flush remaining buffered spans:
import { shutdownTracing } from '@mutagent/sdk/tracing' ; // Before your process exits await shutdownTracing ();
Next Steps
Manage Prompts Version and organize your prompts
Run Evaluations Measure prompt quality with metrics
Optimize Automatically improve your prompts
All Integrations See all supported frameworks
