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.

Run as an Upsun Cloud task

The agent runs as an Upsun Cloud task, 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.

Store the API key as a sensitive variable rather than passing it inline. Passing it inline exposes the secret in shell history.

upsun variable:create -p <project-id> --level project --name env:ANTHROPIC_API_KEY \
    --value "<key>" --sensitive true --visible-runtime true

To use OpenAI, store env:OPENAI_API_KEY the same way.

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:

tasks:
  performance-agent:
    base: "performance-agent"

Commit the change and deploy it so the task is available on your environment:

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 <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: the Model provider, Anthropic or OpenAI. This maps to the MODEL 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.
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.

From the CLI or API

Replace the project ID, environment, and application name with yours:

upsun e:curl -p <project-id> -e <env> -X POST /tasks/performance-agent/run \
  --json '{"variables":{"env":{"AGENT_APPLICATION":"<app-name>"}}}'

To analyze a worker instead, pass the worker name in AGENT_APPLICATION. There is no qualifier or special syntax:

upsun e:curl -p <project-id> -e <env> -X POST /tasks/performance-agent/run \
  --json '{"variables":{"env":{"AGENT_APPLICATION":"<worker-name>"}}}'

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 under variables.env. For example, to use OpenAI and lower the cost ceiling:

upsun e:curl -p <project-id> -e <env> -X POST /tasks/performance-agent/run \
  --json '{"variables":{"env":{"AGENT_APPLICATION":"<app-name>","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, 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.
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 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 is optional and billed separately, as a per-project fee. See the pricing page.

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.

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.