Actions#

Overview#

An action is a containerized function — packaged as a Docker image — that runs on Roboto’s managed compute infrastructure. Actions are the workhorse of repeatable data processing in Roboto.

Actions ingest raw log files into Roboto’s data model and post-process that data after ingestion. An action can work with raw files downloaded from a dataset, or read already-ingested topic data as structured records without downloading the original files. Actions can also write results back to a dataset, add tags and metadata, and create events.

Actions range from simple scripts to sophisticated transformations. Roboto ships with a library of ready-to-use actions for common robotics workflows, and you can build and deploy your own.

Actions complement agents: an action runs your own containerized code deterministically, while an agent applies AI judgment using Roboto’s built-in tools. Reach for an action when the job is repeatable data processing — ingestion, transformation, report generation. Reach for an agent when the work needs analysis, search, or judgment.

The Action Hub#

The Action Hub is Roboto’s catalog of actions. It includes ingestion actions for ROS, PX4, Ardupilot, and other supported formats, along with analysis and utility actions.

Your organization’s deployed actions are available from the Actions page in the Roboto web UI.

Action lifecycle#

A typical workflow:

  1. Develop — Write your action code and define its configuration in action.json. roboto actions init scaffolds a new action project.

  2. Test locally — Use roboto actions invoke-local to run your action against real data without deploying.

  3. Deploy — Build and push your Docker image, then register the action with your Roboto organization using roboto actions create or the generated deploy.sh script.

  4. Invoke — Run the action on hosted compute, either manually or automatically via a trigger.

  5. Monitor — Follow live logs and check invocation status as it runs.

See the Process Data with Actions user guide for a step-by-step walkthrough, or Create Your Own Action to build and deploy a custom action. Example actions are also available on GitHub.

Configuring an action#

Each action is defined by an action.json file that specifies its name, description, parameters, compute requirements, and more. See the Action Configuration reference for the complete schema.

Parameters customize an action’s behavior at invocation time without changing its code: for example, a signal threshold, a topic name, or an output format. Parameters can be required or optional and can have default values.

Compute requirements set the CPU, memory, and storage allocated to each invocation. See the Compute page for available options and how usage is measured.

Invocations#

An invocation is a single execution of an action. When an action is invoked, Roboto:

  1. Provisions an isolated container with the requested compute resources.

  2. Downloads input files into the container’s workspace (if requires_downloaded_inputs is enabled).

  3. Runs the action’s entrypoint, passing in dataset context and any parameter values.

  4. Streams container logs in real time.

  5. Uploads any files written to the action’s output directory back to the dataset.

  6. On exit, shuts down the container and records the final status.

Each invocation has a unique identifier prefixed with iv_.

To monitor an invocation:

# Check status
roboto invocations status <invocation_id>

# Stream live logs
roboto invocations logs --tail <invocation_id>

See the roboto invocations CLI for the full list of commands.

Triggers#

A trigger is a rule that automatically responds to activity in your Roboto organization. A trigger fires on one or more platform events — a file finishing ingestion, an invocation failing, a dataset gaining a tag — optionally filters them with a condition, and when a platform event matches, runs its targets: invoke an action, start an agent, or send a Slack message. Triggers are the primary way to build automated data pipelines in Roboto. For example, you can ingest every log file as it is uploaded, run a diagnostic action whenever a file finishes ingestion, or have an agent investigate every failed invocation.

Triggers created under Roboto’s earlier trigger model are migrated to this model automatically; you don’t need to recreate them.

Platform events#

A platform event describes something that happened to your data or workloads. A trigger fires only for the platform event types it subscribes to. Platform events are distinct from events, the time-anchored annotations you place on your data; see Key Terms. Platform events cover:

  • Files — a file was uploaded, finished ingestion, or had its tags or metadata changed. Use file ingested when your processing reads ingested topic data rather than raw files.

  • Datasets — a dataset was created, had its metadata updated, gained a tag, or completed an upload batch.

  • Invocations — an action invocation completed or failed. Useful for chaining processing steps or alerting on failures.

  • Sessions — a session was created, updated, or had files added.

  • Events — an event was created on your data, for example by an action that flags anomalies.

A trigger can subscribe to several platform event types at once, as long as they are about the same kind of entity and its condition and targets make sense for all of them. The web UI’s Trigger On picker offers the file and dataset-metadata events; the rest are subscribed with --on on roboto triggers create, which lists every subscribable type in its help output.

A trigger can instead fire on a schedule: a cron expression evaluated in UTC, such as 0 9 * * 1 for 09:00 every Monday. A schedule-fired trigger has no platform event to condition on, so it runs its targets on every scheduled minute; an action target selects its inputs with a query (files or topics matching a RoboQL expression) rather than file patterns. Minutes missed while the scheduler is unavailable are skipped rather than run late, and a trigger whose action has been deleted is disabled after the failed run so it stops failing every minute.

