# Messages

Chat APIs exchange lists of messages. An [LLM span](https://openinf.dev/spec/spans/llm.html.md) 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](https://openinf.dev/spec/attributes/conventions.html.md#flattening) 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](https://openinf.dev/spec/content/messages.html.md#content-items) |
| `message.tool_calls` | Tool calls generated by the model. See [Tool Calling](https://openinf.dev/spec/content/tool-calling.html.md) |
| `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](https://openinf.dev/spec/attributes/semantic-conventions.html.md#message) for the full definitions.

## Text Messages

A message that contains only text uses `message.content`:

```json
{
  "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](https://openinf.dev/spec/content/multimodal.html.md#text-content) |
| `"image"` | An image, by URL or base64 | [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#image-content) |
| `"audio"` | Audio, by URL or base64 | [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#audio-content) |
| `"video"` | Video, by URL or base64 | [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#video-content) |
| `"document"` | A document such as a PDF, an uploaded file, or inline text | [Multimodal Content](https://openinf.dev/spec/content/multimodal.html.md#document-content) |
| `"reasoning"` | Reasoning or thinking content | [Reasoning Content](https://openinf.dev/spec/content/messages.html.md#reasoning-content) |
| `"tool_use"` | A tool call that must stay ordered relative to adjacent items | [Tool Calling](https://openinf.dev/spec/content/tool-calling.html.md#ordered-tool-use-content-items) |

```json
{
  "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:

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

See [Tool Calling](https://openinf.dev/spec/content/tool-calling.html.md) 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](https://openinf.dev/spec/content/multimodal.html.md). Use `message_content.type` `"audio"`, `"video"`, or `"document"` on chat APIs.

### OpenAI Responses

```json
{
    "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

```json
{
    "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`:

```json
{
    "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`:

```json
{
    "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](https://openinf.dev/spec/spans/llm.html.md#completions).
