---
sidebar:
  hidden: true
title: roboto.ai.agent_thread.agent_thread_goal_view
---
SDK wrapper that resolves an [`AgentThreadGoalRecord`](/docs/reference/python-sdk/roboto/ai/agent_thread#roboto.ai.agent_thread.AgentThreadGoalRecord) against the parent thread's message stream.

`AgentThreadGoalView` is the read shape `AgentThread.goals` returns. It delegates field reads to the underlying record and adds three resolved properties:

- [`achieve_tool_use`](/docs/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.achieve_tool_use) — the raw [`AgentToolUseContent`](/docs/reference/python-sdk/roboto/ai/agent_thread#roboto.ai.agent_thread.AgentToolUseContent) for the achieve-tool invocation associated with the goal.
- [`achieve_tool_result`](/docs/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.achieve_tool_result) — the matching [`AgentToolResultContent`](/docs/reference/python-sdk/roboto/ai/agent_thread#roboto.ai.agent_thread.AgentToolResultContent), when one was persisted.
- [`result`](/docs/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.result) — the typed, per-goal-type [`GoalResult`](/docs/reference/python-sdk/roboto/ai/goals#roboto.ai.goals.GoalResult) parsed from the tool\_use input.

All three resolve lazily by scanning the parent thread's `messages` list for the `achieve_tool_use_id` stored on the record. A single internal pass locates the tool\_use / tool\_result pair and is shared by all three accessors, so reading `goal.achieve_tool_use`, `goal.achieve_tool_result`, and `goal.result` in sequence does the same work as reading any one of them. The pair is cached on the wrapper after the first lookup, keyed on the messages-list identity, so repeated reads on the same snapshot are constant-time after the first.

## Module Contents

### AgentThreadGoalView

```python
class roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView(
    record: roboto.ai.agent_thread.record.AgentThreadGoalRecord,
    messages: list[roboto.ai.agent_thread.record.AgentMessage],
)
```

`from roboto.ai.agent_thread import AgentThreadGoalView`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/agent_thread/agent_thread_goal_view.py#L53-L240)

SDK-side wrapper around an [`AgentThreadGoalRecord`](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadGoalRecord).

Holds a back-reference to a messages list (the parent thread's full message history) so the achieve-tool invocation can be located via `achieve_tool_use_id` without forcing the caller to do the lookup by hand.

The wrapper is value-like: instantiating it does not copy the underlying record. Callers should not mutate it; mutations on the parent thread (via `run` / `refresh`) are visible through the wrapper's resolved properties because the messages list is shared.

**Parameters**

- **record** (`roboto.ai.agent_thread.record.AgentThreadGoalRecord`)
- **messages** (`list[roboto.ai.agent_thread.record.AgentMessage]`)

**Properties**

- **AgentThreadGoalView.achieve_tool_result** (`roboto.ai.agent_thread.record.AgentToolResultContent | None`): The matching tool-result block for [`achieve_tool_use`](/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.achieve_tool_use), if the runner persisted one before the turn terminated.

  For a FAILED goal whose last attempt errored mid-flight (or whose tool_result chunk never landed), this returns `None` even when [`achieve_tool_use`](/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.achieve_tool_use) is non-null.

- **AgentThreadGoalView.achieve_tool_use** (`roboto.ai.agent_thread.record.AgentToolUseContent | None`): The achieve-tool invocation the LLM submitted for this goal.

  Returns `None` when `achieve_tool_use_id` is `None` (no attempt has been recorded) or when no matching block is present in the thread's messages — the latter can happen if the caller is holding a thread snapshot that pre-dates the achieve-tool being persisted. In that case, a refresh of the thread should bring the block into view.

- **AgentThreadGoalView.achieve_tool_use_id** (`str | None`): `tool_use_id` of the achieve-tool invocation associated with this goal — see [`AgentThreadGoalRecord.achieve_tool_use_id`](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadGoalRecord.achieve_tool_use_id) for the per-status semantics.

- **AgentThreadGoalView.concluded_at** (`datetime.datetime | None`): Timestamp when the goal reached a terminal state, or `None` while still PENDING.

- **AgentThreadGoalView.created** (`datetime.datetime`): Timestamp when the goal was registered.

- **AgentThreadGoalView.goal_data** (`dict[str, Any]`): The original goal-declaration payload. Use [`to_agent_goal()`](/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.to_agent_goal) to re-hydrate into the typed [`AgentGoal`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoal) model.

- **AgentThreadGoalView.goal_type** (`str`): Discriminator selecting which [`AgentGoal`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoal) model the goal was declared as. Equivalent to `self.record.goal_type`.

- **AgentThreadGoalView.message_sequence_num** (`int`): Index of the user-role message that declared this goal.

- **AgentThreadGoalView.record** (`roboto.ai.agent_thread.record.AgentThreadGoalRecord`): The underlying wire record. Useful for callers that want the unwrapped pydantic shape (e.g. for JSON serialization).

- **AgentThreadGoalView.result** (`roboto.ai.goals.results.GoalResult | None`): Typed, per-goal-type result for the achieve-tool invocation.

  Returns `None` when no terminal achieve-tool invocation is available (PENDING goal, or FAILED with no attempted invocation), when the matching `tool_use` cannot be located in the thread's messages, or when the persisted input is malformed enough to fail validation against the achieve-input model. In all three cases callers can still inspect [`achieve_tool_use`](/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.achieve_tool_use) / [`achieve_tool_result`](/reference/python-sdk/roboto/ai/agent_thread/agent_thread_goal_view#roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView.achieve_tool_result) directly for debugging.

  The returned object is one of the concrete subclasses of [`GoalResult`](/reference/python-sdk/roboto/ai/goals/results#roboto.ai.goals.results.GoalResult) (e.g. [`DatasetSummaryGoalResult`](/reference/python-sdk/roboto/ai/goals/results#roboto.ai.goals.results.DatasetSummaryGoalResult)), so callers can `isinstance`-dispatch or simply read the typed fields. The status field reflects the goal's terminal status, so the same accessor works for both ACHIEVED and FAILED outcomes.

- **AgentThreadGoalView.status** (`roboto.ai.agent_thread.record.AgentGoalStatus`): Current lifecycle state of the goal.

#### AgentThreadGoalView.to_agent_goal()

```python
def to_agent_goal() -> roboto.ai.goals.types.AgentGoal
```

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

Re-hydrate the goal declaration into its typed [`AgentGoal`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoal) model. Delegates to [`AgentThreadGoalRecord.to_agent_goal()`](/reference/python-sdk/roboto/ai/core/record#roboto.ai.core.record.AgentThreadGoalRecord.to_agent_goal).

**Returns**

- `roboto.ai.goals.types.AgentGoal`