Enum ContentPart 

#[non_exhaustive]
pub enum ContentPart {
    Text {
        text: String,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    Image {
        source: MediaSource,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    Audio {
        source: MediaSource,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    Video {
        source: MediaSource,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    Document {
        source: MediaSource,
        name: Option<String>,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    Thinking {
        text: String,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    RedactedThinking {
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    Citation {
        snippet: String,
        source: CitationSource,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    ToolUse {
        id: String,
        name: String,
        input: Value,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    ImageOutput {
        source: MediaSource,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    AudioOutput {
        source: MediaSource,
        transcript: Option<String>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
    ToolResult {
        tool_use_id: String,
        name: String,
        content: ToolResultContent,
        is_error: bool,
        cache_control: Option<CacheControl>,
        provider_echoes: Vec<ProviderEchoSnapshot>,
    },
}

One block of content inside a Message.

The enum is #[non_exhaustive] so future variants don’t break user match arms. New modalities or capability blocks land here as additional variants — codecs reach 100% IR coverage by either emitting native wire shape or a LossyEncode warning for each.

Every input-side variant carries an Option<CacheControl> field — operators mark a block as cached and codecs that support per-block caching (Anthropic, Bedrock-on-Anthropic) emit the directive natively. Other codecs emit LossyEncode. The ToolUse variant — the assistant’s outbound call — does not carry caching: the model emits it, there is nothing to cache.

Every variant also carries provider_echoes: Vec<ProviderEchoSnapshot> — vendor-keyed opaque round-trip tokens this part must echo back on the next turn (Gemini 3.x thought_signature, Anthropic signature, OpenAI Responses encrypted_content, …). Defaults to empty. Codecs only read / write entries matching their own Codec::name. See ProviderEchoSnapshot for the cross-vendor design.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Text

Plain UTF-8 text — the primary medium.

Fields

text: String

The text payload.

cache_control: Option<CacheControl>

Per-block cache directive.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens (Gemini emits thought_signature on text parts in reasoning turns).

Image

An image input.

Fields

source: MediaSource

Where the image bytes live.

cache_control: Option<CacheControl>

Per-block cache directive.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

Audio

An audio input.

Fields

source: MediaSource

Where the audio bytes live.

cache_control: Option<CacheControl>

Per-block cache directive.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

Video

A video input.

Fields

source: MediaSource

Where the video bytes live.

cache_control: Option<CacheControl>

Per-block cache directive.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

Document

A document input (PDF, plain-text file, etc.).

Fields

source: MediaSource

Where the document bytes live.

name: Option<String>

Display name shown to the model (e.g. "contract.pdf"). Optional — codecs that require a name supply a stable derivation when absent.

cache_control: Option<CacheControl>

Per-block cache directive.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

Thinking

A reasoning / extended-thinking block produced by the assistant before the user-facing reply.

Surfaced as its own variant (rather than mixed with Text) so recipes can show / hide / cache reasoning independently. Order relative to Text parts is preserved — vendors that rely on chain-of-thought integrity (Anthropic thinking, Gemini 3.x thought_signature) require the original block order on follow-up turns.

Vendor opaque tokens (Anthropic signature, Gemini thought_signature, OpenAI Responses reasoning-item encrypted_content) ride on provider_echoes.

Fields

text: String

The reasoning text.

cache_control: Option<CacheControl>

Per-block cache directive.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

RedactedThinking

A reasoning block the safety system flagged for redaction. Carries no harness-readable text — the entire block is an opaque round-trip artifact preserved in provider_echoes.

Emitted by Anthropic Claude 3.7 Sonnet only; Claude 4.x and later do not produce this variant. Codecs that don’t recognise it on encode emit LossyEncode (invariant 6 — the prior silent-drop is replaced by a typed channel).

Fields

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens. Anthropic emits { "data": "<base64>" } here under provider key "anthropic-messages".

Citation

A grounded citation produced by the assistant — the snippet is the verbatim cited text; source describes provenance.

Fields

snippet: String

The cited substring as it appears in the assistant’s reply.

source: CitationSource

Where the snippet came from.

cache_control: Option<CacheControl>

Per-block cache directive.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

ToolUse

A tool call emitted by the assistant. The harness dispatches it. Tool calls are model output — they do not carry a cache directive (the model emits each call afresh).

Vendor opaque tokens (Gemini 3.x thought_signature on functionCall parts, OpenAI Responses function_call.id) ride on provider_echoes. Missing the Gemini token on the first functionCall of a step yields HTTP 400 on the next turn — codecs MUST round-trip it.

Fields

id: String

Stable ID matched against the corresponding ToolResult.

name: String

Tool name to dispatch (must exist in the active ToolRegistry).

input: Value

JSON arguments for the tool — must validate against the tool’s input_schema before dispatch.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

ImageOutput

An image the assistant produced (vendor-managed image generation: OpenAI image_generation_call.result, Gemini inline_data parts on the model output, …). Distinct from Self::Image which is a user-supplied input.

Output blocks have no cache directive — they are produced fresh per turn.

Fields

source: MediaSource

Where the produced image bytes live. Most vendors return inline base64 (MediaSource::Base64); some return a hosted URL.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

AudioOutput

Audio the assistant produced (text-to-speech reply). Distinct from Self::Audio which is a user-supplied input.

Fields

source: MediaSource

Where the produced audio bytes live.

transcript: Option<String>

Optional textual transcript the vendor returned alongside the audio. Surfaced separately so callers can route transcript text through the operator’s logging channel without re-decoding the audio.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

ToolResult

The harness’s reply to a previous ToolUse call.

Both tool_use_id and name are carried because providers disagree on which one keys correlation: Anthropic / OpenAI / Bedrock use the id (tool_use_id / tool_call_id / toolUseId), while Gemini’s functionResponse keys by name. Carrying both keeps the IR provider-neutral — codecs use whichever their wire format requires without needing the agent harness to know.

Fields

tool_use_id: String

The originating ToolUse::id.

name: String

The originating ToolUse::name. Required for Gemini’s functionResponse wire shape; ignored by codecs that correlate purely by id.

content: ToolResultContent

Result payload — either a string or structured data.

is_error: bool

True if the tool reported a failure.

cache_control: Option<CacheControl>

Per-block cache directive. Tool result blocks often carry the heaviest payloads; caching them across turns is the canonical RAG-cache pattern.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens.

Implementations

impl ContentPart

pub fn text(text: impl Into<String>) -> Self

Build a text part from anything string-like.

pub fn image(source: MediaSource) -> Self

Build an image part from a media source.

pub fn audio(source: MediaSource) -> Self

Build an audio part from a media source.

pub fn video(source: MediaSource) -> Self

Build a video part from a media source.

pub fn document(source: MediaSource, name: Option<String>) -> Self

Build a document part from a media source.

pub fn thinking(text: impl Into<String>) -> Self

Build a thinking part with no opaque tokens. Codecs attach vendor opaque tokens via Self::with_provider_echo.

pub fn redacted_thinking() -> Self

Build a redacted-thinking part. Anthropic Claude 3.7 Sonnet emits these for safety-flagged reasoning; the codec attaches the opaque data payload via Self::with_provider_echo.

pub const fn cache_control(&self) -> Option<&CacheControl>

Borrow the cache directive on this part, when any is set. Returns None for assistant-output variants (ToolUse, ImageOutput, AudioOutput, RedactedThinking) — they are produced fresh per turn and have nothing to cache.

pub fn provider_echoes(&self) -> &[ProviderEchoSnapshot]

Borrow this part’s vendor opaque round-trip tokens. Codecs use this to recover their own blob (matched by Codec::name) on the encode side.

pub fn with_cache_control(self, cache: CacheControl) -> Self

Attach (or clear) a cache directive on this part. Returns the value back so callers can chain. No-op on ToolUse / ImageOutput / AudioOutput / RedactedThinking (model output never carries caching) — the directive is silently dropped.

pub fn with_provider_echo(self, echo: ProviderEchoSnapshot) -> Self

Append a vendor opaque round-trip token to this part. Codecs call this on the decode side after extracting the wire-shape signature / encrypted_content / data field. Returns the value back so callers can chain.

Trait Implementations

impl Clone for ContentPart

fn clone(&self) -> ContentPart

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ContentPart

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ContentPart

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ContentPart

fn eq(&self, other: &ContentPart) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ContentPart

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for ContentPart

impl StructuralPartialEq for ContentPart