Images in Traces

Capture the images sent to your models, and add images to any trace or span

Overview

Confident AI captures the images in your traces and displays them inline in a span's input or output, right where the message or string references them. This is useful for vision use cases, such as chart and screenshot analysis or visual question answering, where the image is as much a part of the input as the text.

Images get onto a trace in two ways:

Automatically, from the model calls recorded by a supported integration
Manually, by adding Media at the span or trace level

Any image/* type is supported, such as PNG, JPEG, GIF, and WebP.

Capture Images from Model Calls

If you're using a supported integration, you don't need to do anything extra. Send images to your model the way your provider SDK expects them, and as long as init() has run, they're captured with the rest of the messages:

main.py

import base64
from pathlib import Path

from confident_trace import init, shutdown
from openai import OpenAI

init()
client = OpenAI()

image = base64.b64encode(Path("chart.png").read_bytes()).decode()

try:
    response = client.chat.completions.create(
        model="gpt-4.1",
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": "What does this chart show?"},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{image}"},
                },
            ],
        }],
    )
    print(response.choices[0].message.content)
finally:
    shutdown()

src/index.ts

import { readFileSync } from "node:fs";
import OpenAI from "openai";
import { init } from "confident-trace";

const runtime = init();
const client = new OpenAI();

const image = readFileSync("chart.png").toString("base64");

try {
  const response = await client.chat.completions.create({
    model: "gpt-4.1",
    messages: [{
      role: "user",
      content: [
        { type: "text", text: "What does this chart show?" },
        { type: "image_url", image_url: { url: `data:image/png;base64,${image}` } },
      ],
    }],
  });
  console.log(response.choices[0]?.message.content);
} finally {
  await runtime.shutdown();
}

Remember to launch your entry point with the Node preload so the OpenAI call is instrumented.

Here, the OpenAI integration records the image_url part on the LLM span, and the chart is displayed inline in the span's input. Every other supported integration works the same way, so an Anthropic image block, a Gemini inline image, or a LangChain image content block is captured just like this.

Add Images to Traces & Spans

For images that aren't part of a model call, such as a screenshot your agent took, a chart a tool generated, or a file a user uploaded, wrap the file in Media and add it at the span or trace level. An image can be part of a string, or a value on its own:

main.py

from confident_trace import Media, init, span, update_span, shutdown

init()

@span(type="tool")
def review_chart(path: str):
    chart = Media.from_file(path)
    update_span(input=f"Does {chart} match the report?")
    return "The chart matches the report."

try:
    review_chart("chart.png")
finally:
    shutdown()

Here, the image is placed inside the span's input string, so the span displays the question with the chart inline, right where it's referenced. To make an image a value on its own, pass it directly instead, such as update_span(output=chart).

update_trace() takes images the same way, if you'd rather put the image on the trace's input or output. To create an image from a URL, bytes, or base64 instead of a local file, see Create Media.

src/index.ts

import { Media, init, span, updateSpan } from "confident-trace";

const runtime = init();

const reviewChart = span({ name: "review_chart", type: "tool" }, (path: string) => {
  const chart = Media.fromFile(path);
  updateSpan({ input: `Does ${chart} match the report?` });
  return "The chart matches the report.";
});

try {
  reviewChart("chart.png");
} finally {
  await runtime.shutdown();
}

updateTrace() takes images the same way, if you'd rather put the image on the trace's input or output. To create an image from a URL, bytes, or base64 instead of a local file, see Create Media.

Next Steps

With images in your traces, see how PDFs and audio are captured.

PDFs

Capture the PDFs sent to your models, and add documents to any trace or span.

Audio

Add audio to your messages and play it back on each message in a trace.

Ready to monitor AI in production?Connect traces, alerts, dashboards, and evals in one production workflowBook a demo

Last updated on October 9, 2026