Task types

Every task declares a type that selects the tool it runs. This page covers the core task types; iteration lives on the Loops page.

`type: agent`

Runs an agent with a prompt.

Component	Description	Type
agent_ref	Path to the `.agentic.yml` agent to run, relative to the project root.	required for `type: agent`
prompt	The input prompt passed to the agent for this task.	required for `type: agent`
consistency_run	Number of times to run the agent and select the most consistent output. Must be > 1 to enable.	optional (default: 1)
consistency_prompt	Custom evaluation prompt for consistency checking. Overrides Automation-level prompt. Supports Jinja templating with variables: `submission_1`, `submission_2`, `task_description`.	optional
output.mode	`answer` (default) returns the agent’s natural-language answer. `sql` stops once the agent has produced SQL and returns the SQL text instead. See SQL output mode.	optional (default: `answer`)

Agent task consistency runs

You can enable consistency checking on agent tasks by setting consistency_run to a value greater than 1. This runs the agent multiple times with the same prompt and selects the most consistent output:

# Automation-level consistency prompt (applies to all agent tasks)
consistency_prompt: |
  Your custom evaluation prompt here...
  Use {{ submission_1 }}, {{ submission_2 }}, and {{ task_description }}

tasks:
  - name: calculate_revenue
    type: agent
    agent_ref: analytics.agentic.yml
    prompt: "What was our total revenue last quarter?"
    consistency_run: 5 # Run 5 times and pick the most consistent result

  - name: analyze_trends
    type: agent
    agent_ref: analytics.agentic.yml
    prompt: "What are the key sales trends?"
    consistency_run: 3
    # Task-level prompt overrides Automation-level prompt
    consistency_prompt: |
      Compare these trend analyses focusing on directional consistency:
      Submission 1: {{ submission_1 }}
      Submission 2: {{ submission_2 }}
      Are they factually consistent? Answer A or B.

This is particularly useful for:

Critical calculations where consistency is important
Data analysis tasks that may have slight variations in output
Queries involving complex logic where you want to verify the agent’s reasoning

Consistency prompt configuration:

Automation-level: Add consistency_prompt at the root to apply to all agent tasks
Task-level: Add consistency_prompt to a specific task to override the Automation prompt
Default: If not specified, uses the built-in evaluation prompt optimized for data analysis (view the default prompt source)

Available template variables:

{{ submission_1 }} - First output
{{ submission_2 }} - Second output
{{ task_description }} - The task prompt

Note: Custom prompts completely replace the default. To adapt the default for your domain, copy the source and modify the specific rules you need.

SQL output mode

Set output.mode: sql to use an agent as a SQL generator. The agent stops once it has SQL — skipping the natural-language answer — and the SQL text becomes the task’s result. SQL compiled from the semantic model or matched from a verified query is returned without running it; SQL the agent wrote itself gets a LIMIT 0 check first. Pair it with cache to save the SQL to a file and an execute_sql task to run it:

tasks:
  - name: query
    type: agent
    agent_ref: analytics.agentic.yml
    prompt: Aggregate total weekly sales by month.
    output:
      mode: sql
    cache:
      enabled: true
      path: results/cache/monthly_sales.sql

  - name: run_query
    type: execute_sql
    database: local
    sql_file: results/cache/monthly_sales.sql

Automations that the agent would otherwise delegate to can’t be used in SQL mode.

`type: execute_sql`

Executes a SQL query either referenced by filename or provided inline.

Component	Description	Type
sql_file	The sql file within the `data` directory to execute	required (or use `sql_query`)
sql_query	Inline SQL query to execute (alternative to `sql_file`)	required (or use `sql_file`)
database	The name of the `database` to execute the query against	required

You can use either sql_file to reference a SQL file, or sql_query to provide the SQL inline. Note: These options are mutually exclusive—only one should be used at a time. Specifying both in a single task is not allowed.

# Using sql_file
- name: query_with_file
  type: execute_sql
  sql_file: my_query.sql
  database: local

# Using sql_query inline
- name: query_inline
  type: execute_sql
  sql_query: |
    SELECT * FROM users
    WHERE created_at > '2024-01-01'
  database: local

`type: formatter`

Formats the provided template using the outputs of other tasks, then passes the rendered template as output.

Component	Description	Type
template	The template to be rendered and passed as output.	required

`type: workflow`

Runs another Automation as a sub-step.

Component	Description	Type
src	Path to the Automation yml file to execute. Relative to the root of the oxy directory.	required
variables	Variables that are passed through, overriding the sub-Automation’s variables.	optional

Use this to break up complex Automations into smaller, easily testable chunks. The variables key allows parameterization by overriding the sub-Automation’s Automation-level variables. This is particularly useful when embedding an Automation task into a loop:

- name: loop_brands
  type: loop_sequential
  values: ["brand1", "brand2"]
  concurrency: 10
  tasks:
    - name: brand_stats
      type: workflow
      src: brand_stats.automation.yml
      variables:
        brand_rollup: "{{ loop_brands.value }}"

`type: semantic_query`

Runs a query against your semantic model — measures, dimensions, filters, and ordering by name, with the SQL compiled for you. See Using the Semantic Model for every property.

