roboto.ai.core.content

Message-content primitive value types shared across the roboto.ai layer.

These are the leaf building blocks of AgentMessage.content. They live here — below both roboto.ai.core.record and roboto.ai.goals — so the goals layer can reference the raw tool-call blocks (to carry them on a GoalResult) without importing from core.record. That keeps the roboto.ai import graph a DAG: core.content depends on nothing in roboto.ai; goals and core.record both depend down onto it.

Module Contents

roboto.ai.core.content.AGENT_CONTENT_MODEL_BY_TYPE: dict[AgentContentType, type[AgentContent]]

The model class for each JSON-serialized content type, keyed by discriminator.

Excludes AgentContentType.TEXT, whose payload is persisted as raw text rather than a serialized model. Every other member of AgentContent carries a content_type discriminator and round-trips through model_dump_json / model_validate_json; driving both serialization directions off this one map keeps them symmetric, so a member added to the union without a home here fails loudly instead of being silently dropped on write or reconstructed without its payload on read.

class roboto.ai.core.content.AgentCompressionFillerContent(/, **data)

Bases: pydantic.BaseModel

Filler standing in for a message the compression deletion pass emptied.

Carries no payload. A message reduced to nothing but tombstones keeps this single block instead of an empty content list, so it stays in the Bedrock payload at its original role and turn alternation survives without relocating content. The Bedrock boundary renders it as <Deleted in compression>. Produced only by the compression deletion pass and stored only at the DELETED tier; the verbatim original thread (what the SDK and UI render) never contains one.

Parameters:

data (Any)

content_type: Literal[AgentContentType]

type roboto.ai.core.content.AgentContent = AgentTextContent | AgentToolUseContent | AgentToolResultContent | AgentErrorContent | AgentDeletedContent | AgentCompressionFillerContent

Type alias for all possible content types within agent messages.

class roboto.ai.core.content.AgentContentType

Bases: roboto.compat.StrEnum

Enumeration of different types of content within agent messages.

Defines the various content types that can be included in agent messages.

COMPRESSION_FILLER = 'compression_filler'

Stand-in block kept in a message the deletion pass emptied entirely.

A message reduced to nothing but tombstones would break user/assistant alternation if it dropped from the payload. Replacing its content with this single filler keeps the message — and its role — in place. The model sees it as <Deleted in compression>. Only the cross-message deletion pass produces it, so it appears only inside a DELETED-tier compressed variant, never in the verbatim original thread the SDK and UI read.

DELETED = 'deleted'

Tombstone marking a content block elided by compression.

Appears only inside a DELETED-tier compressed variant. Both producers — message-tier compression dropping a pure-filler text run, and the cross-message deletion pass dropping a whole tool exchange — store their output at the DELETED tier, so a message carrying one is always a DELETED-tier variant. Never in the verbatim original thread the SDK and UI read.

ERROR = 'error'

Error information when message generation fails.

TEXT = 'text'

Plain text content from users or AI responses.

TOOL_RESULT = 'tool_result'

Results returned from tool executions.

TOOL_USE = 'tool_use'

Tool invocation requests from the AI assistant.

class roboto.ai.core.content.AgentDeletedContent(/, **data)

Bases: pydantic.BaseModel

Tombstone for a content block removed by compression.

Carries no payload — its presence records that a block once occupied this slot, and it converts to None at the Bedrock boundary so the block drops from the LLM payload. Produced when compression drops a block — a pure-filler text run at message compression, or a whole redundant tool exchange in the cross-message deletion pass — and stored only at the DELETED tier, so a message carrying one is always a DELETED-tier variant. A message reduced to nothing but tombstones does not drop: it is replaced with a single AgentCompressionFillerContent so it keeps its role and turn. The verbatim original thread (what the SDK and UI render) never contains one.

Parameters:

data (Any)

content_type: Literal[AgentContentType]

class roboto.ai.core.content.AgentErrorContent(/, **data)

Bases: pydantic.BaseModel

Error content within an agent message.

Used when message generation fails due to an error or is cancelled by the user.

Parameters:

data (Any)

content_type: Literal[AgentContentType]

error_code: str | None = None

Optional error code for programmatic handling.

error_message: str

User-friendly error message describing what went wrong.

class roboto.ai.core.content.AgentTextContent(/, **data)

Bases: pydantic.BaseModel

Text content within an agent message.

Parameters:

data (Any)

text: str

The actual text content of the message.

class roboto.ai.core.content.AgentToolResultContent(/, **data)

Bases: pydantic.BaseModel

Tool execution result content within an agent message.

Parameters:

data (Any)

content_type: Literal[AgentContentType]

raw_response: dict[str, Any] | None = None

Raw, unparsed response payload from tool execution.

runtime_ms: int

Wall-clock execution time of the tool in milliseconds.

status: str

Outcome of the tool execution (e.g. ‘success’, ‘error’).

tool_name: str

Name of the tool that was executed.

tool_use_id: str

Identifier of the tool invocation this result corresponds to.

class roboto.ai.core.content.AgentToolUseContent(/, **data)

Bases: pydantic.BaseModel

Tool usage request content within an agent message.

Parameters:

data (Any)

content_type: Literal[AgentContentType]

input: dict[str, Any] | None = None

Parsed tool input parameters chosen by the LLM (provider-agnostic).

raw_request: dict[str, Any] | None = None

Raw, unparsed request payload for this tool invocation.

tool_name: str

Name of the tool the LLM is requesting to invoke.

tool_use_id: str

Unique identifier for this tool invocation, used to correlate with its result.