> ## 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.

# Integrations Overview

> Connect your AI framework to MutagenT for automatic tracing and observability

# Integrations

MutagenT integration packages are **thin adapters** that map your framework's events to MutagenT SDK tracing primitives. They provide automatic tracing with zero manual instrumentation -- every LLM call, chain execution, tool invocation, and graph transition is captured without changing your application code.

## How It Works

Each integration package sits between your AI framework and the MutagenT SDK. The adapter intercepts framework events (callbacks, middleware hooks, or client wrappers) and translates them into SDK span operations. All span lifecycle management, batching, and transport is handled by the SDK -- the integration packages contain no networking code.

<Mermaid>
  flowchart LR
  A\["Your App<br />(LangChain, OpenAI, etc.)"] --> B\["Integration Adapter<br />(callback handler,<br />middleware, wrapper)"]
  B --> C\["@mutagent/sdk<br />(startSpan, endSpan,<br />span batching)"]
  C --> D\["MutagenT Platform<br />(traces, analysis,<br />dashboards)"]
</Mermaid>

## Supported Frameworks

| Framework     | TypeScript Package                             | Pattern                         | Status      |
| ------------- | ---------------------------------------------- | ------------------------------- | ----------- |
| LangChain     | `@mutagent/langchain`                          | Callback handler                | Available   |
| LangGraph     | `@mutagent/langchain` or `@mutagent/langgraph` | Callback handler                | Available   |
| OpenAI        | `@mutagent/openai`                             | Proxy wrapper (`observeOpenAI`) | Available   |
| Vercel AI SDK | `@mutagent/vercel-ai`                          | OTel SpanExporter or Middleware | Available   |
| Mastra        | `@mutagent/sdk` (direct)                       | SDK tracing                     | Coming Soon |

All TypeScript packages require `@mutagent/sdk >=0.1.0` as a peer dependency.

## Two Ways to Integrate

### Option 1: CLI (Recommended)

The CLI can auto-detect your framework by scanning your codebase and generate configuration code:

```bash theme={null}
# Auto-detect framework by scanning your codebase
mutagent explore

# Generate integration code for a specific framework
mutagent integrate langchain
mutagent integrate langgraph
mutagent integrate openai
mutagent integrate vercel-ai

# Auto-detect framework and generate integration
mutagent integrate

# Validate an existing integration setup
mutagent integrate langchain --verify
```

<Tip>
  After `mutagent auth login`, the CLI offers a guided integration path that automatically runs `mutagent explore` and walks you through framework selection, package installation, and code generation.
</Tip>

### Option 2: Manual Setup

Install the integration package and initialize tracing yourself:

<Steps>
  <Step title="Install the SDK and integration package">
    ```bash theme={null}
    npm install @mutagent/sdk @mutagent/langchain
    ```
  </Step>

  <Step title="Initialize tracing at app startup">
    ```typescript theme={null}
    import { initTracing } from '@mutagent/sdk/tracing';

    initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
    ```
  </Step>

  <Step title="Use the integration adapter">
    ```typescript theme={null}
    import { MutagentCallbackHandler } from '@mutagent/langchain';

    const handler = new MutagentCallbackHandler();
    const result = await chain.invoke(input, { callbacks: [handler] });
    ```
  </Step>
</Steps>

## What Gets Traced

<CardGroup cols={2}>
  <Card title="LLM Calls" icon="message">
    Input messages, output text, model name, and provider
  </Card>

  <Card title="Token Usage" icon="coins">
    Prompt tokens, completion tokens, and total token counts
  </Card>

  <Card title="Latency" icon="clock">
    Span duration for every operation, from LLM calls to tool executions
  </Card>

  <Card title="Errors" icon="triangle-exclamation">
    Error messages and status propagation for failed operations
  </Card>

  <Card title="Tool Calls" icon="wrench">
    Tool inputs, outputs, and execution status
  </Card>

  <Card title="Graph Topology" icon="diagram-project">
    Node transitions, edge routing, and conditional branching decisions
  </Card>
</CardGroup>

## Framework Guides

<CardGroup cols={2}>
  <Card title="LangChain" icon="link" href="/integrations/langchain">
    Callback handler for chains, agents, tools, and retrievers
  </Card>

  <Card title="LangGraph" icon="diagram-project" href="/integrations/langgraph">
    Automatic tracing via LangChain callback handler
  </Card>

  <Card title="OpenAI" icon="bolt" href="/integrations/openai">
    Proxy wrapper with full SDK surface preservation
  </Card>

  <Card title="Vercel AI SDK" icon="layer-group" href="/integrations/vercel-ai">
    OTel SpanExporter or middleware for generate and stream
  </Card>

  <Card title="Mastra" icon="wand-magic-sparkles" href="/integrations/mastra">
    SDK-direct tracing for Mastra agent framework
  </Card>
</CardGroup>