---
sidebar:
  hidden: true
title: roboto.ai.goals.types
---
## Module Contents

### AgentGoal

```python
roboto.ai.goals.types.AgentGoal
```

`from roboto.ai.goals import AgentGoal`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/goals/types.py#L278-L281)

Closed, Roboto-controlled discriminated union of all declarable agent goals.

Validated via pydantic discriminator on `goal_type`. Add new goals by extending the `Union` and registering a corresponding `GoalHandler`.

A goal is the right primitive when the caller has an upfront, verifiable platform mutation the turn must complete — and is willing to fail the turn (`AgentThreadStatus.GOALS_FAILED`) if the action doesn't happen. Goals power specialized agents with deterministic, directionally opinionated behavior. One-off LLM-discovered actions and pure reads belong as regular `AgentTool` registrations; actions that don't need an LLM at all belong as direct REST endpoints. The registry is closed to keep this discipline visible at PR-review time.

### AgentGoalBase

```python
class roboto.ai.goals.types.AgentGoalBase(/, **data: Any)
```

`from roboto.ai.goals.types import AgentGoalBase`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/goals/types.py#L54-L86)

Bases: `pydantic.BaseModel`

Shared base for every [`AgentGoal`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoal) subclass.

Subclasses must declare a literal-typed discriminator field, e.g. `goal_type: Literal[GoalType.MY_GOAL] = GoalType.MY_GOAL`. Two machineries enforce that contract:

- `__pydantic_init_subclass__()` raises `TypeError` at class-body parse if a subclass forgets `goal_type` — converts a silent dispatch footgun into a loud failure.
- `_force_discriminator_into_fields_set()` marks `goal_type` as explicitly set after construction so it survives the SDK's `model_dump_json(exclude_unset=True)` serialization and reaches the server's discriminated-union parser. Without it, default-valued `goal_type` would be stripped on the wire and the server would 400 with "Request body malformed".

**Parameters**

- **data** (`Any`)

### AgentGoalStatus

```python
class roboto.ai.goals.types.AgentGoalStatus
```

`from roboto.ai.agent_thread import AgentGoalStatus`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/goals/types.py#L35-L51)

Bases: `roboto.compat.StrEnum`

Lifecycle of a per-turn declared goal.

Goals begin PENDING when registered. They transition to ACHIEVED when the corresponding achieve-tool reports success, or to FAILED when the runner's corrective re-prompt budget for the turn is exhausted (or when the worker cannot construct an achieve-tool for the goal).

**Attributes**

- **AgentGoalStatus.ACHIEVED** = `'achieved'`: Goal's corresponding achieve-tool was invoked successfully.
- **AgentGoalStatus.FAILED** = `'failed'`: Goal could not be achieved within the turn's retry budget.
- **AgentGoalStatus.PENDING** = `'pending'`: Goal has been registered but not yet completed.

### CreateEventsGoal

```python
class roboto.ai.goals.types.CreateEventsGoal(/, **data: Any)
```

`from roboto.ai.goals import CreateEventsGoal`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/goals/types.py#L218-L275)

Bases: [`AgentGoalBase`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoalBase)

Goal: investigate a dataset and create tagged events on it from fixed vocabularies.

The caller declares [`event_vocabulary`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.CreateEventsGoal.event_vocabulary) — a fixed set of event types (name → description) the agent may create — and, optionally, [`tag_vocabulary`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.CreateEventsGoal.tag_vocabulary) — a fixed set of tags (tag → when-to-apply description) the agent may attach. The achieve-tool constrains every submitted event's `name` to an `event_vocabulary` key and every tag to a `tag_vocabulary` key, so the agent can only file events of the declared kinds carrying the declared tags; the descriptions steer which intervals qualify and which tags fit. Every created event is associated with the dataset identified by [`dataset_id`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.CreateEventsGoal.dataset_id). When [`collection_id`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.CreateEventsGoal.collection_id) is set, each created event is also added to that (event) collection; when it is `None`, events are created but not filed into any collection. The dataset id — and the collection id when set — are constructor-injected into the achieve-tool so the LLM cannot redirect the work.

**Parameters**

- **data** (`Any`)

**Attributes**

- **CreateEventsGoal.collection_id** (`str | None`) = `None`: Identifier of the collection every created event is added to. `None` (the default) means created events are not filed into any collection. When set, the achieve-tool enforces it as an invariant and the target must be an event collection.
- **CreateEventsGoal.dataset_id** (`str`): Identifier of the dataset to investigate. Every created event is associated with this dataset. The achieve-tool enforces this as an invariant.
- **CreateEventsGoal.event_focus_prompt** (`str | None`) = `None`: Caller-provided natural-language guidance layered on top of the vocabularies (e.g. "only flag intervals longer than five seconds"). `None` means the vocabulary descriptions alone steer the agent. When set, must be 1-`_MAX_EVENT_FOCUS_PROMPT_CHARS` characters; an empty string is rejected so callers don't accidentally suppress the guidance with whitespace-stripped input.
- **CreateEventsGoal.event_vocabulary** (`dict[str, str]`) = `None`: Fixed set of event types the agent may create, mapped to descriptions. Keys are the event names the LLM may choose between — each becomes the `name` of a created event — and values describe what each event type signifies so the LLM can decide which intervals qualify. Must contain at least one entry and at most `_MAX_EVENT_VOCABULARY`.
- **CreateEventsGoal.goal_type** (`Literal[GoalType]`): Discriminator. Always [`GoalType.CREATE_EVENTS`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.GoalType.CREATE_EVENTS).
- **CreateEventsGoal.tag_vocabulary** (`dict[str, str]`) = `None`: Fixed set of tags the agent may attach to created events, mapped to descriptions of when each tag applies. For every event it creates the agent picks a subset (possibly empty) of these tags. Empty (the default) means created events carry no tags. At most `_MAX_TAG_VOCABULARY` entries.

