roboto.ai.agent_thread.record

What the caller had open: attached datasets, files, and visualizer state.

What the caller was looking at when they composed the message this block sits on.

Superseded shape: the same payload used to be persisted as a whole ROBOTO-role message whose text was a <ctx>...</ctx> marker (ENG-2185). Readers still accept that form for threads written before this type existed; nothing emits it any more.

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.

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 information when message generation fails.

Plain text content from users or AI responses.

Results returned from tool executions.

Tool invocation requests from the AI assistant.

Optional error code for programmatic handling.

User-friendly error message describing what went wrong.

Goal’s corresponding achieve-tool was invoked successfully.

Goal could not be achieved within the turn’s retry budget.

Goal has been registered but not yet completed.

List of content blocks that make up this message.

Timestamp when this message was created.

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

Current generation status of this message.

Message generation was cancelled by the user.

Message generation has finished and content is complete.

Message generation failed due to an error.

Message content is currently being generated.

Message has been queued but generation has not begun.

AI agent responding to user queries and requests.

Roboto system providing tool results and system information.

Human user sending messages to the agent.

Whether the sub-task is done.

Human-readable description of the sub-task.

Completed.

Not done yet.

Outcome recorded when the task was completed. None until then.

Longer description delimiting the task’s scope and intent.

Where the task was completed. None until then.

Display order among the thread’s top-level tasks.

Where the task most recently became in_progress. None if never started.

Current lifecycle state.

Ordered sub-tasks. A task cannot be completed until all of these are done.

Thread-monotonic id, stable for the life of the thread. The model references this id to start or complete the task.

Short title of the task.

Index of the tool-call content block within that message.

Index of the assistant message whose tool call stamped this boundary.

Resulting status of the affected task.

Id of the affected task.

Finished; carries a AgentTask.conclusion.

The single active task. At most one task per thread is in this state.

Not started yet.

The actual text content of the message.

Updated token for the next incremental synchronization.

Latest snapshot of every goal declared in the thread, ordered by allocation. None means there has been no change since the previous delta — clients should retain the snapshot they already hold. An empty list means the thread has no declared goals. A non-empty list is the authoritative current snapshot and replaces any prior value.

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

Discard held messages from this index onward before applying this delta.

A delta’s messages normally extend what a client already holds, because the server sends only content the client has not seen. That breaks when a turn is abandoned partway and regenerated: the replacement message reuses the same index, so what the client holds at that index is text from an attempt that no longer exists, and appending to it would splice the real reply onto a discarded draft.

When this field is set, the client must truncate its held messages to indices strictly below it, then apply messages_by_idx and adopt continuation_token as usual — the server has rewound the stream to that point and will resend it. None (the common case) means append as normal.

Updated status of the agent thread.

Latest snapshot of the thread’s task list, ordered by position. None means no change since the previous delta — clients should retain the snapshot they already hold. An empty list means the thread has no tasks. A non-empty list is the authoritative current snapshot and replaces any prior value.

Updated title of the agent thread.

tool_use_id of the achieve-tool invocation associated with this goal. Populated by the turn runner on every achieve-tool attempt, so its final value depends on the goal’s terminal status:

• ACHIEVED: the tool_use_id of the successful invocation.
• FAILED: the tool_use_id of the last attempted invocation, or None if the LLM never invoked the achieve-tool before the retry budget exhausted.
• PENDING: None (or the most recent attempt so far).

Use with AgentThread.goals and the GoalResult accessor on the SDK wrapper to locate the exact AgentToolUseContent / AgentToolResultContent pair without scanning by tool name.

Timestamp when the goal transitioned to a terminal state (ACHIEVED or FAILED). None while the goal is still PENDING.

Timestamp when the goal was registered.

The validated goal payload as JSON. Use to_agent_goal() to recover the typed model the caller declared.

Discriminator selecting which AgentGoal model the goal_data payload conforms to (e.g. "dataset_summary").

Index in the thread’s full messages list of the AgentRole.USER message that declared this goal. Use to render goals adjacent to the turn they were attached to.

Current lifecycle state of the goal.

Token used for incremental updates and synchronization.

Timestamp when this agent thread was created.

User ID of the person who created this agent thread.

Serialized RobotoPrincipal ("ptype:id") that started this thread, e.g. "user:jo@example.com" or "invocation:iv_123". Unlike created_by, this preserves whether the thread was driven by a person, a device, or an action invocation. None on threads created before this field existed.

If this thread was started via the agent launch flow, the id of the agent that produced it. None for threads started directly through POST /v1/ai/threads. Forks do not inherit this field — a fork is its own thread.

