Goals#

Overview#

A goal is a structured outcome you attach to a turn of a thread — like “triage this dataset against my label vocabulary” or “create events for every hard-braking interval”. Where a plain chat message asks the AI to do something, a goal requires it: the AI must achieve every declared goal before the turn can complete successfully.

Key properties:

  • Goals are declared per turn, not per thread. A turn may carry a message, goals, or both — declaring goals alone is enough to start a turn.

  • Each goal has a lifecycle: pending while the AI works, then achieved or failed. If any goal fails, the turn fails rather than quietly succeeding.

  • Goal results are structured data, not just chat text: a triage goal records a decision, justification, and confidence for every label; an events goal records every event submitted.

  • Goal types are built into Roboto, each wired to a specific platform action — this is how the AI’s write capabilities stay scoped.

Goal types#

Dataset summary#

Generates a summary of a dataset and persists it, so it appears on the dataset page. Optionally takes a format-spec prompt describing the structure you want (“bulleted, lead with anomalies, max 200 words”).

from roboto.ai.goals import DatasetSummaryAgentGoal

goal = DatasetSummaryAgentGoal(
    dataset_id="ds_abc123",
    summary_format_spec_prompt="Lead with anomalies, then a topic-by-topic recap.",
)

Dataset triage#

Deliberates over a label vocabulary you supply — up to 50 labels, each with a description of what it signifies — and applies the labels that fit (zero or more) as tags on the dataset. Every label gets an explicit decision with a justification and confidence, recorded in the thread.

from roboto.ai.goals import DatasetTriageGoal

goal = DatasetTriageGoal(
    dataset_id="ds_abc123",
    label_vocabulary={
        "crash": "The robot made unplanned contact with an obstacle or the ground.",
        "gps-degraded": "GPS accuracy dropped below usable thresholds for any period.",
        "needs-review": "Anything anomalous a human should look at.",
    },
)

Label names become dataset tags, so they must use the tag-safe character set (letters, numbers, underscore, hyphen).

Create events#

Investigates a dataset and creates events on it, drawn from an event vocabulary you supply (event name → description of what qualifies). Optionally:

  • a tag vocabulary constrains which tags created events may carry;

  • a collection ID files every created event into an event collection;

  • a focus prompt layers extra guidance on top (“only flag intervals longer than five seconds”).

from roboto.ai.goals import CreateEventsGoal

goal = CreateEventsGoal(
    dataset_id="ds_abc123",
    event_vocabulary={
        "hard_braking": "Deceleration exceeding 0.5g sustained for over 250ms.",
        "gps_dropout": "An interval where GPS fix quality is lost or degraded.",
    },
    tag_vocabulary={
        "severe": "Apply when the event likely impacted the mission outcome.",
    },
    collection_id="cl_abc123",
    event_focus_prompt="Only flag intervals longer than five seconds.",
)

The AI can only create events of the declared kinds with the declared tags — the vocabularies are enforced, not advisory.

Declaring goals#

Attach goals to the turn that starts a thread, or to any later turn. A message is optional when goals are declared:

from roboto.ai import AgentThread
from roboto.ai.goals import DatasetTriageGoal

thread = AgentThread.start(
    goals=[
        DatasetTriageGoal(
            dataset_id="ds_abc123",
            label_vocabulary={
                "crash": "The robot made unplanned contact with an obstacle or the ground.",
                "nominal": "The run completed without incident.",
            },
        )
    ],
)
thread.run()

Add goals to an existing thread with send_text():

thread.send_text(
    "Also check the battery telemetry.",
    goals=[DatasetSummaryAgentGoal(dataset_id="ds_abc123")],
).run()

In the web app, each turn’s goals appear in the thread as a strip of status chips that update as the AI works.

Inspecting results#

After a turn completes, read structured results from the thread:

for goal in thread.goals:
    print(goal.goal_type, goal.status)
    result = goal.result
    if result is not None:
        print(result)

Each goal type has a typed result:

  • Dataset summary — the persisted summary text.

  • Dataset triage — one decision per vocabulary label (does it apply, why, and with what confidence), plus applied_labels, the labels that became tags.

  • Create events — the list of events the AI submitted, with their time bounds and tags.

If a goal cannot be achieved within the turn’s retry budget, its status is failed and run() raises RobotoAgentGoalsFailedException, so automation never mistakes an incomplete turn for a successful one.

Goals and automation#

Goals are the foundation for repeatable agent workflows. An agent can carry goals with {{variable}} placeholders — for example, a “triage” agent whose dataset_id is filled in per launch. That turns a one-off request into a one-click (or one-API-call) operation for your whole team.

On this page