> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsun Cloud performance agent > Automatically find performance bottlenecks in your Upsun Cloud application. The performance agent analyzes up to 7 days of profiling and traffic data and generates an AI-powered report with actionable recommendations. # Upsun Cloud performance agent The `performance-agent` correlates a range of observability signals from an application or worker deployed on Upsun Cloud, including Upsun Blackfire profiles, continuous profiling data, traffic, and your source code, then generates a performance analysis report. It analyzes a configurable window of up to 7 days (24 hours by default), subject to your [profiling retention](#analysis-window). ## Run as an Upsun Cloud task The agent runs as an Upsun Cloud [`task`](/docs/configure-apps/tasks), so it requires no local installation. The only credential you supply is an LLM provider API key: `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. The provider is deduced from the `MODEL` you set (`claude*` uses `ANTHROPIC_API_KEY`, `gpt*` uses `OPENAI_API_KEY`). You bring your own key, and your provider bills the tokens the agent consumes directly to you. See [What a run costs](#what-a-run-costs). Store the API key as a sensitive variable rather than passing it inline. Passing it inline exposes the secret in shell history. ```bash theme={null} upsun variable:create -p --level project --name env:ANTHROPIC_API_KEY \ --value "" --sensitive true --visible-runtime true ``` ### 1. Add the task to your Upsun Cloud configuration Add the following to `.upsun/config.yaml`: ```yaml theme={null} tasks: performance-agent: base: "performance-agent" ``` Commit the change and deploy it so the task is available on your environment: ```bash theme={null} git add .upsun/config.yaml git commit -m "Add performance agent task" upsun push ``` ### 2. Run the agent You can run the agent from the Console, or through the CLI and API. #### From the Console 1. Open your environment overview page. 2. Either find the **Tasks** card in the left-hand column, or open the **Containers** tab and select **performance-agent** under **Tasks**. 3. In the **Run performance-agent task on ``** dialog, set the following: * **Analysis scope**: use the **Select the application or worker** dropdown to choose the container to analyze. * **Analysis period**: choose 15 minutes, 1 hour, 24 hours, or 7 days. The dialog shows the profiling coverage included with your plan inline, for example *Your plan covers 15 minutes. For more, upgrade continuous profiling.* See [Analysis window](#analysis-window). * **AI engine and guard rails**: the model, thinking level, maximum number of findings, and budget cap. These map to the [`MODEL`, `THINKING`, `MAX_FINDINGS`, and `MAX_BUDGET_USD`](#task-environment-variables) variables. 4. Click **Run**. When the analysis completes, the results appear in the **Report** tab, marked with a sparkle icon. The report lists each finding and the suggested diff that addresses it. #### From the CLI or API Replace the project ID, environment, and application name with yours: ```bash theme={null} upsun e:curl -p -e -X POST /tasks/performance-agent/run \ --json '{"variables":{"env":{"AGENT_APPLICATION":""}}}' ``` To analyze a worker instead, pass the worker name in `AGENT_APPLICATION`. There is no qualifier or special syntax: ```bash theme={null} upsun e:curl -p -e -X POST /tasks/performance-agent/run \ --json '{"variables":{"env":{"AGENT_APPLICATION":""}}}' ``` `AGENT_APPLICATION` is the only required variable. The report is written to the task activity log. ### Analysis window The agent analyzes a window of up to 7 days. Set it with `FROM_TIMESTAMP` and `TO_TIMESTAMP` from the CLI and API, or with the **Analysis period** presets in the Console. How much of that window the agent can draw on depends on your continuous profiling retention. Every project includes 15 minutes of continuous profiling. Longer history comes from the [continuous profiling add-on](/docs/administration/billing/add-on-subscription#continuous-profiling-add-on), which retains 30 days per project. The default 15 minutes is enough for the agent to run without failing, but it only covers the last few minutes of activity. Feeding the agent more profiling data surfaces bottlenecks that build up over time, like a slow path under peak traffic or a weekly batch job. ### Task environment variables Pass additional variables under `variables.env` in the run command. | Env var | Default | Description | | - | - | - | | `AGENT_APPLICATION` | (required) | Name of the Upsun Cloud application or worker to analyze. | | `CLONE_TIMEOUT` | `900` | Timeout in seconds for cloning the environment's source; also the requested proxy token TTL. Raise for very large repos. | | `FROM_TIMESTAMP` | (binary default: `to - 86400`) | Window start in Unix seconds. Window capped at 7 days. See [Analysis window](#analysis-window). | | `TO_TIMESTAMP` | (binary default: now) | Window end in Unix seconds. | | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | (required) | Provider API key, read by the binary directly from env. The provider is deduced from `MODEL` (`claude*` uses `ANTHROPIC_API_KEY`, `gpt*` uses `OPENAI_API_KEY`). Set it as a sensitive variable, not inline. | | `MODEL` | `claude-opus-4-8` | Model ID. See [Available models](#available-models). | | `LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or `silent`. | | `THINKING` | `xhigh` | `minimal`, `low`, `medium`, `high`, or `xhigh`. | | `MAX_FINDINGS` | `5` | Integer 1–15. | | `MAX_BUDGET_USD` | `5` | Cost ceiling in USD. | | `QUIET` | `false` | Read by the binary directly from env; `0`/`false`/`no`/`off` to disable. | | `VERBOSE` | `false` | Read by the binary directly from env; `0`/`false`/`no`/`off` to disable. | Variables with a binary default are the agent's own defaults. The task only passes a flag when the variable is set. `--project` and `--environment` are locked to the runtime's `PLATFORM_PROJECT` and `PLATFORM_BRANCH` and cannot be overridden through environment variables. ### Available models Set `MODEL` to any of the following IDs. Aliases resolve to the latest matching model. The provider is deduced from the model ID. | Model | Alias | Provider | | - | - | - | | `claude-opus-4-8` | `claude-opus` | `anthropic` | | `claude-opus-4-7` | | `anthropic` | | `claude-sonnet-5` | `claude-sonnet` | `anthropic` | | `claude-sonnet-4-6` | | `anthropic` | | `gpt-5.5` | | `openai` | | `gpt-5.6-sol` | | `openai` | | `gpt-5.6-luna` | | `openai` | | `gpt-5.6-terra` | `gpt` | `openai` | ## What a run costs Upsun Cloud doesn't charge for the performance agent itself. There is no license, subscription, or per-run fee. Each run costs you the compute of the [task container](/docs/configure-apps/tasks#resources-variables-and-access) it runs in, billed per second at the resources you allocate to the task. Task compute cost is the same regardless of which model you use. Your LLM provider then bills the tokens the agent consumes to your own API key, and this billing varies by task model (see the table below). Upsun doesn't resell those tokens, and task compute doesn't cover them. The [continuous profiling add-on](/docs/administration/billing/add-on-subscription#continuous-profiling-add-on) is optional and billed separately, as a per-project fee. See the [pricing page](https://upsun.com/pricing/). ### Cost by model Cost per run depends on the model, the length of the analysis window, and how much observability data your app produces. The `MAX_BUDGET_USD` variable (default `5`) caps spend per run. The figures below come from internal tests and are only a rough sense of scale, not a guarantee. Your actual cost will vary. | Model | Approximate cost per run | | - | - | | `gpt-5.6-terra` | \~\$0.25 to \$0.85 | | `claude-sonnet-5` | \~\$0.65 to \$2.20 | | `claude-opus-4-8` | \~\$1.00 to \$2.90 |