Scheduled Tasks and Approvals

Scheduled Tasks and Approvals#

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

Beyond authoring and deploying a configuration, the genai command line tool does two more things: it schedules an agent to run on its own, and it decides which tools the agent may use without a person approving the call first. This page explains both. For the full flag-by-flag reference, see the genai task section on the CLI Reference page.

A tool is an action an agent can take besides writing an answer, such as searching documents, querying a knowledge graph, running code, or calling out to an external system. Which tools exist in a project comes from the configuration you deploy, for example the MCP resource for an external Model Context Protocol server, and from the capability preferences that turn each kind on or off. For the full list, see the Preference Reference page.

A task is not part of the configuration you write and deploy. Tasks are created and managed on their own, with the genai task command. The genai deploy command neither creates nor removes tasks. What the commands share is the project. A task belongs to a Squirro project, the same one you deploy the configuration to, and each run behaves like an ordinary conversation with that project, using the configuration already deployed to it. Deploy the configuration first, then create the task. A task run only starts a conversation and produces its answer, so it leaves the agents, tools, and every other part of the deployed configuration untouched.

Scheduled Tasks#

A scheduled task is an instruction you save once together with the times at which it should run. At each of those times, the platform sends the instruction to the project on your behalf, and the agent answers it as it would answer anyone. Each run creates a conversation you can open afterwards to read the answer. Use a task for recurring work such as a daily digest, a weekly report, or a periodic check.

Every task has an owner, the user who created it, and every run acts as that user. A run therefore reaches only the content and tools that user is allowed to reach, and a task stops producing useful results if that user loses access to the project.

You create a task with a recurrence, a time, and a timezone. The recurrence is daily, weekly, monthly, or annually, and it determines which extra fields are required: a weekly task names the days of the week, a monthly task names the day of the month, and an annually task names both the day and the month.

genai task create \
  --name "Nightly document digest" \
  --instruction "Summarize the documents added today and post the summary." \
  --recurrence daily --time 02:00 --timezone Europe/Zurich

This runs every day at 02:00 in the Europe/Zurich timezone. A task has two switches that decide whether it fires on its own: --enabled and --disabled pause or resume the whole task, and --auto-fire and --no-auto-fire control the schedule alone. A task fires on its schedule only when both are on, so create it with --disabled to set it up now and start it later. The second switch goes by different names depending on where you meet it: auto-fire in command line output, and trigger.enabled over the API.

The command line tool is not the only way to create a task. A user can also ask an agent in Chat to set one up, and the result is an ordinary task that genai task list shows alongside the rest. The capability that governs this is capability.tasks.enabled, which is on for every project. A scheduled run cannot do the same, so a task never creates or reschedules another task.

You can run a task immediately with genai task run, review its history with genai task runs, and re-run a run that failed or ended without finishing with genai task retry. A manual run fires whatever the two switches are set to, which lets you test a task before you let its schedule start it. For every flag, see the CLI Reference page.

Human Approval#

Some tools an agent can call do more than read data. They send, change, or delete something, and the effect is hard to take back, so you may want a person to check the call before it runs. Sending an email or deleting a record is a different matter from running a search.

A tool is marked as needing approval where it is defined, for example on an MCP server. Approval rules do not make that decision. They answer the next question: when such a tool is about to run, what happens. Each rule matches a tool name against a pattern and gives an answer, called a disposition. Rules are matched in order and the last one that matches wins, so you can write a broad rule first and a narrow exception after it.

The dispositions are:

approve

Let the call run without asking anyone.
reject

Refuse the call. The agent is told, and it plans around the refusal.
interactive

Pause and ask the person in the conversation to approve the call before it runs.
defer

Park the run and wait for someone to approve the call later. The run continues from where it stopped once approved.
hide

Take the tool away from the agent, so it never tries to call it in the first place.

Only hide applies to every tool. The other four take effect on tools marked as needing approval, and any other tool runs as usual whatever the rules say.

When a tool needs approval but matches no rule, the answer depends on who is there to ask. A live conversation asks the person in it. A scheduled run has nobody to ask, so it refuses the call. Approval is never skipped by leaving it unmentioned.

How Approvals Combine#

Approval rules can be set in two places. Both sets are taken into account for a task run, so a tool can be matched by a rule in each of them.

The project approval policy

The hitl block on the Project resource. You deploy it with the rest of the configuration, it covers every conversation and every task in the project, and it is the only place that can grant approve. For its field shape, see the Project resource on the Resource Reference page.
```
kind: Project
schema: v1
title: Research workspace

hitl:
  rules:
    - pattern: "delete_*"
      disposition: reject
    - pattern: "send_email"
      disposition: approve
```
The rules on a scheduled task

Added with --hitl when you create or update the task. They apply to that one task.
```
genai task update TASK_ID --hitl "send_email=defer"
```
TASK_ID is the identifier the platform gives a task when you create it. It is printed by genai task create and listed in the first column of genai task list. Every command that acts on one task takes it.

Task rules can only tighten the project approval policy, never loosen it. Where both set a disposition for the same tool, the stricter of the two applies. Read from least to most strict, the order is approve, interactive, defer, reject, and hide.

Taken together, the two extracts above mean that the task defers send_email even though the project approves it, because defer is the stricter of the two. A task rule of delete_*=approve would change nothing, because the project rejects those calls and a task cannot soften that.

Because a task runs with no one present, approve and interactive set by the task itself both become defer. The run parks and waits for a person to approve the call later, instead of going ahead on its own or waiting for an answer that never comes. To let a scheduled run call such a tool with no one approving it, grant approve in the project approval policy.

Approval on a Task#

Attach approval rules to a task with the repeatable --hitl PATTERN=DISPOSITION flag:

genai task create \
  --name "Nightly document digest" \
  --instruction "Summarize the documents added today and email the summary to the team." \
  --recurrence daily --time 02:00 --timezone Europe/Zurich \
  --hitl "delete_*=reject" \
  --hitl "send_email=defer"

Any tool whose name begins with delete_ is refused, so the scheduled run can never call one. When the agent wants to call send_email, the run parks and waits for a person to approve it. A tool that needs approval and matches no rule is refused, so the task cannot quietly call something you did not account for.

Next Steps#

For every genai task command and flag, see the CLI Reference page.
For the hitl block and the rest of the Project fields, see the Resource Reference page.
For the capability paths that decide which tools an agent can reach, see the Preference Reference page.
For the endpoints behind the genai task commands, see the API Reference page.