roboto.ai.goals.results#

Typed, per-goal-type results bundling the achieve-tool invocation.

A GoalResult is the typed read shape an SDK caller gets back from AgentThreadGoalView.result once a goal has reached a terminal state (ACHIEVED or FAILED with at least one attempted invocation). It bundles together:

  • The goal’s terminal AgentGoalStatus.

  • The exact AgentToolUseContent the LLM submitted to satisfy the goal — useful when callers need to introspect the request or correlate with downstream effects.

  • The corresponding AgentToolResultContent (when the runner observed one), so callers can see the response the LLM saw.

  • Per-goal-type typed fields parsed from achieve_tool_use.input via the shared roboto.ai.goals.achieve_inputs models, so callers get result.summary, result.label_decisions, result.events directly instead of reaching into a raw dict.

The discriminated-union pattern mirrors AgentGoal exactly: each concrete subclass declares goal_type: Literal[GoalType.X] = GoalType.X and the union dispatches on that discriminator.

Validation lives in the SDK, not on the wire — the server emits achieve_tool_use_id (a pointer into the persisted message stream) and the SDK rebuilds the GoalResult from messages it already holds. A new goal type therefore needs no API change, only a new subclass here plus a corresponding entry in AgentGoal.

Module Contents#

class roboto.ai.goals.results.CreateEventsGoalResult(/, **data)#

Bases: GoalResultBase, roboto.ai.goals.achieve_inputs.CreateEventsAchieveInput

Result of a GoalType.CREATE_EVENTS achieve-tool invocation.

Exposes the list of EventSpec objects the LLM submitted. The SDK does not currently surface the resulting event ids directly from this result — callers wanting the created events should query the dataset’s events using the time bounds in events. (Surfacing event ids here would require an API-layer round-trip back to the achieve-tool’s response payload; YAGNI until a caller needs it.)

Parameters:

data (Any)

goal_type: Literal[roboto.ai.goals.types.GoalType.CREATE_EVENTS]#

Discriminator. Always GoalType.CREATE_EVENTS.

class roboto.ai.goals.results.DatasetSummaryGoalResult(/, **data)#

Bases: GoalResultBase, roboto.ai.goals.achieve_inputs.DatasetSummaryAchieveInput

Result of a GoalType.DATASET_SUMMARY achieve-tool invocation.

Exposes the LLM-submitted summary directly alongside the raw achieve_tool_use / achieve_tool_result blocks.

Parameters:

data (Any)

goal_type: Literal[roboto.ai.goals.types.GoalType.DATASET_SUMMARY]#

Discriminator. Always GoalType.DATASET_SUMMARY.

class roboto.ai.goals.results.DatasetTriageGoalResult(/, **data)#

Bases: GoalResultBase, roboto.ai.goals.achieve_inputs.DatasetTriageAchieveInput

Result of a GoalType.DATASET_TRIAGE achieve-tool invocation.

Exposes the full per-label deliberation in label_decisions; use applied_labels for the convenience subset that actually became tags on the dataset.

Parameters:

data (Any)

property applied_labels: list[str]#

Labels for which the LLM voted applies=True.

Matches the set of tags the achieve-tool persisted on the dataset. Returned in declaration order, not the (sorted) order in which the achieve-tool writes them to the dataset; for stable ordering use sorted(result.applied_labels).

Return type:

list[str]

goal_type: Literal[roboto.ai.goals.types.GoalType.DATASET_TRIAGE]#

Discriminator. Always GoalType.DATASET_TRIAGE.

roboto.ai.goals.results.GoalResult#

Closed, Roboto-controlled discriminated union of every typed goal result.

Validated via pydantic discriminator on goal_type. Mirrors the shape of AgentGoal so adding a new goal type means:

  1. Add a new GoalType member.

  2. Add a new AgentGoal subclass in roboto.ai.goals.types.

  3. Add a matching achieve-input model in roboto.ai.goals.achieve_inputs.

  4. Add a new GoalResult subclass here that inherits from both GoalResultBase and the new achieve-input model.

No API or wire-schema change is needed because the SDK builds the result from the persisted message stream via achieve_tool_use_id.

class roboto.ai.goals.results.GoalResultBase(/, **data)#

Bases: pydantic.BaseModel

Shared base for every concrete GoalResult.

Subclasses must declare a literal-typed goal_type field so the discriminated union can dispatch — and must also inherit from the matching achieve-input model from roboto.ai.goals.achieve_inputs so the parsed typed fields land alongside the raw blocks.

Parameters:

data (Any)

achieve_tool_result: roboto.ai.core.content.AgentToolResultContent | None = None#

The AgentToolResultContent the runner observed for the matching tool_use_id, if any. None when the runner persisted a tool_use but no corresponding tool_result reached the chunk log before the turn terminated.

achieve_tool_use: roboto.ai.core.content.AgentToolUseContent#

The AgentToolUseContent the LLM submitted. input carries the raw arguments; the parsed typed fields on the subclass are derived from it.

status: roboto.ai.goals.types.AgentGoalStatus#

ACHIEVED or FAILED.

Type:

Terminal status of the goal

On this page