# `OzMcp.Structs.SamplingMessage`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/structs/sampling_message.ex#L1)

Helper module used to build `SamplingMessage` structure: a message of the
conversation the server asks the client to complete.

_(MCP protocol: 2025-11-25)_

`content` is one block or a list of blocks. A block is a `TextContent`,
`ImageContent`, `AudioContent`, `ToolUseContent` or `ToolResultContent`
struct, or a map that is already a block.

## Short example:

```elixir
%SamplingMessage{}
  |> SamplingMessage.role(:user)
  |> SamplingMessage.content(%TextContent{} |> TextContent.text("Hello"))
  |> SamplingMessage.build()
```

Result:

```elixir
%{role: "user", content: %{type: "text", text: "Hello"}}
```

`user/1` and `assistant/1` build a message from a text:

```elixir
SamplingMessage.user("Hello") |> SamplingMessage.build()
```

Specification: [SamplingMessage](https://modelcontextprotocol.io/specification/2025-11-25/schema#samplingmessage)

## Fields

| Field | Setter | Type | Required |
|---|---|---|---|
| `role` | `role/2` | role() \| String.t() | no |
| `content` | `content/2` | block() \| list(block()) \| nil | no |
| `_meta` | `_meta/2` | map | no |

# `block`

```elixir
@type block() ::
  %OzMcp.Structs.TextContent{_meta: term(), annotations: term(), text: term()}
  | %OzMcp.Structs.ImageContent{
      _meta: term(),
      annotations: term(),
      data: term(),
      mimeType: term()
    }
  | %OzMcp.Structs.AudioContent{
      _meta: term(),
      annotations: term(),
      data: term(),
      mimeType: term()
    }
  | %OzMcp.Structs.ToolUseContent{
      _meta: term(),
      id: term(),
      input: term(),
      name: term()
    }
  | %OzMcp.Structs.ToolResultContent{
      _meta: term(),
      content: term(),
      isError: term(),
      structuredContent: term(),
      toolUseId: term()
    }
  | map()
```

# `role`

```elixir
@type role() :: :user | :assistant
```

# `t`

```elixir
@type t() :: %OzMcp.Structs.SamplingMessage{
  _meta: map() | nil,
  content: block() | [block()] | nil,
  role: role() | String.t()
}
```

# `assistant`

```elixir
@spec assistant(String.t()) :: %OzMcp.Structs.SamplingMessage{
  _meta: term(),
  content: term(),
  role: term()
}
```

An `assistant` message with a text content.

# `build`

```elixir
@spec build(t()) :: map()
```

# `content`

```elixir
@spec content(t(), block() | [block()] | nil) :: t()
```

# `role`

```elixir
@spec role(t(), role() | String.t()) :: t()
```

# `user`

```elixir
@spec user(String.t()) :: %OzMcp.Structs.SamplingMessage{
  _meta: term(),
  content: term(),
  role: term()
}
```

A `user` message with a text content.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
