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 rawAgentToolUseContentfor the achieve-tool invocation associated with the goal.achieve_tool_result— the matchingAgentToolResultContent, when one was persisted.result— the typed, per-goal-typeGoalResultparsed 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
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
Properties
AgentThreadGoalView.achieve_tool_result
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.
AgentThreadGoalView.achieve_tool_use
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
tool_use_id of the achieve-tool invocation associated with this goal — see AgentThreadGoalRecord.achieve_tool_use_id for the per-status semantics.
AgentThreadGoalView.concluded_at
Timestamp when the goal reached a terminal state, or None while still PENDING.
AgentThreadGoalView.created
Timestamp when the goal was registered.
AgentThreadGoalView.goal_data
The original goal-declaration payload. Use to_agent_goal() to re-hydrate into the typed AgentGoal model.
AgentThreadGoalView.goal_type
Discriminator selecting which AgentGoal model the goal was declared as. Equivalent to self.record.goal_type.
AgentThreadGoalView.message_sequence_num
Index of the user-role message that declared this goal.
AgentThreadGoalView.record
The underlying wire record. Useful for callers that want the unwrapped pydantic shape (e.g. for JSON serialization).
AgentThreadGoalView.result
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.
AgentThreadGoalView.status
Current lifecycle state of the goal.
AgentThreadGoalView.to_agent_goal()
Re-hydrate the goal declaration into its typed AgentGoal model. Delegates to AgentThreadGoalRecord.to_agent_goal().
Return type