Agent engineering team validating production telemetry

SDK setup

Moduna Docs

Instrument AI agents without rearranging your app.

Install the TypeScript or Python SDK, initialize OpenTelemetry once at startup, and attach conversation metadata to agent workflows.

TypeScript setup Python setup

Overview

One telemetry path from prompt to product signal.

Moduna receives traces from the agent stack you already run, then uses conversation and session context to group production behavior into intent-level product evidence.

NodeTypeScript SDKVercel AI SDK and LangChain setup with @moduna/otel.PythonPython SDKLangChain callbacks and manual spans with the moduna package.DevLocal validationLocal logs and local OTLP export before production traffic.

Concepts

The minimum production setup

Create an API key

Create a Moduna project and copy the generated project API key.

Initialize tracing

Initialize the SDK once near application startup before agent workflows run.

Attach context

Pass conversation and session metadata so Moduna can group traces into product-level intent.

Review behavior

Open the dashboard to inspect prompts, completions, token usage, failures, and emerging user needs.

TypeScript

Set up @moduna/otel

Install

bash

npm install @moduna/otel
pnpm add @moduna/otel
bun add @moduna/otel

Environment

bash

export MODUNA_API_KEY="your-moduna-key"

Initialize

import ModunaOTEL from "@moduna/otel";

const otel = new ModunaOTEL({
	agentName: "my-ai-app",
	framework: "vercel-ai-sdk",
});

Vercel AI SDK

const result = await generateText({
	model,
	prompt,
	experimental_telemetry: otel.vercelTelemetry({
		conversationId: "conversation-123",
		sessionId: "session-456",
	}),
});

LangChain

import ModunaOTEL from "@moduna/otel";
import { ChatGoogleGenerativeAI } from "@langchain/google-genai";

const otel = new ModunaOTEL({
	agentName: "my-ai-app",
	framework: "langchain",
});
const handler = otel.langChainHandler();
const model = new ChatGoogleGenerativeAI({ model: "gemini-1.5-pro" });

const result = await model.invoke("Hello, world!", {
	callbacks: [handler],
	metadata: {
		conversationId: "conversation-123",
		sessionId: "session-456",
	},
});

Python

Set up moduna

Install

bash

pip install moduna
uv add moduna

Environment

bash

export MODUNA_API_KEY="md_live_..."

Initialize

python

from moduna import Moduna
from moduna.sdk.tracing import set_conversation_id

otel = Moduna()
otel.init(
	{
		app_name="support-agent",
		framework=Instruments.LANGCHAIN	
	}
)

Direct API key

python

from moduna_otel import ModunaOTEL
from moduna.sdk.tracing import set_conversation_id

otel = ModunaOTEL(
	{
		app_name="support-agent",
		framework=Instruments.LANGCHAIN,
		api_key="md_live_..."
	}
)

Manual instrumentation

python

def call_model(span):
	span.set_attribute("app.operation", "ticket-summary")
	return model.invoke("Summarize this ticket")

result = otel.instrument(
	"support-agent.summary",
	call_model,
	{
		"conversation_id": "conversation-123",
		"session_id": "session-456",
	},
)

Local development

Validate telemetry before production

Local OpenTelemetry logs

const otel = new ModunaOTEL({
	agentName: "my-ai-app",
	enableLocalLogging: true,
	framework: "vercel-ai-sdk",
});

otel.emitLog({
	body: "Generated a response",
	attributes: {
		"ai.operation": "generateText",
	},
});

Local OTLP dev mode

const otel = new ModunaOTEL({
	agentName: "my-ai-app",
	devMode: true,
	framework: "langchain",
});

// Defaults:
// MODUNA_OTEL_ENDPOINT=http://localhost:4317
// MODUNA_OTEL_EXPORT_PROTOCOL=grpc

Next steps

Open the dashboard once spans arrive.

Inspect prompts, completions, token usage, errors, conversation IDs, and session IDs from the same place your team reviews intent clusters.

Read implementation notes