SpecificationMessages

General

Attributes

Span Conventions

Messages and Content

Feedback

Configuration

Messages

Chat APIs exchange lists of messages. An LLM span records the messages sent to the model in llm.input_messages and the messages it returned in llm.output_messages. Each item uses the message.* attributes, flattened with a zero-based index:

  • llm.input_messages.<index>.message.role - Role of the message (e.g., “user”, “assistant”, “system”)
  • llm.input_messages.<index>.message.content - Text content of the message
  • llm.output_messages.<index>.message.role - Role of the output message
  • llm.output_messages.<index>.message.content - Text content of the output message

Message Attributes

Attribute Holds
message.role The role of the message’s author, e.g. "system", "user", "assistant", "tool"
message.content The message’s text, when the message is text only
message.contents The message’s content items, when it has several or their order matters. See Content Items
message.tool_calls Tool calls generated by the model. See Tool Calling
message.tool_call_id On a tool result message, the tool_call.id it answers
message.name On a tool or function result message, the name of the function that produced it

See the Semantic Conventions for the full definitions.

Text Messages

A message that contains only text uses message.content:

{
  "llm.input_messages.0.message.role": "user",
  "llm.input_messages.0.message.content": "Hello, how are you?"
}

Content Items

A message with multiple content items, such as text and an image, uses message.contents. Each item is a message_content object whose message_content.type says what it holds:

message_content.type Content Defined in
"text" Text Multimodal Content
"image" An image, by URL or base64 Multimodal Content
"audio" Audio, by URL or base64 Multimodal Content
"video" Video, by URL or base64 Multimodal Content
"document" A document such as a PDF, an uploaded file, or inline text Multimodal Content
"reasoning" Reasoning or thinking content Reasoning Content
"tool_use" A tool call that must stay ordered relative to adjacent items Tool Calling
{
  "llm.input_messages.0.message.role": "user",
  "llm.input_messages.0.message.contents.0.message_content.type": "text",
  "llm.input_messages.0.message.contents.0.message_content.text": "What objects do you see in this image?",
  "llm.input_messages.0.message.contents.1.message_content.type": "image",
  "llm.input_messages.0.message.contents.1.message_content.image.image.url": "https://example.com/photo.jpg"
}

Tool Role Messages

When a message with message.role set to "tool" represents the result of a function call, the message.name attribute MAY be set to identify which function produced the result. This complements message.tool_call_id, which links the result back to the original tool call request. For example:

{
    "message.role": "tool",
    "message.content": "2001",
    "message.name": "multiply",
    "message.tool_call_id": "call_62136355"
}

See Tool Calling for the complete tool calling flow.

Reasoning Content

Assistant messages from reasoning-capable models may include "reasoning" items in message.contents alongside "text" and tool calls. Use message.contents when the provider returns ordered parts that must be replayed in order, such as reasoning followed by a tool call. The reasoning content convention uses these message content attributes:

  • message_content.type — set to "reasoning" for reasoning/thinking content. This includes Anthropic redacted_thinking blocks.
  • message_content.id — captures provider-assigned content identifiers when they are needed for replay, such as OpenAI ResponseReasoningItem.id.
  • message_content.signature — captures provider signature values verbatim, and captures Gemini thoughtSignature values when they are attached to a non-tool content part such as text.
  • message_content.data — captures Anthropic redacted_thinking.data values verbatim.
  • message_content.encrypted_content — captures OpenAI encrypted_content verbatim.

When a provider attaches the reasoning echo token to a tool call instead of a message content item, use tool_call.reasoning_signature. Gemini uses this for thoughtSignature on functionCall parts. If a tool call must remain ordered relative to reasoning or text content, emit a message.contents item with message_content.type = "tool_use" and the same tool_call.* fields used by message.tool_calls.

When OpenAI returns an array of summary_text items, concatenate them in source order into a single message_content.text value for now. Emit message_content.id when the ResponseReasoningItem.id is present, because stateless replay needs the reasoning item id as well as its encrypted_content.

Audio, video, and document (e.g. PDF or inline text) content items are defined in Multimodal Content. Use message_content.type "audio", "video", or "document" on chat APIs.

OpenAI Responses

{
    "attributes": {
        "openinference.span.kind": "LLM",
        "llm.system": "openai",
        "llm.model_name": "gpt-5",
        "llm.output_messages": [
            {
                "message.role": "assistant",
                "message.contents": [
                    {
                        "message_content.type": "reasoning",
                        "message_content.id": "rs_abc123",
                        "message_content.text": "User asked for the capital of France...\nThe answer is Paris.",
                        "message_content.encrypted_content": "gAAAAA...=="
                    },
                    {
                        "message_content.type": "text",
                        "message_content.text": "Paris."
                    }
                ]
            }
        ],
        "llm.token_count.completion_details.reasoning": 482
    }
}

Anthropic Messages

{
    "attributes": {
        "openinference.span.kind": "LLM",
        "llm.system": "anthropic",
        "llm.model_name": "claude-opus-4-6",
        "llm.output_messages": [
            {
                "message.role": "assistant",
                "message.contents": [
                    {
                        "message_content.type": "reasoning",
                        "message_content.text": "Let me work through this. The capital of France is...",
                        "message_content.signature": "EuYBCkQYAiJA..."
                    },
                    {
                        "message_content.type": "text",
                        "message_content.text": "Paris."
                    }
                ]
            }
        ]
    }
}

For an Anthropic redacted_thinking block, emit a reasoning content item with message_content.data and without message_content.text:

{
    "attributes": {
        "openinference.span.kind": "LLM",
        "llm.system": "anthropic",
        "llm.model_name": "claude-opus-4-6",
        "llm.output_messages": [
            {
                "message.role": "assistant",
                "message.contents": [
                    {
                        "message_content.type": "reasoning",
                        "message_content.data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2..."
                    }
                ]
            }
        ]
    }
}

Gemini Function Calling

Gemini attaches thoughtSignature to content parts such as functionCall and sometimes text. When the signature is on a non-tool content part, capture it on that content item as message_content.signature. When the signature is on a function call, capture it on the corresponding tool call as tool_call.reasoning_signature:

{
    "attributes": {
        "openinference.span.kind": "LLM",
        "llm.system": "google",
        "llm.model_name": "gemini-3-pro",
        "llm.output_messages": [
            {
                "message.role": "model",
                "message.tool_calls": [
                    {
                        "tool_call.function.name": "get_current_temperature",
                        "tool_call.function.arguments": "{\"location\":\"Paris\"}",
                        "tool_call.reasoning_signature": "CiQB..."
                    }
                ]
            }
        ],
        "llm.token_count.completion_details.reasoning": 318
    }
}

Completions API

The legacy completions API (non-chat) has no messages. Its prompts and choices are recorded as lists:

  • llm.prompts.<index>.prompt.text - Input prompt(s) provided to the completions API (e.g., llm.prompts.0.prompt.text, llm.prompts.1.prompt.text)
  • llm.choices.<index>.completion.text - Text choice(s) returned from the completions API (e.g., llm.choices.0.completion.text, llm.choices.1.completion.text)

These attributes use a nested indexed format with discriminated union structure, allowing for future expansion. The nested structure (.prompt.text and .completion.text) mirrors the pattern used for llm.input_messages and llm.output_messages. See the Completions example.