> ## 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`](https://developer.upsun.com/docs/configure-apps/tasks), so it requires no local installation. The only credential you supply is an LLM provider API key. Set `MODEL` to `anthropic` (the default) to use `ANTHROPIC_API_KEY`, or to `openai` to use `OPENAI_API_KEY`. The agent picks its model for that provider. 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](https://developer.upsun.com/docs/development/variables/set-variables.md#variable-options) 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 ``` To use OpenAI, store `env:OPENAI_API_KEY` the same way. > [!WARNING] > > An Anthropic key must be scoped to a single workspace. A multi-workspace (identity-linked) key > needs a workspace ID on every request, which the agent can't supply, and the run stops in > preflight. ### 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**: the **Model provider**, Anthropic or OpenAI. This maps to the [`MODEL`](#task-environment-variables) variable. The agent picks the model for that provider. Console runs use the default maximum findings (`5`) and budget cap (\$5). To change them, use the [CLI or API](#from-the-cli-or-api). 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 its proposed fix. See [What you get back](#what-you-get-back). #### 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. To change the provider, maximum findings, or budget cap, pass any of the [task environment variables](#task-environment-variables) under `variables.env`. For example, to use OpenAI and lower the cost ceiling: ```bash theme={null} upsun e:curl -p -e -X POST /tasks/performance-agent/run \ --json '{"variables":{"env":{"AGENT_APPLICATION":"","MODEL":"openai","MAX_BUDGET_USD":"2"}}}' ``` ### 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](https://developer.upsun.com/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. ### What you get back Each run produces a single report: * **Summary**: a one-sentence assessment of the application's performance. * **Recommendation**: what to address first. `No action needed.` when there's nothing to report. * **Findings**: up to 15 entries (5 by default), ordered by impact, highest first. Each finding includes: * **Title** and **description** of what's happening. * **Impact**: how much it costs, for example *23% of request wall time*. * **Priority**: `low`, `medium`, `high`, or `critical`. * **Why it matters**: the effect on your users or your application. * **Proposed fix**: a patch to your source or configuration, or written guidance when no file change applies, such as a sizing decision. If your app receives traffic but Upsun Blackfire monitoring or continuous profiling returns no data, the agent reports the missing data as a finding, with the steps to fix it. ### 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. 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. `MODEL=anthropic` uses `ANTHROPIC_API_KEY`; `MODEL=openai` uses `OPENAI_API_KEY`. Set it as a sensitive variable, not inline. | | `MODEL` | `anthropic` | LLM provider: `anthropic` or `openai`. The agent picks its model for that provider. | | `LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or `silent`. | | `MAX_FINDINGS` | `5` | Integer 1–15. | | `MAX_BUDGET_USD` | `5` | Cost ceiling in USD. The agent aborts at the next turn boundary when exceeded. | | `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. ## Data access and handling ### What the agent can access The agent can access the following data, and reads only what it needs for the analysis: * **Observability data** through the Upsun Cloud API: deployments, activities and activity logs, application and platform logs, HTTP traffic, server metrics, Upsun Blackfire recommendations and profiles, and continuous profiling data. * **Source code**: a shallow clone of the environment's branch tip. To profile an endpoint, the agent can send HTTP requests to your environment's public routes. ### Data handling and storage The agent sends the data it reads to the LLM provider that you set in `MODEL`, using your own API key. That provider processes the request under your own account with them, subject to your agreement with that provider. If your data includes content that your organization restricts from leaving your infrastructure, confirm that sending it to your chosen provider is acceptable before running the agent. The run's activity log holds the report and the agent's live progress: the commands it runs and its notes, which can quote your logs, profiles, or source. Run variables are also visible there, so store your provider API key as a project variable and never pass it as a run variable. ## 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](https://developer.upsun.com/docs/configure-apps/tasks.md#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 the provider you use. Your LLM provider then bills the tokens the agent consumes to your own API key, and this billing varies by provider (see the table below). Upsun doesn't resell those tokens, and task compute doesn't cover them. The [continuous profiling add-on](https://developer.upsun.com/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 provider Cost per run depends on the provider, 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 agent checks it between turns, so a run can go over it by the cost of one turn. > [!NOTE] > > The figures below come from internal tests and are only a rough sense of scale, not a guarantee. Your actual cost will vary. | Provider | Approximate cost per run | | - | - | | `anthropic` | Under \$1.50 | | `openai` | Under \$0.50 | These figures apply to the current agent release. A later release can change them. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.