Conditions#

A trigger can specify a condition that must hold before it fires. Conditions are evaluated against the entities involved in the platform event, addressed by context: dataset fields as dataset.*, file fields as file.*, invocation fields as invocation.*, and so on. For example, a trigger can fire only when dataset.tags contains production, or when a metadata field on the file matches a given value.

The web UI’s Conditions builder covers the common case: each row is one requirement on a dataset’s or a file’s tags, metadata, created or created_by, combined with AND or OR. Conditions over anything else the platform event exposes are written as JSON and passed to the CLI with --condition-json. To see what a given platform event type makes available to a condition, ask for a sample:

# Every field path a file-ingested platform event exposes
roboto triggers sample file.ingested --paths

# The whole sample platform event, fully dereferenced
roboto triggers sample invocation.failed

Targets#

A target is what a trigger does when a platform event matches its subscription and condition. A trigger can have one target or several, and each runs independently:

  • Invoke action — run an action, just as if you invoked it manually. The action runs against a dataset, so this target needs a file or dataset platform event (or a schedule). Required inputs glob patterns (for example '**/*.bag', or '**/*' for any file) select which files the invocation operates on, and you can set parameter values and compute overrides per trigger.

  • Start agent — launch one of your organization’s agents with inputs filled in from the platform event, using placeholders such as {{dataset.dataset_id}}.

  • Send Slack message — post a templated message to a connected Slack channel, for example to announce a failed invocation or a newly ingested dataset.

The Roboto web UI creates and edits triggers with a single invoke-action target. Triggers with several targets, or with an agent or Slack target, are created with roboto triggers create --targets-json, which takes one target spec or a list of them, each discriminated on type (invoke_action, start_agent, or send_slack_message):

roboto triggers create \
    --name investigate-failures \
    --on invocation.failed \
    --once-per invocation \
    --targets-json '[{"type": "start_agent", "target_id": "investigate", "agent_id": "ag_abc123"}]'

Fire once per#

The fire once per setting controls how often a trigger fires for related platform events, so retries and re-deliveries don’t run your targets twice:

  • File — at most once per matching file, even if the same file is uploaded again. Use this when your target processes individual files; an action target receives the matching file as its input.

  • Dataset — at most once per dataset. Use this when your target operates on the dataset as a whole; for an action target, Roboto waits until every required-inputs pattern has a matching file before invoking.

  • Invocation, Session — at most once per invocation or session.

  • Occurrence — every time, with nothing collapsed. A re-upload of the same file is a new occurrence; an action target still receives the file as its input.

Which settings are available depends on the subscribed platform events.

The web UI’s Invoke For Each setting on the create-trigger form chooses between once per file and once per dataset. The others are set with --once-per on roboto triggers create.

Testing a trigger#

roboto triggers dry-run explains, gate by gate, whether a trigger would fire for a specific piece of data — without running anything. Name a dataset, file, invocation, or session, and Roboto walks through every gate the trigger would apply: subscription, enabled state, each condition clause with the actual values it saw, and each target’s own checks.

roboto triggers dry-run my-trigger --dataset-id ds_abc123
roboto triggers dry-run my-trigger --file-id file_abc123 --on file.ingested

Pass exactly one of --dataset-id, --file-id, --invocation-id or --session-id. --on picks which of the trigger’s subscribed platform events to synthesize; it defaults to the first one compatible with the entity you named. Use this to debug why a trigger did or didn’t fire.

Dispatch history#

Each time a trigger fires a target, Roboto records a dispatch: which platform event matched, which target ran, whether it succeeded, and a link to the result — the invocation, agent thread, or message. A trigger’s page in the web UI has an Evaluation History tab listing the times it fired and an Invocations tab listing the invocations it produced, and a dataset’s file browser shows when triggers were last evaluated for that dataset with a link to its evaluation history.

Example: post-ingestion analysis#

A common pattern is to run an analysis action automatically after ingestion completes. Subscribe a trigger to the file ingested platform event with an invoke-action target, and the action can read topic data as a structured dataframe without downloading the raw log file.

Managing triggers#

Create and manage triggers from the Triggers page in the Roboto web UI, or from the CLI:

roboto triggers list
roboto triggers get my-trigger
roboto triggers enable my-trigger
roboto triggers disable my-trigger
roboto triggers delete my-trigger

The Triggers page lists and edits triggers that invoke a single action, fire once per file or per dataset, and subscribe only to the file-uploaded, file-ingested, file-metadata-updated and dataset-metadata-updated platform events. Triggers outside that shape — several targets, an agent or Slack target, or any other platform event — are created and managed with the CLI or the Python SDK, and do not appear in that list.

See the roboto triggers CLI reference for the full list of commands.

On this page