Conversations and messages

Every interaction with a large language model (LLM) follows a pattern: someone sends a message, the model responds. Blue Guardrails captures these exchanges to analyze what the model said and whether it's accurate.

Understanding this structure helps you troubleshoot issues and interpret your data.

Messages are the building blocks

A message is a single piece of content in an LLM interaction. Think of it like an email or a chat bubble. Each message has a sender (its "role") and content.

LLM messages differ from typical chat in two ways. First, a single message can mix text, images, and tool calls. Second, messages include machine-generated content like tool invocations.

Message roles

Every message has a role that identifies its source. Blue Guardrails recognizes four roles.

System messages contain instructions that guide model behavior. They set the context: who the assistant is, what it should do, what constraints apply. System messages typically appear at the start of a conversation.

User messages contain input from people. This includes questions, commands, follow-ups, and any content the human provides.

Assistant messages contain model output. This is what the LLM generates in response to user messages. When you're detecting hallucinations, assistant messages are what you're evaluating.

Tool messages contain results from tool execution. When a model calls a tool, the result comes back as a tool message. These messages provide ground truth—verified facts the model should incorporate into its response.

Message parts

Messages contain one or more parts. Each part is a piece of content with its own type.

Text is the most common part type. It's plain text content—questions, answers, explanations.

Tool calls appear when an assistant decides to invoke a tool. The part includes the tool name and arguments the model wants to pass.

Tool call responses contain the result of executing a tool. They include an ID that links them back to the original tool call.

Reasoning parts capture the model's chain-of-thought when exposed. Some models share their reasoning process separately from their final answer.

Multimodal content includes images, audio, and files. These parts contain binary data or references to external resources.

A single assistant message might contain both text and a tool call. Or it might include reasoning followed by a final answer. The parts-based structure lets Blue Guardrails analyze each component separately.

Conversations tie messages together

A conversation is a sequence of messages. It represents one complete interaction session—everything from the first user message to the final assistant response.

Conversations maintain context. When you ask a follow-up question, the model sees everything that came before. This history shapes how the model interprets your request and what it knows when generating a response.

Two patterns dominate LLM interactions: simple chat and agent trajectories.

Chat conversations

In a chat, messages alternate between user and assistant. The user asks a question, the assistant responds, the user asks another question, and so on.

┌─────────────────────────────────────┐
│ User: What's the capital of France? │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Assistant: Paris is the capital.    │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ User: What's its population?        │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Assistant: About 2.1 million...     │
└─────────────────────────────────────┘

Each user message builds on the previous exchange. The assistant's response to "What's its population?" makes sense only because both parties know "its" refers to Paris.

Agent trajectories

Agents follow a more complex pattern. The model doesn't just respond—it takes actions, observes results, and reasons about what to do next.

An agent trajectory might look like this:

┌─────────────────────────────────────┐
│ User: What's the weather in Paris?  │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Assistant: [tool_call: get_weather] │
│            location: "Paris"        │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Tool: {"temp": 18, "sky": "cloudy"} │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Assistant: It's 18°C and cloudy     │
│            in Paris right now.      │
└─────────────────────────────────────┘

The assistant's first response is a tool call, not text. Only after receiving the result does it respond to the user. Some trajectories involve multiple tool calls before the final response.

This pattern is central to hallucination detection. When an assistant claims "It's 18°C and cloudy," you can verify that claim against the tool result in the conversation history. The structured data is right there.

Message grouping

Blue Guardrails assembles conversations from the traces your application sends. The process works like this:

First, it looks for a conversation ID. If your tracing data includes gen_ai.conversation.id, messages sharing that ID belong together.

If there's no conversation ID, Blue Guardrails falls back to the trace ID. All messages from spans in the same trace form a conversation.

Tool calls get linked to their responses using the call ID. When an assistant message contains a tool call with id: "call_abc123", Blue Guardrails matches it to the tool message with the same ID.

Messages are ordered by when they arrived. This recreates the sequence your application sent to the model.

Relevance to hallucination detection

Hallucination detection evaluates whether assistant claims are grounded in available information. That evaluation needs context.

When you check a response for accuracy, you need to know what the model "knew" when generating it. The conversation history provides this context.

Consider an assistant that says "The report shows 15% growth." To verify this, Blue Guardrails needs to see what report data appeared in the conversation. Did a tool return that figure? Did the user provide it? The answer determines whether the claim is grounded or fabricated.

Tool results are especially valuable. They provide machine-readable ground truth. If a database query returns {"growth": 0.15} and the assistant says "15% growth," that's verifiable. If the assistant says "20% growth," that's a detectable hallucination.

The structured message model makes this analysis possible. Each part can be examined. Each role provides context about who said what. And the conversation sequence shows what information was available at each point.

For more on how Blue Guardrails captures this data, see Tracing and OpenTelemetry.