### DatasetSummaryAgentGoal

```python
class roboto.ai.goals.types.DatasetSummaryAgentGoal(/, **data: Any)
```

`from roboto.ai.goals import DatasetSummaryAgentGoal`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/goals/types.py#L89-L108)

Bases: [`AgentGoalBase`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoalBase)

Goal: summarize a specific dataset and persist the result.

The achieve-tool wired to this goal must call `SummaryService.set_dataset_summary` against the dataset identified by [`dataset_id`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.DatasetSummaryAgentGoal.dataset_id) (no other dataset). The format spec is supplied to the LLM as part of the goal prompt block; the achieve-tool itself does not interpret it.

**Parameters**

- **data** (`Any`)

**Attributes**

- **DatasetSummaryAgentGoal.dataset_id** (`str`): Identifier of the dataset to summarize. The achieve-tool enforces this as an invariant.
- **DatasetSummaryAgentGoal.goal_type** (`Literal[GoalType]`): Discriminator. Always [`GoalType.DATASET_SUMMARY`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.GoalType.DATASET_SUMMARY).
- **DatasetSummaryAgentGoal.summary_format_spec_prompt** (`str | None`) = `None`: Caller-provided natural-language guidance about the desired summary structure. `None` means use the handler's opinionated default. When set, must be 1-4000 characters; an empty string is rejected so callers don't accidentally suppress the default with whitespace-stripped input.

### DatasetTriageGoal

```python
class roboto.ai.goals.types.DatasetTriageGoal(/, **data: Any)
```

`from roboto.ai.goals import DatasetTriageGoal`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/goals/types.py#L123-L169)

Bases: [`AgentGoalBase`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoalBase)

Goal: deliberate over a caller-supplied label vocabulary and apply the labels that fit.

The achieve-tool requires one decision per vocabulary entry — each with `applies: bool` plus a justification and confidence. Labels with `applies=true` (zero or more) become tags on the dataset identified by [`dataset_id`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.DatasetTriageGoal.dataset_id); per-label reasoning lives in the agent session log, not on the dataset itself.

**Parameters**

- **data** (`Any`)

**Attributes**

- **DatasetTriageGoal.dataset_id** (`str`): Identifier of the dataset to triage. The achieve-tool enforces this as an invariant.
- **DatasetTriageGoal.goal_type** (`Literal[GoalType]`): Discriminator. Always [`GoalType.DATASET_TRIAGE`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.GoalType.DATASET_TRIAGE).
- **DatasetTriageGoal.label_vocabulary** (`dict[str, str]`) = `None`: Allowable labels for this triage action, mapped to descriptions. Keys are the labels the LLM may choose between; values describe what each label signifies so the LLM can pick correctly. Must contain at least one entry and at most `_MAX_TRIAGE_LABELS`. Each key must match `_TRIAGE_LABEL_PATTERN` (ASCII alphanumerics, underscore, hyphen). Each description must be 1-`_MAX_TRIAGE_DESCRIPTION_CHARS` characters.

### GoalType

```python
class roboto.ai.goals.types.GoalType
```

`from roboto.ai.goals import GoalType`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/ai/goals/types.py#L14-L32)

Bases: `roboto.compat.StrEnum`

Discriminator values for the [`AgentGoal`](/reference/python-sdk/roboto/ai/goals/types#roboto.ai.goals.types.AgentGoal) union.

Each value pairs with exactly one `pydantic.BaseModel` subclass below and one server-side `GoalHandler` registration. The string value is the canonical identifier used in persistence (`agent_session_goals.goal_type`), in the Bedrock-facing achieve-tool name, and in the wire format.

**Attributes**

- **GoalType.CREATE_EVENTS** = `'create_events'`: Investigate a dataset and create events on it, drawn from a caller-supplied event vocabulary; optionally file each created event into a caller-supplied collection.
- **GoalType.DATASET_SUMMARY** = `'dataset_summary'`: Produce and persist a dataset summary via `SummaryService.set_dataset_summary`.
- **GoalType.DATASET_TRIAGE** = `'dataset_triage'`: Deliberate over a caller-supplied label vocabulary and apply the labels that fit (zero or more) as tags on the dataset, with a per-label justification recorded in the agent session log.