Skip to main content

Schedules

The Schedules screen lets you run an agent on a cron expression, in a time zone, with a fixed input, and change, pause or delete these schedules. Portal path: /agents/schedules. Developers, application owners and tenant administrators manage the schedules of their agents. The screen is drawn by portal/src/screens/agents.tsx.

What the screen shows​

  • Schedules table, read with GET /v1/schedules (every schedule of the tenant in one call, oldest first). Columns: Id, Agent id, Cron, Time zone, Enabled, Next run, Last run.
  • When the list is empty: No schedule, with the hint Run an agent every day, week or month. and the button New schedule.
  • The row menu View details shows every field of the row in a side panel (the API has no detail route for a schedule).
  • New schedule opens a side panel with the fields Agent id (required), Cron (required, example 0 8 * * 1-5), Time zone (default Europe/Paris), Input (JSON, default {}), Enabled (default on).

Actions​

Button or actionWhat it doesAPI callRoles
Refresh (icon)Reloads the list.GET /v1/schedulesAny tenant member
New scheduleCreates the schedule; the Control Plane checks the cron expression and the time zone and computes the next run.POST /v1/schedulestenant_admin, developer, application_owner
Row menu View detailsShows the row in a side panel.NoneAny tenant member
Row menu EditForm Cron (required) and Enabled, submitted with Edit. Turn Enabled off to pause the schedule.PATCH /v1/schedules/{schedule_id}tenant_admin, developer, application_owner
Row menu DeleteOpens Confirm a destructive action; type the schedule id, then Confirm.GET /v1/lineage/graph, then DELETE /v1/schedules/{schedule_id}tenant_admin, developer, application_owner
Retry (error state)Sends the failed read again.Same callSame roles

The New schedule form sends this body:

{"agent_id": "invoice-assistant", "cron": "0 8 * * 1-5", "timezone": "Europe/Paris", "input": {}, "enabled": true}

0 8 * * 1-5 runs the agent at 08:00, Monday to Friday, in the chosen time zone.

Roles​

The portal hides no button. In services/control-plane/src/eai/domains/agents/routes.py, create, edit and delete check WRITE_ROLES (tenant_admin, developer, application_owner, from services/control-plane/src/eai/domains/agents/kit.py); the list only needs a tenant. platform_admin passes every role check. The run started by a schedule is subject to the same rules as any run: the agent must be active and within its budgets.

Typical tasks​

Run an agent every working day​

  1. Find the agent. A schedule points to one agent. Copy its id or name from the Registry. Expected result: you have the agent reference. If it fails: when the agent is missing, register it first.
  2. Create the schedule. The cron expression fixes the rhythm. Click New schedule, fill Agent id, type 0 8 * * 1-5 in Cron, keep or change Time zone, add an Input when the agent needs one, then click Create. Expected result: the toast Created and a row with its Next run. If it fails: invalid_cron (422) gives the reason, fix the expression or the time zone; scheduler_unavailable (503) means the Temporal scheduler backend refused the schedule, contact the platform team.
  3. Check the first run. The scheduler starts the run at the next date. After that time, open the Runs screen. Expected result: a new run of the agent; the schedule shows a Last run. If it fails: check that Enabled is on and that the agent is active in the Registry.

Pause a schedule​

  1. Edit it. Pausing keeps the schedule for later. In the row menu, click Edit, turn Enabled off, then click Edit. Expected result: the toast Done and Enabled is off in the row. If it fails: schedule_not_found (404) means the schedule was deleted meanwhile; click Refresh.

Troubleshooting​

SymptomCauseFix
invalid_cron (422): "Invalid cron expression: ..."The expression or the time zone is not valid.Use five fields (minute, hour, day, month, weekday) and an IANA time zone such as Europe/Paris.
agent_not_found (404) on CreateAgent id names no agent of the tenant.Copy the id or the name from the Registry.
schedule_not_found (404)The schedule no longer exists.Click Refresh.
scheduler_unavailable (503) on Create or EditThe Temporal scheduler backend is configured but does not answer.Ask the platform team to check the Temporal service, then retry.
forbidden (403) with required_rolesYour roles are not tenant_admin, developer or application_owner.Ask a tenant administrator for one of these roles.
Invalid JSON under InputThe input is not valid JSON.Fix the JSON, for example {}.
No new run at the planned timeEnabled is off, or the agent is suspended or killed and its new runs are refused.Turn Enabled on, or resume the agent.