roboto.ai.core.record

Module Contents

type roboto.ai.core.record.AgentContent = AgentTextContent | AgentToolUseContent | AgentToolResultContent | AgentErrorContent

Type alias for all possible content types within agent messages.

class roboto.ai.core.record.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.

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.record.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.record.AgentMessage(/, **data)

Bases: pydantic.BaseModel

A single message within an agent session.

Represents one message in the conversation, containing the sender role, content blocks, and generation status. Messages can contain multiple content blocks of different types (text, tool use, tool results).

Parameters:

data (Any)

content: list[AgentContent]

List of content blocks that make up this message.

created: datetime.datetime = None

Timestamp when this message was created.

is_complete()

Check if message generation is complete.

Returns:

True if the message status is COMPLETED, False otherwise.

Return type:

bool

is_unsuccessful()

Check if message generation failed or was cancelled.

Returns:

True if the message status is FAILED or CANCELLED, False otherwise.

Return type:

bool

role: AgentRole

The role of the message sender (user, assistant, or roboto).

status: AgentMessageStatus

Current generation status of this message.

classmethod text(text, role=AgentRole.USER)

Create a simple text message.

Convenience method for creating a message containing only text content.

Parameters:

• text (str) – The text content for the message.

• role (AgentRole) – The role of the message sender. Defaults to USER.

Returns:

AgentMessage instance containing the text content.

Return type:

AgentMessage

class roboto.ai.core.record.AgentMessageStatus

Bases: roboto.compat.StrEnum

Enumeration of possible message generation states.

Tracks the lifecycle of message generation from initiation to completion.

CANCELLED = 'cancelled'

Message generation was cancelled by the user.

COMPLETED = 'completed'

Message generation has finished and content is complete.

FAILED = 'failed'

Message generation failed due to an error.

GENERATING = 'generating'

Message content is currently being generated.

NOT_STARTED = 'not_started'

Message has been queued but generation has not begun.

is_terminal()

Check if the message generation is in a terminal state.

Returns:

True if the message is in a terminal state, False otherwise.

Return type:

bool

class roboto.ai.core.record.AgentRole

Bases: roboto.compat.StrEnum

Enumeration of possible roles in an agent session.

Defines the different participants that can send messages in a session.

ASSISTANT = 'assistant'

AI agent responding to user queries and requests.

ROBOTO = 'roboto'

Roboto system providing tool results and system information.

USER = 'user'

Human user sending messages to the agent.

class roboto.ai.core.record.AgentSession(/, **data)

Bases: pydantic.BaseModel

Complete record of an agent session.

Contains all the persistent data for a session including metadata, message history, and synchronization state.

Parameters:

data (Any)

property chat_id: str

Backwards-compatible alias — serialized as chat_id in API responses.

Return type:

str

continuation_token: str

Token used for incremental updates and synchronization.

created: datetime.datetime

Timestamp when this agent session was created.

created_by: str

User ID of the person who created this agent session.

messages: list[AgentMessage] = None

Complete list of messages in the conversation.

model_profile: str | None = None

Model profile used for this agent session (e.g., ‘standard’, ‘advanced’).

org_id: str

Organization ID that owns this agent session.

session_id: str = None

Unique identifier for this agent session.

status: AgentSessionStatus

Current status of this agent session.

title: str | None = None

Title of this agent session.

class roboto.ai.core.record.AgentSessionDelta(/, **data)

Bases: pydantic.BaseModel

Incremental update to an agent session.

Contains only the changes since the last synchronization, used for efficient real-time updates without transferring the entire session history.

Parameters:

data (Any)

continuation_token: str

Updated token for the next incremental synchronization.

messages_by_idx: dict[int, AgentMessage]

New or updated messages indexed by their position in the conversation.

status: AgentSessionStatus | None = None

Updated status of the agent session.

title: str | None = None

Updated title of the agent session.

class roboto.ai.core.record.AgentSessionStatus

Bases: roboto.compat.StrEnum

Enumeration of possible agent session states.

Tracks the overall status of an agent session from creation to termination.

CLIENT_TOOL_TURN = 'client_tool_turn'

Client must execute pending tool uses and submit results.

NOT_STARTED = 'not_started'

Session has been created but no messages have been sent.

ROBOTO_TURN = 'roboto_turn'

Roboto is generating a message.

USER_TURN = 'user_turn'

User has the turn to send a message.

class roboto.ai.core.record.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.record.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.record.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.

roboto.ai.core.record.ChatContent

roboto.ai.core.record.ChatContentType

roboto.ai.core.record.ChatErrorContent

roboto.ai.core.record.ChatMessage

roboto.ai.core.record.ChatMessageStatus

roboto.ai.core.record.ChatRecord

roboto.ai.core.record.ChatRecordDelta

roboto.ai.core.record.ChatRole

roboto.ai.core.record.ChatStatus

roboto.ai.core.record.ChatTextContent

roboto.ai.core.record.ChatToolResultContent

roboto.ai.core.record.ChatToolUseContent

class roboto.ai.core.record.ClientToolSpec(/, **data)

Bases: pydantic.BaseModel

Declarative specification for a client-side tool.

Unlike AgentTool (which is an ABC with a __call__ method for server-side execution), ClientToolSpec is a plain data model. The backend includes it in the LLM’s tool list but never executes it — the client is responsible for execution and submitting the result.

Parameters:

data (Any)

description: str

input_schema: dict[str, Any]

name: str

class roboto.ai.core.record.ModelProfileResponse(/, **data)

Bases: pydantic.BaseModel

Metadata about an available model profile, returned by the API.

Parameters:

data (Any)

description: str

Short description of the profile’s characteristics.

id: str

Profile identifier, e.g. ‘standard’ or ‘advanced’.

is_default: bool = False

Whether this profile is selected by default for new sessions.

label: str

Human-readable display label.