Skip to main content

​
Upsun performance agent

The performance-agent correlates a range of observability signals from an application or worker deployed on Upsun, including 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.

​
Run as an Upsun task

The agent runs as an Upsun task, 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. Store the API key as a sensitive variable rather than passing it inline. Passing it inline exposes the secret in shell history.

​
1. Add the task to your Upsun configuration

Add the following to .upsun/config.yaml:
Commit the change and deploy it so the task is available on your environment:

​
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 <environment> 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.
    • 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 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:
To analyze a worker instead, pass the worker name in AGENT_APPLICATION. There is no qualifier or special syntax:
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, 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. 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.

​
What a run costs

Upsun 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 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 is optional and billed separately, as a per-project fee. See the pricing page.

​
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.
Last modified on August 24, 2026