Scheduling

A template can ship the recurring work its agent is designed to do in a schedules: block, and Trinity creates those schedules when the agent is created — through the UI, the API, and MCP alike. They appear here like any other schedule and are yours to edit, disable, or delete. See Creating Agents.

Keep the message to a bare playbook call. The recommended shape for any schedule message — declared or hand-created — is a single line that invokes one of the agent's skills by name, e.g. /daily-briefing, with no inline instructions. The logic then lives in the versioned playbook, so changing what a scheduled run does is an edit to the skill, never to the schedule. A skill that normally asks questions at its decision points needs a headless mode (the abilities convention is a --autonomous argument) before it goes on a cron; otherwise every run blocks on a prompt nobody sees and burns its whole timeout. See Abilities Marketplace.

By default a scheduled run ends in the executions list — an operator's view. If the run exists for one particular person (a morning brief, a weekly summary), you can name them and have the output arrive as a message in their Workspace conversation with that agent instead of only in the log.

Set deliver_to_workspace_email on the schedule:

curl -X POST http://localhost:8000/api/agents/my-agent/schedules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "name": "morning-brief",
        "cron_expression": "0 7 * * 1-5",
        "message": "Write my morning brief.",
        "timezone": "Europe/Kyiv",
        "deliver_to_workspace_email": "person@example.com"
      }'

The same field is available on create_agent_schedule and update_agent_schedule; passing null on an update stops delivering. Leave it unset and nothing changes. The schedule form in the UI has no field for it.

Where it lands. In that person's Mainchat with the agent — the one constant conversation per person per agent, which is where the agent reaches you when no particular chat is the right home for a message. It reads like any other message from the agent, and it can be rated like one.

Who you can name. Someone the agent is already shared with, or its owner. If the address cannot reach the agent — never shared, share revoked, blocked, or simply unknown — the run fails and says so on the execution row rather than running and quietly delivering nowhere. A malformed address is rejected when you save the schedule, not hours later on the first fire.

Who can set it.You can always name yourself. Naming anyone else takes the agent's owner or an admin — on create and on update alike — so that someone the agent is merely shared with cannot put a recurring message of their choosing into a colleague's chat. Clearing the address is never restricted.

When it shows up.The message is saved as soon as the run finishes, but the Workspace does not poll a conversation you already have open. So it appears the next time that person loads the Workspace or switches to the chat — fine at daily cadence, and worth knowing if you were expecting it to pop up mid-conversation. It also avoids cutting into a turn already in progress in that chat: it waits up to two minutes for that reply to finish, then writes regardless.

Delivered once. Each fire delivers at most one message, even if the platform has to retry internally.

Rateable. The delivered message is an ordinary reply from the agent, so the person can rate it like any other — see Workspace.

Each schedule has an analytics view summarizing how it has been performing over a selectable time window.

At-a-Glance Scorecards

Performance shows up in two places without opening any analytics card:

Both are fed by one endpoint: GET /api/agents/{name}/schedules/analytics-summary?window=7d|14d|30d— one row per schedule, including zero-run schedules.

Detailed Analytics Card

The card shows run counts, success rate, duration percentiles (p50 / p95 / p99), total cost, the top tools the schedule called, and a daily timeline of successes, failures, and cost.

Via the API

GET /api/agents/{name}/schedules/{id}/analytics?window_hours=168

On high-traffic schedules the duration percentiles are computed over the newest 5,000 successful runs; the response reports sampled: true when this cap applies. Counts and the timeline always cover the full window.

Failed executions can automatically retry with configurable delay and attempt limits.

Configuration

Retries are off by default: a schedule created in the UI (Max Retries → Disabled (default)) or over the REST API has max_retries: 0. The create_agent_schedule MCP tool is the exception and defaults to 1 retry; pass max_retries: 0 there to turn it off.

Retry Behavior

Execution Grouping

Retries are linked to their original execution:

The execution list groups retries under their parent execution for clarity.

Execution Statuses

An optional executable shipped by an agent template that gates each cron tick before Claude is invoked. When present, it lets the agent decide at runtime whether the scheduled work is actually needed — so empty polls (no new PRs, no new emails, no alerts) consume zero tokens.

How It Works

Key Behaviors

For Template Authors

Place the hook at ~/.trinity/pre-check (no extension), make it executable (chmod +x), and include a shebang. The hook receives no arguments. Print a work description to stdout if there is work, or print nothing if there is nothing to do.

#!/usr/bin/env python3
import sys
# ... check for new items ...
if new_items:
    print(f"Review {len(new_items)} new PRs: {', '.join(new_items)}")
# else: exit 0 with empty stdout → Trinity records a skip