Orchestrator

Recurring runs are delegated to an orchestrator. Two are supported, and they are interchangeable: the client for each implements the same method surface, so nothing in the calling code changes when you switch.

`ORCHESTRATOR`	Backend	Notes
`mage`	Mage AI	the default — used when the variable is unset
`th2etl`	th2etl	the in-house replacement

Only these two values change behavior. Anything else is read as an unrecognized setting and falls back to mage — there is no third backend.

The setting is read by the listing endpoints too, not only when a schedule is created. A deployment that flips the flag without restarting keeps reading the previous orchestrator, and the runs created on the new one never appear.

Orchestrator screen listing agents with their model, schedule and run actions — The orchestrator screen: one row per agent, with its model, its schedule and a manual trigger.

Scheduling a run

POST /api/adk/schedule_run
{
  "agent_id": "agent42",
  "user_id": "user@example.com",
  "session_id": "session_scheduled",
  "new_message": {
    "role": "user",
    "parts": [{ "text": "Generate the daily report" }]
  },
  "schedule_interval": "@daily",
  "start_time": "2026-03-10T08:00:00"
}

Interval shortcuts

Preset	Cron
`@hourly`	`0 * * * *`
`@daily` — also `@midnight`	`0 0 * * *`
`@weekly`	`0 0 * * 0`
`@monthly`	`0 0 1 * *`
Custom	e.g. `/15 * * *`

Mage accepts the @interval shortcuts directly. The th2etl client translates them into five-field cron expressions before creating the trigger, so the same request body works against either backend.

Managing schedules and runs

Method	Endpoint	Description
GET	`/api/pipelines`	List pipelines
POST	`/api/pipelines/agents/triggers`	Create a trigger for an agent
GET	`/api/pipelines/{pipeline_uuid}/schedules`	List an agent’s schedules
PUT	`/api/pipelines/{pipeline_uuid}/schedules/{schedule_id}`	Update a schedule
GET	`/api/pipelines/{pipeline_uuid}/schedules/{schedule_id}/runs`	List a schedule’s runs
GET	`/api/pipelines/runs/{run_id}`	Get one run
GET	`/api/pipelines/runs/{run_id}/logs`	Get a run’s logs
PUT	`/api/pipelines/runs/{run_id}/cancel`	Cancel a run

The endpoints keep the pipelines naming from the Mage era. They are orchestrator agnostic: the same calls reach th2etl when the flag is set.

What changes between the two

The mapping matters if you inspect the orchestrator directly rather than through this API.

	Mage	th2etl
Unit per agent	a pipeline trigger	one scheduler, named after the `agent_id`
Schedule identifier	an integer id	the scheduler name
Per-trigger variables	trigger variables	the scheduler’s `variables`, injected into the run context on every fire
Ad-hoc trigger	trigger a run	`POST /schedulers/{name}/run`

Identifiers are opaque to callers — read one from a listing and pass it back. Do not compare them numerically: Mage ids are integers while th2etl uses names, and a numeric comparison against a th2etl id silently fails to match.

Configuration

See Configuration for the variables each orchestrator needs. When ORCHESTRATOR is unset, the server talks to Mage — so a deployment that means to use th2etl must set it explicitly.

Get started

Concepts

Business Agents

Frontend

Automation

AgentOps

Integrations

Tools & Skills

Ecosystem

Contributing

Scheduling a run

Interval shortcuts

Managing schedules and runs

What changes between the two

Configuration

​Scheduling a run

​Interval shortcuts

​Managing schedules and runs

​What changes between the two

​Configuration

Scheduling a run

Interval shortcuts

Managing schedules and runs

What changes between the two

Configuration