If a trigger’s start_agent target launched this thread, the id of that trigger. None for every other thread, including one launched from the same agent by a person. Set alongside created_from_agent_id, which names the agent; this names what decided to run it. Forks do not inherit this field — a fork is its own thread.

Message sequence number in the source thread that this fork was taken from.

Populated in tandem with forked_from_thread_id; both are None for threads that were not created as a fork.

If this thread was forked, the id of the source thread. None otherwise.

Deserialization also accepts the legacy forked_from_session_id spelling for backward compatibility.

Goals declared across this thread’s turns, ordered by the turn that declared them. None means goals were not loaded for this record; an empty list means they were loaded but the thread never declared any.

Complete list of messages in the conversation.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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

Organization ID that owns this agent thread.

The surface that owns this thread.

Set by Roboto when the thread is created; it cannot be supplied by a caller. A thread owned by a surface outside Roboto refuses new messages over the API, raising RobotoThreadReadOnlyException; reading, cancelling, and rating it stay open, and a fork does not inherit the origin, so the copy is writable.

None on threads created before this field existed, and equivalent to ThreadOrigin.API — every surface that predates the field was Roboto’s own. It stays nullable until those rows are backfilled.

When the calling user pinned this thread, or None if they have not.

A pin is a personal bookmark, so two users reading the same thread see different values here. Pin and unpin through roboto.ai.agent_thread.AgentThread.set_pinned(). Only GET /v1/ai/threads and POST /v1/ai/threads/search report it; reads of a single thread leave it None whatever the pin state.

Current status of this agent thread.

The thread’s task list, ordered by AgentTask.position. None means tasks were not loaded for this record; an empty list means they were loaded but the thread has none.

Unique identifier for this agent thread.

Deserialization also accepts the legacy session_id and chat_id spellings for backward compatibility; the canonical attribute name is thread_id.

Title of this agent thread.

Who can read this thread. PRIVATE (the default) restricts reads to the created_by user and Roboto admins; ORG opens the thread to every member of org_id.

Client must execute pending tool uses and submit results.

The agent runner exhausted its corrective re-prompt budget without achieving every declared goal for the most-recent turn. Signals to clients that the thread needs human intervention before it can continue.

Thread has been created but no messages have been sent.

Roboto is generating a message.

User has the turn to send a message.

Identifier of the entity the thread applies to — e.g. a dataset id or file id.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Short, free-form explanation of how the subject came to be attached (e.g. why this thread applies to that entity).

What the tool returned: free-form text, or a JSON object or array of structured data.

Independent of any model provider’s wire format (provider-agnostic, like AgentToolUseContent.input). None on results written before this field existed; use resolve_payload() to read old and new results uniformly.

Legacy provider-formatted response envelope (Bedrock toolResult shape).

Kept so results written before payload existed remain readable; deprecated for new readers, who should call resolve_payload() instead of parsing this field.

Populated only where the server-side envelope is in scope: threads read over the API arrive with this field stripped (and, for legacy rows, with payload synthesized from it server-side before the strip), so API/SDK readers should not expect it.

Wall-clock execution time of the tool in milliseconds.

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

Name of the tool that was executed.

Identifier of the tool invocation this result corresponds to.

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

Raw, unparsed request payload for this tool invocation.

Name of the tool the LLM is requesting to invoke.

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

Target skill’s ID. Must be visible to the caller — an org-shared skill, or the caller’s own private skill. A subscription is not required; the per-thread set bypasses subscription state entirely.

Optional. If omitted, resolves to the skill’s latest (MAX(version)) row.

Pins the exact version exposed to the AI for this thread. Subscriptions and their per-user ai_version pins are ignored when a thread carries an explicit available_skills set.

Structured output returned by the tool.

Wall-clock execution time of the tool in milliseconds.

Outcome of the tool execution.

Name of the tool that was executed.

Identifier of the tool invocation this result corresponds to.

Highest message sequence number (inclusive) to copy into the new thread.

Target skill’s ID. Must be visible to the caller (own private skill or an org-shared skill); the route layer rejects unauthorized invocations before the spec reaches the service.

Optional. If omitted, resolves to the skill’s latest (MAX(version)) row.

Note this is the structural latest, not the caller’s pinned ai_version: a manually-invoked chip runs MAX(version) regardless of what the caller’s AI auto-invoke is pinned to. Use Skill.set_ai_version() to control the pin separately.

Pin state the thread should have for the calling user after the call.

