Get Started
Agent frameworks

VoltAgent

Capture traces from VoltAgent agents over OTLP

Choose a setup method

Method Use it when
Voxmith skill You want your coding agent to inspect the app, make the change, and verify it.
Voxmith SDK You want explicit control over the interaction boundaries and fields.
OpenTelemetry The framework already emits useful spans or you operate an OTel pipeline.

Start with one method for a call path. Combining SDK tracking with framework OpenTelemetry on the same call can create duplicate interactions.

Recommended. Choose this path when you want your coding agent to inspect the project, select a supported transport, make the smallest instrumentation change, send a test event, and verify that it reached Voxmith.

Install the skill once in your coding-agent environment:

npx skills add Voxmith/skills --skill voxmith

Run the framework-specific prompt below from the application root. Review the resulting diff before deploying it.

Use the voxmith skill to add Voxmith analytics to this VoltAgent application.
Org ID: your-org-id
Instrument the real agent.generateText() path and verify one fresh interaction.

Manual setup: Voxmith SDK

npm install voxmithai
import * as voxmith from 'voxmithai';

voxmith.init('your-org-id');
const interaction = voxmith.begin({ userId: 'u-42', agentName: 'voltagent-support', input: prompt });
try {
  const result = await agent.generateText(prompt);
  interaction.end(result.text);
} catch (error) {
  interaction.end(String(error), false);
  throw error;
} finally {
  await voxmith.shutdown();
}

Manual setup: OpenTelemetry

VoltAgent ships its own observability layer. Plug an OTLP exporter into VoltAgentObservability, then pass userId / conversationId per call.

1. Install

Already have @voltagent/core and @opentelemetry/exporter-trace-otlp-proto? Skip.

No setup yet?

npm install @voltagent/core @opentelemetry/exporter-trace-otlp-proto @opentelemetry/sdk-trace-node

2. Wire the OTel exporter pointing at Voxmith

Already have VoltAgentObservability? Append a span processor for Voxmith to the existing spanProcessors array:

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';

const voxmithProcessor = new BatchSpanProcessor(
  new OTLPTraceExporter({
    url: 'https://otel.voxmith.com/v1/traces',
    headers: { 'X-Voxmith-Org-ID': process.env.VOXMITH_ORG_ID! },
  }),
);

// Inside your existing VoltAgentObservability:
spanProcessors: [
  // ...your existing processors,
  voxmithProcessor,
]

No Observability yet? Full setup:

import { VoltAgent, VoltAgentObservability } from '@voltagent/core';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';

const exporter = new OTLPTraceExporter({
  url: 'https://otel.voxmith.com/v1/traces',
  headers: { 'X-Voxmith-Org-ID': process.env.VOXMITH_ORG_ID! },
});

const observability = new VoltAgentObservability({
  spanProcessors: [new BatchSpanProcessor(exporter)],
});

new VoltAgent({ agents: { agent }, observability });

3. Pass userId / conversationId per call

await agent.generateText('Hello', {
  userId: 'user-42',
  conversationId: 'conv-abc123',
});

VoltAgent maps userId → user.id and conversationId → conversation.id on every span: both read directly by Voxmith for user / session grouping.

What appears in Voxmith

  • Conversations grouped by conversationId.
  • User-level analytics grouped by userId.
  • Events for every exported span.

Verify

Run one agent.generateText call, then open Events and confirm the span arrived.

Troubleshooting

  • Confirm your BatchSpanProcessor is attached to VoltAgentObservability.
  • Confirm X-Voxmith-Org-ID is set on the exporter.
  • Confirm userId and conversationId are passed per call.

References

Next steps

  • Conversations: review the complete VoltAgent interaction.
  • Events: inspect agent, model, and tool activity.
  • Intents: organize production conversations by what users wanted.