Automation

Schedule a workflow with cron

Create a five-field cron schedule and call it securely from an external scheduler.

Create a stored cron schedule for a skill, then configure an external scheduler to invoke it with bearer authentication. The external scheduler controls when requests occur; Agent Studio stores the cron expression and payload template and executes the schedule when its endpoint is called.

Before you begin

You need a skill ID, an authenticated Clerk session for trigger administration, and an external service or worker that can send an HTTP POST on a five-field cron schedule. Choose a strong CRON_SECRET for the Agent Studio server and store the same value in the scheduler's secret manager.

⚠️CRON_SECRET is optional in the implementation. If it is unset, the invocation route does not require the bearer value. Configure it before exposing a cron endpoint beyond a trusted local environment.

Set local variables for the examples. Do not commit the session token or cron secret:

bash

export AGENT_STUDIO_URL="https://agent-studio.example.com"
export SKILL_ID="<skill-id>"
export CLERK_SESSION_TOKEN="<session-token>"
export CRON_SECRET="<strong-random-secret>"

Scheduling model

The cron expression records the intended timing, while the external scheduler supplies the actual timed request.

Create and invoke the schedule

Choose a five-field expression

Write the schedule as five space-separated fields: minute, hour, day of month, month, and day of week. For example, 15 9 * * 1-5 represents 09:15 on weekdays in the timezone used by your external scheduler.

Agent Studio defaults an omitted expression to 0 * * * *, but specify the expression explicitly so the stored configuration and external scheduler can be compared. Confirm the external scheduler's timezone and daylight-saving behavior before production use; the Agent Studio route does not define those scheduler settings.

Create the cron record

Send POST /api/triggers from an authenticated session. payloadTemplate becomes the execution input whenever this schedule is invoked.

bash

curl --fail-with-body \
  --request POST "$AGENT_STUDIO_URL/api/triggers" \
  --header "Content-Type: application/json" \
  --header "Cookie: __session=$CLERK_SESSION_TOKEN" \
  --data "{
    \"type\": \"cron\",
    \"skillId\": \"$SKILL_ID\",
    \"name\": \"Weekday documentation review\",
    \"cronExpression\": \"15 9 * * 1-5\",
    \"payloadTemplate\": {
      \"repository\": \"example/docs\",
      \"reviewMode\": \"stale-pages\"
    }
  }"

The response contains success: true and the stored schedule under data. Save its id; the external scheduler uses that identifier in the invocation URL.

Test one authenticated invocation

Call the schedule endpoint manually before enabling repeated requests:

bash

curl --fail-with-body \
  --request POST "$AGENT_STUDIO_URL/api/triggers/cron/<schedule-id>" \
  --header "Authorization: Bearer $CRON_SECRET"

When the bearer value matches the server's CRON_SECRET, Agent Studio executes the target skill with the stored payload template and returns success: true with the result under data.

Configure the external scheduler

Create a job in the scheduler with the same 15 9 * * 1-5 expression. Set the method to POST, the URL to $AGENT_STUDIO_URL/api/triggers/cron/<schedule-id>, and the Authorization header to Bearer <cron-secret> using the scheduler's secret store.

Do not place the secret in the URL, job name, or logs. The scheduler should regard only a successful HTTP response as delivery; retain its request and response status as operational evidence without recording the authorization header.

Verify the scheduled run

After the next invocation, find the resulting execution and confirm that its input contains repository: "example/docs" and reviewMode: "stale-pages". Inspect its final status and trace to distinguish a successful schedule delivery from a workflow failure.

For an immediate end-to-end test, temporarily use the scheduler's Run now or equivalent control if the provider offers one, then restore the intended timing without changing the Agent Studio record.

Remove an obsolete schedule

Delete the Agent Studio record after disabling the external scheduler job:

bash

curl --fail-with-body \
  --request DELETE "$AGENT_STUDIO_URL/api/triggers?type=cron&id=<schedule-id>" \
  --header "Cookie: __session=$CLERK_SESSION_TOKEN"

Agent Studio returns success: true with Trigger deleted. Disabling the caller first prevents repeated requests to a schedule that no longer exists.

✅The integration is working when the scheduler receives a successful response and Agent Studio records an execution for the intended skill with the stored payload template.

Troubleshooting

Use Inspect an execution trace to diagnose the scheduled run, or Trigger a workflow with a webhook for event-driven automation.