roboto.ai.agent_thread.agent_thread_goal_view#

SDK wrapper that resolves an 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 — the raw AgentToolUseContent for the achieve-tool invocation associated with the goal.

  • achieve_tool_result — the matching AgentToolResultContent, when one was persisted.

  • result — the typed, per-goal-type 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#

class roboto.ai.agent_thread.agent_thread_goal_view.AgentThreadGoalView(record, messages)#

SDK-side wrapper around an 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:
property achieve_tool_result: roboto.ai.agent_thread.record.AgentToolResultContent | None#

The matching tool-result block for 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 is non-null.

Return type:

roboto.ai.agent_thread.record.AgentToolResultContent | None

property 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.

Return type:

roboto.ai.agent_thread.record.AgentToolUseContent | None

property achieve_tool_use_id: str | None#

tool_use_id of the achieve-tool invocation associated with this goal — see AgentThreadGoalRecord.achieve_tool_use_id for the per-status semantics.

Return type:

str | None

property concluded_at: datetime.datetime | None#

Timestamp when the goal reached a terminal state, or None while still PENDING.

Return type:

datetime.datetime | None

property created: datetime.datetime#

Timestamp when the goal was registered.

Return type:

datetime.datetime

property goal_data: dict[str, Any]#

The original goal-declaration payload. Use to_agent_goal() to re-hydrate into the typed AgentGoal model.

Return type:

dict[str, Any]

property goal_type: str#

Discriminator selecting which AgentGoal model the goal was declared as. Equivalent to self.record.goal_type.

Return type:

str

property message_sequence_num: int#

Index of the user-role message that declared this goal.

Return type:

int

property 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).

Return type:

roboto.ai.agent_thread.record.AgentThreadGoalRecord

property 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 / achieve_tool_result directly for debugging.

The returned object is one of the concrete subclasses of GoalResult (e.g. 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.

Return type:

roboto.ai.goals.results.GoalResult | None

property status: roboto.ai.agent_thread.record.AgentGoalStatus#

Current lifecycle state of the goal.

Return type:

roboto.ai.agent_thread.record.AgentGoalStatus

to_agent_goal()#

Re-hydrate the goal declaration into its typed AgentGoal model. Delegates to AgentThreadGoalRecord.to_agent_goal().

Return type:

roboto.ai.goals.types.AgentGoal

On this page