Agents

An agent is a named, deployable unit: a system prompt (its instructions) plus the set of tools it is allowed to use. Agents are how you package a specific job so it can be run consistently from several places.

What an agent is made of

An agents row holds:

• a name,
• instructions (its system prompt),
• tool_ids - the tools it may call, and
• collection_ids - the collections it has access to.

The Agents page is the dashboard for creating and editing them. When selecting tools in the agent editor, you can use "Select all" or "Clear all" buttons to quickly manage the full toolset. Agents are visible across the workspace.

Agents can be created and updated programmatically by the internal assistant (in chat, on a schedule, or in a webhook) using the create_agent and update_agent built-in tools. This lets you ask the assistant to "create an agent that..." or "update the agent to..." and have the changes appear in the dashboard ready to use.

On the Agents page, you can search and filter the list:

• Search — find agents by name, description, or instructions. The search updates as you type with a brief debounce.
• Status — show all agents, only active ones, or only inactive ones.
• Schedules — show all agents, only those with active schedules, or only those without schedules.
• Collections — show agents filed into a specific collection.

Each agent card shows:

• Name and description — the agent's purpose.
• Schedule times (if scheduled) — when the agent runs. If multiple schedules exist, each is listed on its own line. The timezone (e.g., (America/New_York)) is shown only for non-UTC cron schedules, so you can see at a glance when and where the agent runs.
• Last updated (if not scheduled) — when the agent was last modified.

Agents with active schedules have a small green dot indicator next to their name so you can spot scheduled work at a glance.

Running an agent

The same agent can run in three contexts:

• From chat. Opening /chat?agent=:id layers the agent's prompt onto the conversation and scopes the available tools to just the agent's tools.
• From a webhook. A webhook can target an agent, so an incoming payload is run through the agent's prompt and tools instead of a bare prompt. See Webhooks.
• On a schedule. A schedules row pairs an agent with a cadence and an optional input. A scheduler edge function, ticked once a minute by pg_cron, runs due schedules. Cadence can be a preset interval (every N minutes/hours/days) or a standard 5-field cron expression for exact times the presets can't express (e.g., the 15th of every month, the last day of the month, weekdays at 9am, evaluated in a timezone of your choice). Each run uses the agent's own instructions; the optional input can add extra direction for that specific run. You manage schedules inside the agent editor.

Scheduling with cron expressions

When the preset intervals (every 5 minutes, hourly, daily, etc.) don't match your needs, you can use a standard 5-field cron expression to schedule an agent at exact times.

AI-assisted cron generation

Instead of writing cron expressions by hand, describe your schedule in plain English and let the AI generate it for you. In the agent editor's schedule section, type something like:

• "Friday 7am"
• "Every weekday at 9am"
• "15th of every month at 2pm"
• "Last day of the month at 5pm"

Then click Generate cron and the expression will be filled in automatically. This is a quick way to express schedules the presets don't cover without memorizing cron syntax.

Cron expression syntax

A cron expression has five space-separated fields:

┌───────── minute (0–59)
│ ┌─────── hour (0–23)
│ │ ┌───── day of month (1–31, or L for last day)
│ │ │ ┌─── month (1–12)
│ │ │ │ ┌─ day of week (0–6, Sun=0)
│ │ │ │ │
* * * * *

Some common examples:

• 0 9 * * * — Every day at 9:00am
• 0 9 * * 1-5 — Weekdays (Mon–Fri) at 9:00am
• 0 9 15 * * — The 15th of every month at 9:00am
• 0 17 L * * — The last day of every month at 5:00pm
• */30 * * * * — Every 30 minutes
• 0 */6 * * * — Every 6 hours

Features:

• * means "every" in that field.
• Ranges work: 1-5 for days 1 through 5.
• Lists work: 1,15,L for the 1st, 15th, and last day.
• Steps work: */15 for every 15 units, 0 */2 for every 2 hours.
• L in the day field means the last day of the month (works even in February).

When you specify a cron expression, you must also choose a timezone (IANA format, e.g., America/New_York or Europe/London). The schedule evaluates the expression in that timezone, so 0 9 15 * * in America/New_York fires at 9am Eastern time, not UTC.

New schedules default to the workspace timezone (set in Settings → Timezone); existing schedules keep theirs. The agent also learns the current date and time in whatever timezone the schedule uses, so when it reasons about "today" or "now" during the run, it uses the correct local time.

The editor previews the next few fire times as you type, so you can verify the expression does what you expect.

Collections bound to an agent

When you bind collections to an agent, their contents — artifacts, files, to-dos, links, tables, and even other agents — are injected as primary context whenever the agent runs. This happens in all three contexts: chat, webhooks, and schedules. The user's manually picked collections (if any) are merged with the agent's bound collections.

This is how you give an agent a persistent knowledge set. For example, an agent that processes incoming tickets can be bound to a collection of templates and guidelines it should follow every time it runs.

Filing agents into collections

Agents can themselves be filed into collections just like artifacts, files, to-dos, links, and tables. You can organize related agents on the Agents page by multi-selecting them and clicking Add to collection, or add them one at a time from a collection's dashboard. This lets you keep specialized agents grouped by project, workflow, or purpose, making it easy to discover which agents are available and give the assistant a directory of capabilities.

Agent run observability

Every time an agent runs — whether from chat, a webhook, a schedule, or Slack — the system records a detailed trace of what happened:

• Run header: when it started/ended, the surface it came from (chat, schedule, webhook, or Slack), the model used, token usage, and cost.
• Step timeline: each model turn and each tool call, with the tool's raw input/output, duration, error status, and whether it was sandboxed.

This trace lives in the agent_runs and agent_run_steps tables. On the Agents page, each agent card has a Runs button that opens /agents/:id — a dedicated observability page showing the agent's recent runs and their step-by-step timelines.

On the detail page:

• Run cards list recent invocations newest first, with status, trigger surface, final output, tool count, and duration.
• Click a run to expand it and see the step timeline — each model turn and tool call in order.
• "Technical detail" toggle reveals per-step tokens/cost and tool input/output for debugging.
• Runs tick live when expanded if the agent is still running, so you can watch progress in real time.

This is how you troubleshoot an agent that went sideways or verify one that's working well — you can see exactly which tools it called, what it passed them, and what came back.

Why scope tools per agent

Restricting an agent to specific tools is both a safety and a quality measure. A focused agent with three relevant tools behaves more predictably than one with access to everything. And when an agent runs from an untrusted trigger like a webhook, a tight toolset limits what a bad input could cause it to do.

The shared execution path

All three loops (chat, webhook, scheduler) execute built-in tools through one shared module, so a capability like "search the knowledge base" or "send email" behaves identically whether you are chatting live or an agent is running at 6am. That is what makes "the morning agent emails me a summary" reliable - it is the same machinery as chat, just triggered differently.

This also means agents can author content: create artifacts, organize them into collections, and add notes to your workspace knowledge base. A scheduled agent can, for example, fetch articles every morning and file them into a collection your team can chat with.