> ## 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 Performance Agent

> Automatically find performance bottlenecks in your Upsun application. The performance agent analyzes up to 7 days of profiling and traffic data and generates an AI-powered report with actionable recommendations.

# Upsun performance agent

The `performance-agent` correlates a range of observability signals from an app deployed on Upsun, including Blackfire profiles, continuous profiling data, traffic, and your application source code, then generates a performance analysis report. It analyzes a configurable window of up to 7 days (24 hours by default).

## Run as an Upsun task

The agent runs as an Upsun [`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`).

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 <project-id> --level project --name env:ANTHROPIC_API_KEY \
    --value "<key>" --sensitive true --visible-runtime true
```

### 1. Add the task to your Upsun 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

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

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

`AGENT_APPLICATION` is the only required variable. The report is written to the task activity log.

### Task environment variables

Pass additional variables under `variables.env` in the run command.

| Env var                                | Default                        | Description                                                                                                                                                                                                  |
| -------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AGENT_APPLICATION`                    | (required)                     | Name of the Upsun application 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.                                                                                                                                                       |
| `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`    |

### Cost

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.

<Note>
  The figures below come from internal tests and are only a rough sense of scale, not a guarantee. Your actual cost will vary.
</Note>

| 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       |