> ## Documentation Index > Fetch the complete documentation index at: https://docs.unpage.ai/llms.txt > Use this file to discover all available pages before exploring further. # unpage agent > Create, manage, and run Unpage agents 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 ```shell theme={null} 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 ```shell theme={null} 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 ```shell theme={null} unpage agent delete [OPTIONS] AGENT_NAME ``` ## Subcommand: edit Opens an existing agent configuration file in your default editor. ### Usage ```shell theme={null} unpage agent edit [OPTIONS] AGENT_NAME ``` ## Subcommand: list Lists all available agents in your Unpage instance. ### Usage ```shell theme={null} unpage agent list [OPTIONS] ``` ## Subcommand: quickstart Launches an interactive wizard to quickly set up an incident response agent. ### Usage ```shell theme={null} unpage agent quickstart [OPTIONS] ``` ## Subcommand: route Tests which agent would be selected to analyze a given payload based on your routing configuration. ### Usage ```shell theme={null} unpage agent route [OPTIONS] [PAYLOAD] ``` ## Subcommand: run Executes an agent with a provided payload and displays the analysis. ### Usage ```shell theme={null} 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 ```shell theme={null} # 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 ```shell theme={null} 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: ```yaml theme={null} 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 ```shell theme={null} # Start the scheduler (runs all agents with schedules) unpage agent schedule ``` #### Standard 5-field patterns (minute precision) ```yaml theme={null} 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) ```yaml theme={null} 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 ```yaml theme={null} 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: 1. Loads all agents from your profile that have a `schedule` configuration 2. Sets up cron jobs for each scheduled agent 3. Runs agents automatically according to their schedules 4. 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 ```shell theme={null} 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: 1. Exposes a `/webhook` endpoint that receives alert payloads as JSON via POST requests 2. Automatically selects the most appropriate agent based on the incoming payload 3. Processes the alert using the agent's configuration and LLM capabilities 4. Returns an analysis of the alert ### Examples ```shell theme={null} # 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 ```shell theme={null} unpage agent templates [OPTIONS] ``` ## Production Deployment For production deployments of your agents, see our comprehensive [Deployment Guide](/howto/deployment-guide).