---
title: Concepts
sidebar:
  order: 5
---
Roboto makes it easy to manage, process, and analyze your data.

![Platform Overview](/docs/blume-assets/content/docs/_static/overview.png)

For example, you can:

- Upload log files into datasets and share them with your team
- Add tags and metadata to datasets e.g. `crash` or `sw_version=3.4.2`
- Visualize log data from multiple files in interactive dashboards
- Generate artifacts by post-processing log files with custom actions
- Create events on slices of data to mark important moments
- Search data to find relevant logs and edge cases
- Ask an agent to search, summarize, triage, and annotate your data

Learn the basics of Roboto, including core concepts and essential terminology below.

## Overview [#overview-section]

In Roboto, you create [datasets](/docs/learn/concepts#datasets-section) and upload (or import) log [files](/docs/learn/concepts#files-section) to them.

Log files are [ingested](/docs/learn/concepts#ingestion-section) using specialized [actions](/docs/learn/concepts#actions-section). Roboto includes built-in ingestion actions for common robotics formats like `ros`, `px4` and `parquet`. It's also possible to create ingestion actions for custom log formats too.

During ingestion, log files are processed to index and optimize their constituent [topics](/docs/learn/concepts#topics-section). Once ingested, topic data can be queried and visualized.

Additionally, you can create and invoke custom [actions](/docs/learn/concepts#actions-section) to post-process your data. For example, you can automatically generate [events](/docs/learn/concepts#events-section) or detailed reports.

Roboto also lets you run [agents](/docs/learn/concepts#agents-section) that search, explore, and analyze your data conversationally — and, through [goals](/docs/learn/concepts#goals-section), do verifiable work like triaging datasets and creating events. See [Agents](/docs/learn/ai) for an overview.

![Data Model Overview](/docs/blume-assets/content/docs/_static/model-overview.png)

## Key Terms [#terms-section]

### Action [#actions-section]

An **action** is a reusable function to process, transform or analyze data in Roboto. Actions can be [invoked](/docs/learn/concepts#invocations-section) manually, or automatically with [triggers](/docs/learn/concepts#triggers-section).

Actions are used to ingest raw log files into Roboto's data model, and to post-process data once it has been ingested. Depending on what an action needs to do, it can work with raw files downloaded from a dataset, or read ingested topic data directly. Actions can also programmatically add tags, metadata, or events to items in Roboto.

The underlying code for an action needs to be in a Docker [image](/docs/learn/concepts#images-section) and pushed to a registry. During creation, actions must be assigned a unique name by which they can be referenced. Additionally, actions can be defined with any number of optional or required parameters.

Actions can use [secrets](/docs/learn/concepts#secrets-section) to access sensitive information at runtime.

See the [Actions](/docs/learn/actions) page or the [Process Data with Actions](/docs/user-guides/process-data-actions) user guide for additional information.

### Agent [#agents-section]

An **agent** is a purpose-built AI worker you define and run on your data: a saved prompt with typed `{{variable}}` placeholders, optionally paired with [goals](/docs/learn/concepts#goals-section). Each launch starts a [thread](/docs/learn/concepts#threads-section) in which the agent answers questions, searches and analyzes data, and does verifiable work like triaging datasets and creating events. The same agent can be launched repeatedly with different inputs.

Agents differ from [actions](/docs/learn/concepts#actions-section): an action runs your own containerized code deterministically, while an agent is an LLM working with Roboto's built-in tools. Use actions for repeatable data processing; use agents for analysis, search, and judgment calls.

See the [Agents and Threads](/docs/learn/ai/agents) page for additional information.

### Collection [#collections-section]

A **collection** is a versioned container for grouping related resources. Collections can hold [datasets](/docs/learn/concepts#datasets-section), [files](/docs/learn/concepts#files-section), or [events](/docs/learn/concepts#events-section) — each collection holds one resource type, chosen at creation time.

For example, a file collection might gather camera images from ten separate flight datasets to build a training set, or an event collection might curate all "hard braking" events identified across a month of autonomous vehicle logs.

Every change to a collection — adding or removing resources, or updating its name, tags, or description — is versioned, so you can review the full history of any collection. Collections can be shared with specific users; sharing extends to the contents, so anyone who can view a collection can also view the datasets and files it references.

Collections are assigned a unique identifier beginning with the `cl_` prefix.

See the [Collections](/docs/learn/collections) page for additional information.

### Dataset [#datasets-section]

A **dataset** contains [files](/docs/learn/concepts#files-section) in a directory structure similar to Dropbox or Google Drive.

Typically, a dataset stores the files from a single robot activity, such as a drone flight or an autonomous vehicle mission, however, it's versatile enough to be a general-purpose assembly of files.

Every file in a dataset, whether it's raw or generated, resides under a unique key prefix in a Roboto-managed or user-provided storage bucket. Upon creation, datasets are assigned a unique identifier beginning with the `ds_` prefix.

Datasets can have associated tags and metadata to improve search and capture important context. For example, you could tag a dataset with `crash` or add metadata such as `sw_version=3.4.2`.

See the [roboto datasets CLI](/docs/reference/cli#roboto-datasets) for additional information.

### Device [#devices-section]

A **device** represents a robot, upload station, or other non-human entity which can programmatically interact with Roboto.

Devices are referenced by a user-provided `device_id`. This ID can be any string, but needs to be unique within an org. If available, existing robot serial numbers or other unique identifiers are an excellent choice for `device_id`.

Users can provision scoped access tokens for devices, which enables them to programmatically create [datasets](/docs/learn/concepts#datasets-section), upload [files](/docs/learn/concepts#files-section), and perform other operations.

When a device creates a dataset or uploads a file using its access token, that device's `device_id` is automatically added to the resource as first-class metadata.

See the [Devices](/docs/learn/devices) page for additional information.

### Event [#events-section]

An **event** serves as a "time anchor," enabling you to link key entities—such as [datasets](/docs/learn/concepts#datasets-section), [files](/docs/learn/concepts#files-section), [topics](/docs/learn/concepts#topics-section), and [message paths](/docs/learn/concepts#topics-section)—to a specific timespan.

Events are a powerful way to mark important moments of interest (e.g., `Discharged` or `Takeoff`) and correlate them with the underlying data. You can assign tags and metadata to events, making them easier to discover and organize.

An event is an annotation you place on data; it is not a [platform event](/docs/learn/concepts#platform-events-section), which Roboto emits when something happens to your data or workloads.

Events can be created manually in the visualizer, programmatically via the SDK, or automatically by [actions](/docs/learn/concepts#actions-section). Once created, they are visualized on relevant plots and the timeline, helping you to quickly locate and analyze these key moments during review.

Additionally, by creating events, you can extract the associated data through the SDK, enabling more targeted analysis and streamlined workflows.

See the [Create Events on Data](/docs/user-guides/create-events-on-data) user guide for additional information.

### File [#files-section]

A **file** is an individual data item that has been uploaded or imported to a [dataset](/docs/learn/concepts#datasets-section) in Roboto.

An example file might be `report.pdf` or `recording.bag`; any file type can be stored.

Files that contain structured time-series data can be [ingested](/docs/learn/concepts#ingestion-section) by corresponding [actions](/docs/learn/concepts#actions-section). This indexes their constituent [topic](/docs/learn/concepts#topics-section) data for visualization and search.

Files can also have associated tags and metadata to improve search and capture important context.

### Goal [#goals-section]

A **goal** is a structured outcome attached to a turn of a [thread](/docs/learn/concepts#threads-section); the AI must achieve it before the turn completes. Roboto has three built-in goal types: summarizing a dataset, triaging a dataset against a label vocabulary (applied labels become tags), and creating [events](/docs/learn/concepts#events-section) from an event vocabulary.

Goals record structured results — per-label decisions with justifications, or the list of created events — making agent work verifiable and auditable.

See the [Goals](/docs/learn/ai/goals) page for additional information.

### Image [#images-section]

A **Docker image** is a package that includes all of the source code and dependencies necessary to run an [action](/docs/learn/concepts#actions-section).

After definition, a Docker image can be associated with an action. Images must be pushed to Roboto's registry, or hosted on a public registry such as Docker Hub. We plan to support images hosted in private registries too.

See the [roboto images CLI](/docs/reference/cli#roboto-images) for additional information.

### Ingestion [#ingestion-section]

In Roboto, **ingestion** refers to the process of indexing and summarizing log files. A log file must be ingested before the data it contains can be visualized or queried within Roboto.

Ingestion happens through specialized [actions](/docs/learn/concepts#actions-section), which process raw log files into an optimized format when necessary. During ingestion, log files are analyzed to identify their constituent [topics](/docs/learn/concepts#topics-section), which represent structured time-series data.

A successfully ingested log file has a blue chevron next to it in the dataset file browser. Clicking it reveals the file's topics.

Roboto provides built-in ingestion actions for common robotics formats such as `ros` and `px4`. You can find these in the [Action Hub](https://app.roboto.ai/actions/hub). It's also possible to create ingestion actions for custom log formats. We plan to provide examples of these in the near future. [Contact us](https://www.roboto.ai/contact) to learn more.

See the [Formats](/docs/learn/formats) page for a full list of supported log formats and their corresponding ingestion actions.

### Invocation [#invocations-section]

An **invocation** is a specific execution of an [action](/docs/learn/concepts#actions-section), initiated either manually or automatically by a [trigger](/docs/learn/concepts#triggers-section).

For an action to be invoked, the required data to be processed must be specified, and values for any action parameters need to be provided.

During the execution of an invocation, live logs can be viewed in the Roboto platform or CLI.

Upon creation, invocations are assigned a unique identifier beginning with the `iv_` prefix.

See the [roboto invocations CLI](/docs/reference/cli#roboto-invocations) for additional information.

### MCP [#mcp-section]

An **MCP connection** links an external service to Roboto's AI via the [Model Context Protocol](https://modelcontextprotocol.io), letting AI Chat and [agent](/docs/learn/concepts#agents-section) threads use that service's tools mid-conversation — for example, searching your issue tracker or knowledge base.

Connections are per user: each person authorizes the external service with their own account. An allowlist controls which tools are available; by default, only tools the server marks read-only are enabled.

See the [MCP Connections](/docs/learn/ai/mcp) page for additional information.

### Platform event [#platform-events-section]

A **platform event** is a record of something that happened in your organization: a [file](/docs/learn/concepts#files-section) was uploaded or finished [ingestion](/docs/learn/concepts#ingestion-section), a [dataset](/docs/learn/concepts#datasets-section) gained a tag, an [invocation](/docs/learn/concepts#invocations-section) failed. Roboto emits platform events itself; [triggers](/docs/learn/concepts#triggers-section) subscribe to them and run their targets when one matches.

A platform event is not an [event](/docs/learn/concepts#events-section), which is an annotation you place on a span of your data.

See the [Actions](/docs/learn/actions) page for how triggers use platform events.

### Secret [#secrets-section]

A **secret** provides secure storage for sensitive information like API keys, passwords, and other credentials. They can be used by [actions](/docs/learn/concepts#actions-section) during execution without exposing the actual values through Roboto's APIs.

Each secret is scoped to an organization and has a unique name within that organization. Secret values are never transmitted through Roboto's APIs, providing an additional layer of security.

See the [Secrets](/docs/learn/secrets) page for additional information.

### Skill [#skills-section]

A **skill** is a stored, versioned procedure — written in Markdown — that Roboto's AI can apply during a conversation. Skills capture a team's know-how so the AI follows the same steps every time.

Skills have three accessibility tiers: private, org, and org-editable. AI usage is opt-in per user: you subscribe to a skill and pin the version the AI may use. The AI applies skills automatically when relevant, or you can invoke one manually.

See the [Skills](/docs/learn/ai/skills) page for additional information.

### Thread [#threads-section]

A **thread** is a persistent, multi-turn AI conversation. Threads maintain full history, can be resumed or forked, and can carry [goals](/docs/learn/concepts#goals-section) the AI must achieve before a turn completes.

Threads are created from AI Chat in the web app, from the CLI with `roboto chat start`, programmatically via the SDK, or by launching an [agent](/docs/learn/concepts#agents-section).

See the [Agents and Threads](/docs/learn/ai/agents) page for additional information.

### Topic [#topics-section]

A **topic** is a sequence of structured time-series data linked to a source file. Each topic follows a defined schema, where the *message paths* represent the individual fields or signals within that schema.

The data items within a topic are called *messages*, and each message is structured according to the topic's schema. Conceptually, topics and messages resemble [ROS topics](https://wiki.ros.org/Topics) and [ROS messages](https://wiki.ros.org/Messages).

For example, a topic named `battery_status` might contain message paths like `voltage_v` and `current_a`, each representing individual time-series signals.

In Roboto, topic data can be visualized in plots, maps etc., and statistical summaries and metrics can be queried.

### Trigger [#triggers-section]

A **trigger** is a rule that automatically responds to activity in your organization: it subscribes to [platform events](/docs/learn/concepts#platform-events-section), optionally filters them with a condition, and runs its targets — invoke an [action](/docs/learn/concepts#actions-section), start an agent, or send a Slack message — when a platform event matches.

Triggers can be **event-driven** — firing in response to activity such as a file being uploaded or ingested, dataset metadata being updated, or an invocation failing — or **scheduled**, invoking an action on a recurring cron schedule.

For example, a trigger could run an ingestion action whenever a new log file is uploaded, while a trigger on a schedule could generate a weekly summary report.

During creation, triggers must be given a unique name by which they can be referenced, as well as corresponding parameters.

See the [Actions](/docs/learn/actions) page or the [roboto triggers CLI](/docs/reference/cli#roboto-triggers) for additional information.