Agents
Agents
Agents are scheduled Claude sessions that run automatically on a cron schedule. Think of them as recurring automations -- you define a prompt, set a schedule, and Cognova handles the rest.
Agent List
When you open the Agents page, you will see:
- Global stats cards at the top showing aggregate metrics for the selected time period.
- A run activity chart showing daily success/failure counts.
- A list of agent cards, each displaying the agent's name, description, schedule, last run time, budget limit, and current status.
Time Period
Use the 24h, 7d, or 30d buttons in the navbar to change the time window for stats and charts. Your preference is remembered between sessions.
Agent Status
Each agent card shows a status badge:
| Status | Meaning |
|---|---|
| Running | The agent is currently executing (with a spinning indicator). |
| success | The last run completed successfully. |
| error | The last run encountered an error. |
| budget_exceeded | The last run was stopped because it hit its cost limit. |
| cancelled | The last run was manually cancelled. |
Quick Actions
Each agent card provides controls on the right side:
- Enable/Disable toggle -- Turn the agent's schedule on or off without deleting it.
- Play button -- Trigger an immediate manual run (only available when the agent is enabled and not already running).
- Stop button -- Cancel a running execution.
- Edit button -- Open the edit form.
Click anywhere on an agent card to navigate to its detail page.
Creating an Agent
Click New Agent to open a slide-over form with the following fields:
- Name (required) -- A descriptive name, e.g., "Email Digest Agent."
- Description -- An optional summary of what the agent does.
- Schedule (required) -- Pick from common presets or enter a custom cron expression.
- Prompt (required) -- The instructions Claude will follow when the agent runs. This uses a rich-text editor with formatting support.
- Max Turns -- Limit how many conversational turns Claude can take per run (default: 50).
- Max Budget (USD) -- Set a per-run cost cap. The run will stop if the budget is exceeded.
- Enabled -- Whether the agent should start running on its schedule immediately.
Schedule Presets
| Preset | Cron Expression |
|---|---|
| Every 5 minutes | */5 * * * * |
| Every hour | 0 * * * * |
| Every 6 hours | 0 */6 * * * |
| Daily at 8am | 0 8 * * * |
| Daily at midnight | 0 0 * * * |
| Weekly (Sunday midnight) | 0 0 * * 0 |
| Custom | You provide the expression |
Agent Detail Page
Clicking an agent card takes you to a dedicated detail page with:
Agent Info Card
Shows the agent's description, human-readable schedule (with the raw cron expression), budget limit, and last run time.
Stats Cards
Metrics specific to this agent for the selected time period -- total runs, success rate, total cost, and average duration.
Activity Chart
A bar chart of daily runs, broken down by outcome (success, error, cancelled, budget exceeded).
Run History
A chronological list of all runs within the selected period. Each run entry shows:
- Status badge and timestamp.
- A truncated output or error message.
- Duration and cost on the right.
Click any run to open a modal with the full output details.
Detail Page Actions
The navbar on the detail page provides:
- Enable/Disable toggle
- Play or Stop button
- Edit button (opens the slide-over form)
- Delete button (with confirmation)
- Period selector (24h / 7d / 30d)
Deleting an agent is permanent and also removes all of its run history. Consider disabling an agent instead if you might want to re-enable it later.
For details on how agents integrate with hooks, see Claude Hooks. For API endpoint details, see API Reference.