Custom agents (OpenTelemetry Integration)

Monte Carlo works with any agent instrumented with OpenTelemetry, in any language or framework. Point your OTLP exporter at your Agent Observability Data Platform and your agent gets everything in Agent Trust: Bayes finds and fixes what's breaking it.

Snowflake Cortex and Databricks AI/BI Genie & AgentBricks agents don't require OpenTelemetry instrumentation. Monte Carlo reads their traces through your existing warehouse connection — see Platform-native agents.

Before you start

1. Deploy the Agent Observability Data Platform. Every OpenTelemetry agent sends traces to it, so it comes first.

See Agent Observability Data Platform for architecture and prerequisites.

2. Pick your path.

1. Point your exporter at the Data Platform

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<your-collector-endpoint>
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-mcd-id=<your-api-id>,x-mcd-token=<your-api-token>"
export OTEL_SERVICE_NAME=<your-agent-name>

• Endpoint: your Data Platform's collector endpoint. For Monte Carlo-hosted deployments, use the endpoint Monte Carlo provides.
• Credentials: you get x-mcd-id / x-mcd-token when you connect the platform to Monte Carlo. For Monte Carlo-hosted deployments, use the credentials Monte Carlo provides. You can also set them as MCD_DEFAULT_API_ID / MCD_DEFAULT_API_TOKEN.
• Use the _TRACES_ variables, not the bare OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_HEADERS. The bare versions also redirect the metrics and logs exporters, which Monte Carlo doesn't accept, so the export fails.

2. Capture prompts and completions

Monte Carlo reads prompts and completions from gen_ai.* span attributes — OpenTelemetry's standard GenAI semantic conventions, not a Monte Carlo-specific format. Most instrumentation doesn't capture message content by default, so turn it on to get the full capabilities of Agent Trust:

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT=1024

Don't skip the attribute limit. GenAI spans regularly go past OpenTelemetry's default of 128 attributes, and anything over the limit is dropped silently, with no error.

3. Group conversations and tag workflows

• Conversations: set gen_ai.conversation.id on every span in a conversation, not just the first. Reinforcement Loop and Conversation Clusters both work on conversations.
• Workflows and tasks: set montecarlo.workflow and montecarlo.task with your language's OpenTelemetry API, the same way you'd set any custom span attribute.

4. Confirm traces are arriving

Run your agent, then open Agents. Once traces are written, the agent appears on its own; check its Summary or Activity tab for incoming traces.

Not showing up? Check, in order:

1. You used OTEL_EXPORTER_OTLP_TRACES_*, not the bare OTEL_EXPORTER_OTLP_* variables.
2. The endpoint and credentials match your Data Platform.
3. Traces arrive but prompts or completions are missing: content capture is off, or spans are over the attribute limit (step Capture prompts and completions).
4. Each turn shows up as its own conversation: gen_ai.conversation.id isn't set on every span (step Group conversations and tag workflows).

Already exporting to another backend

If you already send traces to CloudWatch, Application Insights, or another backend, add Monte Carlo as a second exporter. Don't replace your existing one.

The environment variables in step 1 configure only one exporter. Set up the Monte Carlo exporter in code or in your OpenTelemetry Collector, with its own endpoint and its own headers.

Don't put x-mcd-id / x-mcd-token in shared header configuration such as OTEL_EXPORTER_OTLP_HEADERS or OTEL_EXPORTER_OTLP_TRACES_HEADERS. Shared headers go to every exporter, so your Monte Carlo credentials would leak to your other backend.

Next steps

• Connect your agent's repository (GitHub, GitLab, or Azure DevOps) so Bayes can name the root cause and propose fixes as draft PRs. See Connecting your agent's definitions.
• Review findings on your agent's Reinforcement loop tab. See Reinforcement Loop.
• See what users ask and where the agent fails in Conversation Clusters.