unpage agent - Unpage

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).

Cron Expression Format

Unpage supports multiple cron formats for maximum flexibility:

Standard 5-field format (minute precision)

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

Extended 6-field format (second precision)

┌───────────── 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.

​Usage

​Commands

​Subcommand: create

​Usage

​Options

​Subcommand: delete

​Usage

​Subcommand: edit

​Usage

​Subcommand: list

​Usage

​Subcommand: quickstart

​Usage

​Subcommand: route

​Usage

​Subcommand: run

​Usage

​Options

​Examples: Running an Agent with a Test Payload

​Subcommand: schedule

​Usage

​Options

​Configuring Scheduled Agents

​Cron Expression Format

​Standard 5-field format (minute precision)

​Extended 6-field format (second precision)

​Cron Aliases

​Examples

​Standard 5-field patterns (minute precision)

​Extended 6-field patterns (second precision)

​Using aliases

​Scheduler Functionality

​Subcommand: serve

​Usage

​Options

​Server Functionality

​Examples

​Subcommand: templates

​Usage

​Production Deployment

Usage

Commands

Subcommand: create

Usage

Options

Subcommand: delete

Usage

Subcommand: edit

Usage

Subcommand: list

Usage

Subcommand: quickstart

Usage

Subcommand: route

Usage

Subcommand: run

Usage

Options

Examples: Running an Agent with a Test Payload

Subcommand: schedule

Usage

Options

Configuring Scheduled Agents

Cron Expression Format

Standard 5-field format (minute precision)

Extended 6-field format (second precision)

Cron Aliases

Examples

Standard 5-field patterns (minute precision)

Extended 6-field patterns (second precision)

Using aliases

Scheduler Functionality

Subcommand: serve

Usage

Options

Server Functionality

Examples

Subcommand: templates

Usage

Production Deployment