---
sidebar:
  hidden: true
title: roboto.ai.agent_thread.record
---
## Module Contents

- [AGENT_CONTENT_MODEL_BY_TYPE](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AGENT_CONTENT_MODEL_BY_TYPE) (data): `AGENT_CONTENT_MODEL_BY_TYPE: dict[AgentContentType, type[AgentContent]]`. The model class for each JSON-serialized content type, keyed by discriminator.

- [AgentClientContextEntry](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentClientContextEntry) (class): The caller's attached viewing context, carried on their own message.

- [AgentCompressionFillerContent](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentCompressionFillerContent) (class): Filler standing in for a message the compression deletion pass emptied.

- [AgentContent](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentContent) (type alias): `type AgentContent = AgentTextContent | AgentToolUseContent | AgentToolResultContent | AgentErrorContent | AgentDeletedContent | AgentCompressionFillerContent | AgentClientContextEntry`. Type alias for all possible content types within agent messages.

- [AgentContentType](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentContentType) (class): Enumeration of different types of content within agent messages.

- [AgentDeletedContent](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentDeletedContent) (class): Tombstone for a content block removed by compression.

- [AgentErrorContent](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentErrorContent) (class): Error content within an agent message.

- [AgentGoalStatus](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoalStatus) (class): Lifecycle of a per-turn declared goal.

- [AgentMessage](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentMessage) (class): A single message within an agent thread.

- [AgentMessageStatus](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentMessageStatus) (class): Enumeration of possible message generation states.

- [AgentRole](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentRole) (class): Enumeration of possible roles in an agent thread.

