AgentKit Studio
Guides

Automation and Scheduling

Bind an agent to a one-time, interval, or Cron trigger, run it locally or in the cloud, and deliver results to a channel conversation.

Automation answers one question: run this by itself at the right time. One prompt, one trigger rule, one target agent. It grants no new capability — it only decides when a sentence reaches an agent.

Prerequisites

  • At least one agent. A local automation needs the app running; a cloud automation needs that agent deployed to the cloud.
  • Delivering to a channel conversation additionally needs that cloud agent bound in Channels with at least one completed conversation with the bot.

The two scheduling targets

LocationRuns inAfter you close the appGood for
LocalThe Host process on this deviceDoes not runEditing files and running commands in your workspace
Cloud deploymentA managed cloud instanceKeeps following the scheduleScheduled summaries, checks, and notifications

A status badge sits at the top of the page: Scheduler running means the trigger loop is up; Scheduler not ready means it is not (for example the Host just started, or no executor is available). Local and cloud share the same rule syntax; only the execution location and delivery capability differ.

Steps

Open Automation

Go to Operations → Automation. Choose Local or Cloud deployment at the top first — switching clears the current filters and any open editor.

The two locations are stored separately

Local tasks and cloud tasks are two separate stores and cannot see each other. After switching, the list you see is independent; the tasks did not disappear.

Create an automation

Choose New automation in the top-right, or prefill from Start from a common task:

TemplateTriggerExample prompt
Daily brief · weekdays 10:000 10 * * 1-5Summarize today's changes in the workspace
Periodic check · every 30 minutesInterval 1800 secondsCheck service status and explain any anomaly with a cause and a recommendation
Weekly summary · Friday 17:000 17 * * 5Summarize this week's progress, risks, and todos

A template only prefills the name, prompt, and rule; it does not create the task.

Fill in the three fields

FieldNotes
Bound agentThe target agent. It cannot change while editing an existing task — create a new task to retarget
Task nameThe name shown in the list, for example "Daily work summary"
Prompt sent when dueThe exact sentence handed to the agent when the task fires

Both the name and the prompt are required; leaving either empty reports "Select an agent and fill in the task name and prompt".

Choose the trigger

TriggerParameterConstraint
Fixed intervalInterval in secondsAt least 60; anything below 60 or non-numeric is treated as 3600
CronFive-field expression (time zone Asia/Shanghai)Exactly 5 fields; *, ,, -, and / are supported
Run onceRun time (local time)Must be in the future, otherwise "Choose a future run time"

Cron examples:

0 9 * * 1-5      weekdays at 09:00
*/30 * * * *     every 30 minutes
0 17 * * 5       Friday at 17:00

Choose the result destination (cloud)

A cloud automation can keep its result to the execution record, or send it to a channel conversation:

OptionBehavior
Execution record onlyThe result stays under "Execution records"; nothing is sent to any IM
Send to a channel conversationPick one from the Recipient conversation dropdown

The dropdown lists only WPS Collaboration or Feishu conversations bound to this cloud agent that already completed a conversation, shown as WPS · <channel account> · Group <conversation id>. An empty list usually means no channel is bound, or you have not talked to the bot yet.

A failed delivery never reruns the task

Delivery is a separate step after execution. A delivery failure only marks a delivery state on the execution record; the agent is not run again.

Save

Choose Create (or Save changes while editing). Two success messages are possible:

  • Local: "Local automation created; keep the app running."
  • Cloud: "Cloud automation created; it keeps following the schedule after you close the app."

Manage day to day

Each task row offers:

ActionNotes
DetailsTask id, schedule, session mode, next run time, and the full prompt
Execution recordsExpand the last 8 runs with their states
EditOpens the same form
Run onceRuns immediately without changing the schedule
DeleteIrreversible. For a cloud task only future triggers stop; already-triggered runs and deliveries continue
Enable switchPause or resume. A paused task cannot "Run once"

The board view groups into four columns: Scheduled, Running, Needs attention, and Paused / finished.

Look at native DSH session automations

Under the local tab there is a disclosure, "Native DSH session automations N · Expand". Those tasks are created by schedule_create inside a conversation and stored separately from Host agent automations.

To create one, say this in a new session:

Remind me to organize my work summary every day at 9

DSH calls schedule_create; refresh this page to see it. This surface is read-only — edit and delete in the original conversation.

Scheduling semantics

RuleBehavior
Scan intervalDue tasks are scanned every 30 seconds
Missed firePolicy defaults to skip: the occurrence is skipped, never backfilled
Concurrency per taskNot allowed. A new occurrence is skipped while the previous one is still running
Single-instance ownershipOne scheduler owns the store directory; a second process gets SCHEDULER_OWNED
Crash recoveryOn startup, occurrences left in claimed / running / accepted / admitting are marked failed with AUTOMATION_OUTCOME_UNKNOWN; the original call is never replayed
Session modeA new session per run (default), or continue an existing session

AUTOMATION_OUTCOME_UNKNOWN means "the original host was interrupted and the outcome is unconfirmed; verify in the original conversation". Nothing backfills it; a human must confirm.

What success looks like

  • The task badge reads Enabled and the row meta shows "Next run: <time>".
  • Execution records lists recent occurrences with state succeeded and a completion time.
  • A cloud delivery task shows "Channel delivery: delivered" in the execution record.
  • When the badge turns Needs attention, the latest run or delivery failed; expand the detail and read errorCode and detail.

Common errors

CodeCauseFix
SCHEDULE_KIND_INVALIDkind is not once, interval, or cronUse one of the three triggers in the UI
SCHEDULE_SPEC_INVALIDonce lacks at, or interval lacks everySecondsSupply the missing parameter
SCHEDULE_TIMEZONE_INVALIDInvalid time zoneUse Asia/Shanghai
CRON_INVALIDThe Cron expression is not 5 fieldsRewrite it as five fields per the examples
TASK_ID_INVALIDThe task id does not match ^[a-z][a-z0-9-]{2,62}$Let the system generate it
SCHEDULE_NOT_FOUNDThe task does not existRefresh the list and retry
SCHEDULE_DISABLED"Run once" on a paused taskEnable it first
SCHEDULE_RUNNINGThe previous run of this task has not finishedWait for it
SCHEDULER_CLOSEDThe scheduler is closedRestart the app
SCHEDULER_OWNEDAnother host process owns the schedulerShut that process down
AUTOMATION_OUTCOME_UNKNOWNThe original host was interrupted; outcome unconfirmedVerify in the original conversation; nothing is replayed
AUTOMATION_RUN_FAILEDThe run adapter failedRead detail on the execution record
delivery_target_unavailableThe original channel or conversation is goneCheck bindings under Channels
delivery_target_changedThe bot or recipient conversation changedPick the recipient conversation again
delivery_conversation_missingNo conversation information yetTalk to the bot once
result_text_missing_or_too_largeNo text to send this run, or it exceeds the limitTighten the prompt, or switch to "Execution record only"
delivery_outcome_unknownThe sending process did not confirmVerify in the recipient conversation; nothing resends automatically

On this page