Optional replacement analysis scope. When provided, overwrites the thread’s current analysis scope; the new scope takes effect for this turn’s tool invocations and every turn thereafter. When None, the thread’s existing analysis scope is left untouched (there is currently no wire-format way to clear a scope via send).

Optional ClientViewingContext describing what the client was viewing when this message was composed. Wire field is client_context; the legacy context alias is accepted during the migration window and will be dropped in a future release.

Optional client-side tools available for this invocation.

Goals declared for this turn. The agent runner enforces achievement: it gates a per-turn achieve-tool against each goal and re-prompts until every goal is satisfied or a per-turn retry budget is exhausted. May be omitted; when present, message becomes optional. Capped at MAX_GOALS_PER_TURN entries (see the constant for rationale).

Skills to invoke as part of this turn, in order. The server fabricates one LoadSkillTool tool_use + tool_result pair per entry and appends them to the transcript after message (if any). When message is empty and no goals are declared, the fabricated pairs become the turn trigger themselves — useful for chip-only invocations that don’t carry a typed prompt. Pass a single-element list for the common “invoke one skill” case.

Message content to send. May be omitted when at least one goal is declared in goals; in that case the server synthesizes a minimal user message so the LLM has a turn-initiating prompt.

Optional analysis scope for the thread. Delivered to every tool invocation on the server side; individual tools opt in to honoring it. None means no scope.

Explicit set of skills the AI may auto-invoke during this thread, replacing the subscription-derived load_skill registry.

Tri-state:

• None (the default) — the AI’s load_skill registry is derived per turn from the caller’s skill subscriptions, as usual.
• [] — the AI has no auto-invokable skills for this thread.
• a non-empty list — exactly these skill versions are auto-invokable; the caller’s subscriptions and per-user ai_version pins are ignored.

Each entry may reference any org-shared skill or the caller’s own private skill (visibility only — no subscription required), at any version. One version per skill: duplicate skill_id entries are rejected. Resolved once at thread start and frozen onto the thread; later subscription changes and skill-body edits do not propagate into it. Capped at MAX_AVAILABLE_SKILLS entries.

Distinct from invoke_skills: available_skills configures what the AI can reach for, while invoke_skills seeds skill bodies into the opening transcript as a turn trigger. It is configuration, not a trigger — a request carrying only available_skills and no messages / goals / invoke_skills is still rejected.

Optional ClientViewingContext describing what the client was viewing when this thread was started. Wire field is client_context; the legacy context alias is accepted during the migration window and will be dropped in a future release.

Optional client-side tools available for this invocation.

Goals declared for the first turn. The agent runner enforces achievement: it gates a per-turn achieve-tool against each goal and re-prompts until every goal is satisfied or a per-turn retry budget is exhausted. May be omitted; when present, messages may be empty. Capped at MAX_GOALS_PER_TURN entries (see the constant for rationale).

Skills to invoke at thread start, in order. The server fabricates one LoadSkillTool tool_use + tool_result pair per entry and appends them to the transcript after any seeded messages. When messages is empty and no goals are declared, the fabricated pairs become the thread seed. Pass a single-element list for the common “invoke one skill” case.

Initial messages to start the conversation with. May be empty when at least one goal is declared in goals; in that case the server synthesizes a minimal user message so the LLM has a turn-initiating prompt.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Optional model profile ID for the thread (e.g. ‘standard’, ‘advanced’).

Optional system prompt to customize AI assistant behavior.

Who may read the resulting thread after it is created. PRIVATE (the default) restricts reads to the creator and Roboto admins; ORG lets any member of the thread’s org read it and makes the thread visible to org members on POST /v1/ai/threads/search. The default is PRIVATE so that a thread started via POST /v1/ai/threads does not leak to the rest of the org until the caller opts in; threads created through the agent launch flow default to ORG instead, since agents exist to share workflows across teammates.

Optional updated client-side tools for the next invocation.

Tool results from client-side execution.

Started through Roboto itself – the web app, the CLI, the SDK, or a direct REST call.

These surfaces read the thread back from Roboto rather than mirroring it somewhere else, so there is nothing for a new turn to fall out of sync with and the thread stays writable.

Started by mentioning @Roboto in Slack, and mirrored into that Slack conversation.

Any member of the thread’s organization (and Roboto admins) may read the thread.

Default for threads produced by the agent launch flow, since agents exist to share workflows across teammates. Forks of an ORG thread do not inherit visibility — every fork lands as PRIVATE.

Only the creating user (and Roboto admins) may read the thread.

Default for threads created via POST /v1/ai/threads so an in-flight experiment does not leak to the rest of the org until the caller opts in.

Read-scope the thread has once the call returns.