The agent command provides functionality to create, manage, and run agents that analyze incidents and alerts, leveraging the infrastructure knowledge graph and LLM capabilities.
Usage
unpage agent [OPTIONS] COMMAND [ARGS]...
Commands
| Command | Description |
|---|
create | Create a new agent configuration file and open it in your editor |
delete | Delete an agent |
edit | Edit an existing agent configuration file |
list | List the available agents |
quickstart | Get up-and-running with an incident agent in <5min! |
route | Determine which agent will be used to analyze the given payload |
run | Run an agent with the provided payload and print the analysis |
schedule | Start the agent scheduler to run agents on a periodic schedule |
serve | Run the Unpage Agent server to automatically process incoming alerts |
templates | List the available agent templates |
Subcommand: create
Creates a new agent configuration file based on available templates and opens it in your default editor.
Usage
unpage agent create [OPTIONS] AGENT_NAME
Options
| Option | Description |
|---|
--profile TEXT | Use profiles to manage multiple graphs [env var: UNPAGE_PROFILE] [default: default] |
--overwrite | Overwrite the agent file if it already exists |
--template TEXT | The template to use to create the agent file [default: default] |
--editor TEXT | The editor to use to open the agent file [default: from $EDITOR env var] |
--no-edit | Do not open the agent file in your editor |
-h, --help | Show help message and exit |
Subcommand: delete
Deletes an existing agent.
Usage
unpage agent delete [OPTIONS] AGENT_NAME
Subcommand: edit
Opens an existing agent configuration file in your default editor.
Usage
unpage agent edit [OPTIONS] AGENT_NAME
Subcommand: list
Lists all available agents in your Unpage instance.
Usage
unpage agent list [OPTIONS]
Subcommand: quickstart
Launches an interactive wizard to quickly set up an incident response agent.
Usage
unpage agent quickstart [OPTIONS]
Subcommand: route
Tests which agent would be selected to analyze a given payload based on your routing configuration.
Usage
unpage agent route [OPTIONS] [PAYLOAD]
Subcommand: run
Executes an agent with a provided payload and displays the analysis.
Usage
unpage agent run [OPTIONS] AGENT_NAME [PAYLOAD]
Options
| Option | Description |
|---|
--profile TEXT | Use profiles to manage multiple graphs [env var: UNPAGE_PROFILE] [default: default] |
--debug | Enable debug mode to print the history of the agent |
--pagerduty-incident TEXT | PagerDuty incident ID or URL to use instead of payload or stdin |
--rootly-incident TEXT | Rootly incident ID or URL to use instead of payload or stdin |
-h, --help | Show help message and exit |
Examples: Running an Agent with a Test Payload
# Run an agent with a JSON payload from a file
unpage agent run my-agent @path/to/payload.json
# Run an agent with a JSON payload provided directly
unpage agent run my-agent '{"alert": "Disk usage exceeds 80%"}'
Subcommand: schedule
Starts the agent scheduler daemon, which runs agents on a periodic schedule according to their cron expressions. This enables “background chores” like cost optimization reports, security audits, and other maintenance tasks that should run automatically on a schedule.
Usage
unpage agent schedule [OPTIONS]
Options
| Option | Description |
|---|
--profile TEXT | Use profiles to manage multiple configurations [env var: UNPAGE_PROFILE] [default: default] |
-h, --help | Show help message and exit |
Configuring Scheduled Agents
To schedule an agent, add a schedule section to your agent YAML file with a cron expression:
description: Run monthly cost optimization checks
schedule:
cron: "0 10 2 * *" # At 10:00 AM on the 2nd day of every month
prompt: >
Analyze infrastructure costs and identify optimization opportunities.
Use available tools to get cost data and generate recommendations.
tools:
- "aws_*"
- "graph_*"
Scheduled agents run with no input payload, so make sure your agent prompt specifies how to get any required inputs (e.g., via tool calls).
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *
┌───────────── second (0 - 59)
│ ┌───────────── minute (0 - 59)
│ │ ┌───────────── hour (0 - 23)
│ │ │ ┌───────────── day of month (1 - 31)
│ │ │ │ ┌───────────── month (1 - 12)
│ │ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │ │
* * * * * *
Cron Aliases
For convenience, you can use these aliases instead of full cron expressions:
@hourly - Run every hour (equivalent to 0 * * * *)@daily - Run daily at midnight (equivalent to 0 0 * * *)@weekly - Run weekly on Sunday at midnight (equivalent to 0 0 * * 0)@monthly - Run monthly on the 1st at midnight (equivalent to 0 0 1 * *)@yearly or @annually - Run yearly on January 1st at midnight (equivalent to 0 0 1 1 *)
Examples
# Start the scheduler (runs all agents with schedules)
unpage agent schedule
Standard 5-field patterns (minute precision)
schedule:
cron: "0 * * * *" # Every hour at minute 0
cron: "*/15 * * * *" # Every 15 minutes
cron: "0 0 * * *" # Daily at midnight
cron: "0 0 * * 0" # Weekly on Sunday at midnight
cron: "0 0 1 * *" # Monthly on the 1st at midnight
cron: "0 9 * * 1-5" # Weekdays at 9 AM
cron: "*/1 * * * *" # Every minute
Extended 6-field patterns (second precision)
schedule:
cron: "*/2 * * * * *" # Every 2 seconds
cron: "*/10 * * * * *" # Every 10 seconds
cron: "0 */30 * * * *" # Every 30 seconds (at 0, 30 seconds of each minute)
cron: "*/5 */1 * * * *" # Every 5 seconds of every minute
Using aliases
schedule:
cron: "@hourly" # Every hour
cron: "@daily" # Daily at midnight
cron: "@weekly" # Weekly on Sunday at midnight
cron: "@monthly" # Monthly on the 1st at midnight
Scheduler Functionality
When running, the scheduler:
- Loads all agents from your profile that have a
schedule configuration
- Sets up cron jobs for each scheduled agent
- Runs agents automatically according to their schedules
- Logs the output of each agent run
Press Ctrl+C to stop the scheduler.
Subcommand: serve
Starts the Unpage Agent server, which listens for incoming alerts and routes them to appropriate agents. This creates a webhook receiver that can process alerts from various systems (like PagerDuty) and intelligently selects the most appropriate agent to analyze them.
Usage
unpage agent serve [OPTIONS]
Options
| Option | Default | Description |
|---|
--host TEXT | 127.0.0.1 | The host to bind to |
--port INTEGER | 8000 | The port to bind to |
--workers INTEGER | 1 | The number of workers to use |
--profile TEXT | default | The profile to use for configuration |
--reload / --no-reload | False | Reload the server when code changes |
--tunnel / --no-tunnel | False | Tunnel the server through ngrok for external access |
--ngrok-token TEXT | From env var | The ngrok token for tunneling |
--ngrok-domain TEXT | None | The ngrok domain for tunneling |
Server Functionality
When running, the agent server:
- Exposes a
/webhook endpoint that receives alert payloads as JSON via POST requests
- Automatically selects the most appropriate agent based on the incoming payload
- Processes the alert using the agent’s configuration and LLM capabilities
- Returns an analysis of the alert
Examples
# Start the agent server with default settings (localhost:8000)
unpage agent serve
# Start the server on a custom host and port
unpage agent serve --host 0.0.0.0 --port 9000
# Start the server with hot-reloading for development
unpage agent serve --reload
# Start the server and expose it externally using ngrok
unpage agent serve --tunnel --ngrok-token your_ngrok_token
Subcommand: templates
Lists all available agent templates that can be used when creating a new agent.
Usage
unpage agent templates [OPTIONS]
Production Deployment
For production deployments of your agents, see our comprehensive Deployment Guide. 