- [AgentSubtask](/reference/python-sdk/roboto/ai/core/task#roboto.ai.core.task.AgentSubtask) (class): A lightweight checklist item under a top-level task.

- [AgentSubtaskStatus](/reference/python-sdk/roboto/ai/core/task#roboto.ai.core.task.AgentSubtaskStatus) (class): Lifecycle state of a sub-task.

- [AgentTask](/reference/python-sdk/roboto/ai/core/task#roboto.ai.core.task.AgentTask) (class): A top-level task the agent is tracking within a thread.

- [AgentTaskBoundary](/reference/python-sdk/roboto/ai/core/task#roboto.ai.core.task.AgentTaskBoundary) (class): Position in the conversation where a top-level task's active span begins or ends.

- [AgentTaskMinimal](/reference/python-sdk/roboto/ai/core/task#roboto.ai.core.task.AgentTaskMinimal) (class): Minimal acknowledgement returned by the task mutation tools.

- [AgentTaskStatus](/reference/python-sdk/roboto/ai/core/task#roboto.ai.core.task.AgentTaskStatus) (class): Lifecycle state of a top-level agent task.

- [AgentTextContent](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentTextContent) (class): Text content within an agent message.

- [AgentThreadDelta](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadDelta) (class): Incremental update to an agent thread.

- [AgentThreadGoalRecord](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadGoalRecord) (class): Customer-visible read shape of a goal declared on an agent thread.

- [AgentThreadRecord](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadRecord) (class): Complete record of an agent thread.

- [AgentThreadStatus](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadStatus) (class): Enumeration of possible agent thread states.

- [AgentToolResultContent](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentToolResultContent) (class): Tool execution result content within an agent message.

- [AgentToolUseContent](/reference/python-sdk/roboto/ai/core/content#roboto.ai.core.content.AgentToolUseContent) (class): Tool usage request content within an agent message.

- [ClientToolSpec](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.ClientToolSpec) (class): Declarative specification for a client-side tool.

- [ThreadOrigin](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.ThreadOrigin) (class): The surface an [`AgentThreadRecord`](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadRecord) was started from, and the one that owns it.

- [ThreadVisibility](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.ThreadVisibility) (class): Read-scope for an [`AgentThreadRecord`](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadRecord).

### AgentThreadSubject

```python
class roboto.ai.agent_thread.record.AgentThreadSubject(/, **data: Any)
```

`from roboto.ai.agent_thread import AgentThreadSubject`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L396-L413)

Bases: `pydantic.BaseModel`

Canonical record of an entity an [`AgentThread`](/reference/python-sdk/roboto/ai/agent_thread/agent_thread#roboto.ai.agent_thread.agent_thread.AgentThread) applies to.

Used to answer "which agent threads are about this dataset / file?" — the dataset detail page's Agent Threads tab is one consumer; future surfaces that want to discover threads by entity will use the same record.

**Parameters**

- **data** (`Any`)

**Attributes**

- **AgentThreadSubject.association_id** (`str`): Identifier of the entity the thread applies to — e.g. a dataset id or file id.
- **AgentThreadSubject.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- **AgentThreadSubject.note** (`str`): Short, free-form explanation of how the subject came to be attached (e.g. why this thread applies to that entity).

### AgentToolDetailResponse

```python
class roboto.ai.agent_thread.record.AgentToolDetailResponse(/, **data: Any)
```

`from roboto.ai.agent_thread import AgentToolDetailResponse`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L68-L72)

Bases: `pydantic.BaseModel`

Unsanitized tool request and response details for an agent tool invocation.

**Parameters**

- **data** (`Any`)

**Attributes**

- **AgentToolDetailResponse.tool_result** (`roboto.ai.core.record.AgentToolResultContent`)
- **AgentToolDetailResponse.tool_use** (`roboto.ai.core.record.AgentToolUseContent`)

### AvailableSkillSpec

```python
class roboto.ai.agent_thread.record.AvailableSkillSpec(/, **data: Any)
```

`from roboto.ai.agent_thread import AvailableSkillSpec`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L101-L125)

Bases: `pydantic.BaseModel`

One entry in a thread's explicit AI-invokable skill set.

Embedded in [`StartAgentThreadRequest.available_skills`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.StartAgentThreadRequest.available_skills). Unlike [`InvokeSkillSpec`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.InvokeSkillSpec) — which seeds a skill into the opening transcript as a turn trigger — this struct only declares that a skill *version* is available for the AI to auto-invoke via its `load_skill` tool during the thread. The route layer resolves access (org visibility, private gating) and version selection; this struct only carries the caller's choice.

Defined locally to avoid the `roboto.ai` \<-> `roboto.domain.skills` import cycle.

**Parameters**

- **data** (`Any`)

**Attributes**

- **AvailableSkillSpec.skill_id** (`str`): 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.

- **AvailableSkillSpec.version** (`int | None`) = `None`: 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.

### ClientToolResult

```python
class roboto.ai.agent_thread.record.ClientToolResult(/, **data: Any)
```

`from roboto.ai import ClientToolResult`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L342-L358)

Bases: `pydantic.BaseModel`

Result of executing a client-side tool.

**Parameters**

- **data** (`Any`)

**Attributes**

- **ClientToolResult.output** (`dict[str, Any] | None`) = `None`: Structured output returned by the tool.
- **ClientToolResult.runtime_ms** (`int`): Wall-clock execution time of the tool in milliseconds.
- **ClientToolResult.status** (`ClientToolResultStatus`): Outcome of the tool execution.
- **ClientToolResult.tool_name** (`str`): Name of the tool that was executed.
- **ClientToolResult.tool_use_id** (`str`): Identifier of the tool invocation this result corresponds to.

### ClientToolResultStatus

```python
class roboto.ai.agent_thread.record.ClientToolResultStatus
```

`from roboto.ai import ClientToolResultStatus`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L334-L339)

Bases: `roboto.compat.StrEnum`

Outcome of executing a client-side tool.

**Attributes**

- **ClientToolResultStatus.DECLINED** = `'declined'`
- **ClientToolResultStatus.ERROR** = `'error'`
- **ClientToolResultStatus.SUCCESS** = `'success'`

### ForkAgentThreadRequest

```python
class roboto.ai.agent_thread.record.ForkAgentThreadRequest(/, **data: Any)
```

`from roboto.ai.agent_thread import ForkAgentThreadRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L371-L375)

Bases: `pydantic.BaseModel`

Request payload for forking an agent thread at a specific message.

**Parameters**

- **data** (`Any`)

**Attributes**

- **ForkAgentThreadRequest.message_sequence_num** (`int`): Highest message sequence number (inclusive) to copy into the new thread.

### InvokeSkillSpec

```python
class roboto.ai.agent_thread.record.InvokeSkillSpec(/, **data: Any)
```

`from roboto.ai.agent_thread import InvokeSkillSpec`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L75-L98)

Bases: `pydantic.BaseModel`

Spec for invoking a skill as part of a turn trigger.

Embedded in [`SendMessageRequest`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.SendMessageRequest) and [`StartAgentThreadRequest`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.StartAgentThreadRequest). The route layer resolves access (org visibility, private gating) and version selection; this struct only carries the caller's choice.

Defined locally to avoid the `roboto.ai` ↔ `roboto.domain.skills` import cycle.

**Parameters**

- **data** (`Any`)

**Attributes**

- **InvokeSkillSpec.skill_id** (`str`): 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.

- **InvokeSkillSpec.version** (`int | None`) = `None`: 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.

### PinThreadRequest

```python
class roboto.ai.agent_thread.record.PinThreadRequest(/, **data: Any)
```

`from roboto.ai.agent_thread import PinThreadRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L389-L393)

Bases: `pydantic.BaseModel`

Request body for `POST /v1/ai/threads/<thread_id>/pin`, which pins or unpins a thread for the caller.

**Parameters**

- **data** (`Any`)

**Attributes**

- **PinThreadRequest.pinned** (`bool`): Pin state the thread should have for the calling user after the call.

### SendMessageRequest

```python
class roboto.ai.agent_thread.record.SendMessageRequest(/, **data: Any)
```

`from roboto.ai.agent_thread import SendMessageRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L128-L196)

Bases: `pydantic.BaseModel`

Request payload for sending a message to an agent thread.

Contains the message content and optional context for the AI assistant.

**Parameters**

- **data** (`Any`)

**Attributes**

- **SendMessageRequest.analysis_scope** (`roboto.ai.core.AnalysisScope | None`) = `None`: 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`).
- **SendMessageRequest.client_context** (`roboto.ai.core.ClientViewingContext | None`) = `None`: Optional [`ClientViewingContext`](/reference/python-sdk/roboto/ai/core/context#roboto.ai.core.context.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.
- **SendMessageRequest.client_tools** (`list[roboto.ai.core.record.ClientToolSpec] | None`) = `None`: Optional client-side tools available for this invocation.
- **SendMessageRequest.goals** (`list[roboto.ai.goals.AgentGoal] | None`) = `None`: 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`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.SendMessageRequest.message) becomes optional. Capped at `MAX_GOALS_PER_TURN` entries (see the constant for rationale).
- **SendMessageRequest.invoke_skills** (`list[InvokeSkillSpec]`) = `None`: 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`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.SendMessageRequest.message) (if any). When [`message`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.SendMessageRequest.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.
- **SendMessageRequest.message** (`roboto.ai.core.record.AgentMessage | None`) = `None`: Message content to send. May be omitted when at least one goal is declared in [`goals`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.SendMessageRequest.goals); in that case the server synthesizes a minimal user message so the LLM has a turn-initiating prompt.

### StartAgentThreadRequest

```python
class roboto.ai.agent_thread.record.StartAgentThreadRequest(/, **data: Any)
```

`from roboto.ai.agent_thread import StartAgentThreadRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L199-L331)

Bases: `pydantic.BaseModel`

Request payload for starting a new agent thread.

Contains the initial messages and configuration for creating a new conversation.

**Parameters**

- **data** (`Any`)

**Attributes**

- **StartAgentThreadRequest.analysis_scope** (`roboto.ai.core.AnalysisScope | None`) = `None`: 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.

- **StartAgentThreadRequest.available_skills** (`list[AvailableSkillSpec] | None`) = `None`: 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`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.StartAgentThreadRequest.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.

- **StartAgentThreadRequest.client_context** (`roboto.ai.core.ClientViewingContext | None`) = `None`: Optional [`ClientViewingContext`](/reference/python-sdk/roboto/ai/core/context#roboto.ai.core.context.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.

- **StartAgentThreadRequest.client_tools** (`list[roboto.ai.core.record.ClientToolSpec] | None`) = `None`: Optional client-side tools available for this invocation.

- **StartAgentThreadRequest.goals** (`list[roboto.ai.goals.AgentGoal] | None`) = `None`: 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`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.StartAgentThreadRequest.messages) may be empty. Capped at `MAX_GOALS_PER_TURN` entries (see the constant for rationale).

- **StartAgentThreadRequest.invoke_skills** (`list[InvokeSkillSpec]`) = `None`: 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`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.StartAgentThreadRequest.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.

- **StartAgentThreadRequest.messages** (`list[roboto.ai.core.record.AgentMessage]`) = `None`: Initial messages to start the conversation with. May be empty when at least one goal is declared in [`goals`](/reference/python-sdk/roboto/ai/agent_thread/record#roboto.ai.agent_thread.record.StartAgentThreadRequest.goals); in that case the server synthesizes a minimal user message so the LLM has a turn-initiating prompt.

- **StartAgentThreadRequest.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

- **StartAgentThreadRequest.model_profile** (`str | None`) = `None`: Optional model profile ID for the thread (e.g. 'standard', 'advanced').

- **StartAgentThreadRequest.system_prompt** (`str | None`) = `None`: Optional system prompt to customize AI assistant behavior.

- **StartAgentThreadRequest.visibility** (`roboto.ai.core.record.ThreadVisibility`): 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.

### SubmitToolResultsRequest

```python
class roboto.ai.agent_thread.record.SubmitToolResultsRequest(/, **data: Any)
```

`from roboto.ai.agent_thread import SubmitToolResultsRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L361-L368)

Bases: `pydantic.BaseModel`

Request payload for submitting client-side tool execution results.

**Parameters**

- **data** (`Any`)

**Attributes**

- **SubmitToolResultsRequest.client_tools** (`list[roboto.ai.core.record.ClientToolSpec] | None`) = `None`: Optional updated client-side tools for the next invocation.
- **SubmitToolResultsRequest.tool_results** (`list[ClientToolResult]`): Tool results from client-side execution.

### UpdateThreadVisibilityRequest

```python
class roboto.ai.agent_thread.record.UpdateThreadVisibilityRequest(/, **data: Any)
```

`from roboto.ai.agent_thread import UpdateThreadVisibilityRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/record.py#L378-L386)

Bases: `pydantic.BaseModel`

Request payload for re-scoping who may read an agent thread.

Sent to `POST /v1/ai/threads/<thread_id>/visibility` by [`roboto.ai.agent_thread.AgentThread.set_visibility()`](/reference/python-sdk/roboto/ai/agent_thread/agent_thread#roboto.ai.agent_thread.agent_thread.AgentThread.set_visibility).

**Parameters**

- **data** (`Any`)

**Attributes**

- **UpdateThreadVisibilityRequest.visibility** (`roboto.ai.core.record.ThreadVisibility`): Read-scope the thread has once the call returns.