- name: sales_metrics
  type: semantic_query
  topic: sales
  dimensions:
    - orders.order_status
  measures:
    - orders.total_revenue
  limit: 10

Looker and Omni integrations add looker_query and omni_query task types — see Looker.

`type: conditional`

Runs a different set of tasks depending on earlier results. Each branch’s if is a Jinja expression (without the surrounding braces) evaluated against the outputs of previous tasks; the first truthy branch runs. An expression that renders empty, false, 0, or none is falsy.

Component	Description	Type
conditions	List of branches, each with an `if` expression and its own `tasks`	required
else	Tasks to run when no branch matches	optional

- name: check_orders
  type: execute_sql
  database: local
  sql_query: SELECT count(*) AS n FROM orders WHERE created_at > current_date - 1

- name: alert_if_quiet
  type: conditional
  conditions:
    - if: check_orders.n[0] == 0
      tasks:
        - name: explain
          type: agent
          agent_ref: analytics.agentic.yml
          prompt: No orders came in yesterday. Check for upstream data issues.
  else:
    - name: summary
      type: formatter
      template: "{{ check_orders.n[0] }} orders yesterday."

`type: http_request`

Makes an outbound HTTP request — for example, to post results to another system’s API. url, headers, body, and form values are Jinja templates rendered against earlier task outputs, and {{ secrets.NAME }} resolves any project secret listed in secrets.

Component	Description	Type
url	Request URL	required
method	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`	optional (default: `POST`)
headers	Request headers	optional
body	Raw request body. Mutually exclusive with `form`	optional
form	Form fields, sent as `application/x-www-form-urlencoded`	optional
secrets	Names of project secrets to make available as `{{ secrets.NAME }}`	optional
timeout_secs	Request timeout, 1–120 seconds	optional (default: 30)
expected_status	Accepted status codes. When empty, any 2xx succeeds and anything else fails the task	optional
allow_hosts	Hostnames the request may target. When empty, any public host is allowed	optional
persist_to_secret	Write a field of the JSON response back to a project secret: `from` (a JSON pointer such as `/refresh_token`) and `name` (the secret)	optional

Requests to private, loopback, and link-local addresses are always blocked.

- name: notify
  type: http_request
  url: https://api.example.com/v1/reports
  method: POST
  secrets: [EXAMPLE_API_KEY]
  headers:
    Authorization: "Bearer {{ secrets.EXAMPLE_API_KEY }}"
    Content-Type: application/json
  body: '{"text": "Weekly report is ready"}'
  allow_hosts: [api.example.com]

`type: airway`

Runs an Airway ELT pipeline (.airway.yml) as a step. The step completes only once the pipeline’s load has committed, so a following execute_sql task reads fully loaded tables.

Component	Description	Type
pipeline	Path to the `.airway.yml` pipeline, relative to the project root	required
resources	Subset of the pipeline’s resources to run. Omit to run all of them	optional

tasks:
  - name: ingest
    type: airway
    pipeline: pipelines/restaurant_analytics.airway.yml
    resources: [orders, order_checks]
  - name: sales_rollup
    type: execute_sql
    database: warehouse
    sql_file: rollups/sales_daily_metrics.sql

Common task options

Any task can also take:

Component	Description
export	Write the task’s result to a file: `path` (relative to the project root; may use Jinja) and `format` (`csv` or `json` for tabular results; `sql` for `execute_sql` and `semantic_query`, which writes the executed SQL).
cache	File-backed cache: `path` (may use Jinja) and `enabled` (default `true`). The first run writes the task’s result to `path`; later runs skip the task and use the file’s contents instead. Edit the file to change what downstream tasks see; delete it to regenerate.

Caching a task’s output

cache is useful for LLM-generated artifacts you want to review and pin — for example, SQL from an agent in SQL output mode. After the first run, edits you make to the cached file are used on every later run.

The visualize task type has been retired. Automations that still use it fail with an “unknown task type” error — use an agent task instead.

Next steps

Loops

Iterate over values with loop_sequential

Variables

Parameterize tasks with typed inputs

Get started

Data Infrastructure

World Model

Agentic Intelligence

Custom Apps

Automations

Integrations

Edge fleet

Manage

Workspaces

Authentication

Observability

Enterprise

Reference

REST API

Resources

Troubleshooting

Task types

`type: agent`

Agent task consistency runs

SQL output mode

`type: execute_sql`

`type: formatter`

`type: workflow`

`type: semantic_query`

`type: conditional`

`type: http_request`

`type: airway`

Common task options

Caching a task’s output

Next steps

Loops

Variables

​type: agent

​Agent task consistency runs

​SQL output mode

​type: execute_sql

​type: formatter

​type: workflow

​type: semantic_query

​type: conditional

​type: http_request

​type: airway

​Common task options

​Caching a task’s output

​Next steps

Loops

Variables

`type: agent`

Agent task consistency runs

SQL output mode

`type: execute_sql`

`type: formatter`

`type: workflow`

`type: semantic_query`

`type: conditional`

`type: http_request`

`type: airway`

Common task options

Caching a task’s output

Next steps