Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions docs/configuration/agent-tasks/build-deployment-optimizer.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,31 +9,33 @@ import AgentTasksEarlyPreviewWarning from '/snippets/agent-tasks-early-preview-w

## Overview

Identifies build and deployment optimization levers and their expected gain, then opens a PR with the proposed change and/or updates the build configuration in Qovery directly. It never merges a fix on its own.
Analyzes build and deployment speed for a service or environment with the [`qovery-speedup`](https://github.com/Qovery/qovery-skills/tree/main/qovery-speedup) skill, then opens a PR for each proposed change. The template's instructions tell the agent not to apply any change directly, and never to merge a PR on its own.

## How It Works

To find concrete ways to make builds and deployments faster and cheaper, the agent:

1. Inspects the service's build setup: Dockerfile, dependency installation, layer caching, image size, and the build/deploy configuration in Qovery.
2. Identifies optimization levers, for example better layer ordering and caching, multi-stage builds, smaller base images, pruning unused dependencies, or parallelisable steps.
3. For each lever, estimates the expected gain (build time, image size, or cost) and the risk.
4. Opens a PR with the proposed changes to the build configuration, and/or updates the build configuration in Qovery directly.
5. Summarises what it changed, the expected gain, and anything that needs a human decision. It never merges, the human always stays the gate.
1. Loads the `qovery-speedup` skill and follows it to analyze build and deployment speed for the current service or environment.
2. Inspects the setup, identifies the bottlenecks, and diagnoses their root causes, including whether a slow build is an avoidable image-mirroring miss.
3. For every proposed change to a file in a repository (Dockerfile, build configuration, Infrastructure as Code such as Terraform), opens a PR on the relevant repository with a before/after and the expected gain. It never merges it.
4. For a change that can only be made from the Qovery Console or API, it does not call the mutating endpoint. It lists the change as a recommendation in its summary, with the exact change needed and the expected gain.
5. Finishes with a summary of what it found, what is proposed in which PR, and what needs a human decision. The human always stays the gate.

The template's domain allowlist is pre-filled with `github.com`, `api.github.com`, `raw.githubusercontent.com`, `gitlab.com`, `bitbucket.org`, and `api.bitbucket.org`.

## Setting It Up

<Steps>
<Step title="Create the agent task">
From the **Agent use cases** section when creating a new service, pick **Build & deployment optimizer** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)), or start from scratch and paste in the instructions above.
From your environment's **Automations** tab, click **Create agent task > Create from template** and pick **Build & deployment optimizer** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)), or choose **Create from scratch** and paste in the instructions above.
</Step>
<Step title="Connect the repository">
Add the Qovery service to optimize as its Context, its linked Git repository is included automatically so the agent can inspect the Dockerfile and build setup. Add a repository on its own only if it isn't tied to a Qovery service.
</Step>
<Step title="Add the Qovery MCP server">
Since you added the service as Context, Qovery's own MCP server is created and selected automatically: organization-scoped, read-only, backed by a Viewer API token. That's enough for the agent to **propose** changes (open a PR).

To let it **apply** changes to Qovery directly instead, add the MCP server manually with an API Policy Token that has write permissions on that service's build/deploy configuration. See [Add MCP Servers](/configuration/agent-tasks/overview#creating-an-agent).
The template's instructions tell the agent never to apply changes to Qovery directly. If you edit the instructions to let it **apply** changes, add the MCP server manually with an API Policy Token that has write permissions on that service's build/deploy configuration. See [Add MCP Servers](/configuration/agent-tasks/overview#creating-an-agent).
</Step>
<Step title="Add a trigger">
Add a schedule trigger, for example weekly, to periodically review build performance, or a webhook trigger. See [Triggers](/configuration/agent-tasks/overview#triggers) for how they work in general.
Expand All @@ -42,7 +44,7 @@ To find concrete ways to make builds and deployments faster and cheaper, the age
This agent is typically run on a schedule rather than triggered concurrently, so **In Place** (the default) works well. Use **Clone Environment** instead if you expect overlapping runs. See [Execution Mode](/configuration/agent-tasks/overview#execution-mode).
</Step>
<Step title="Trigger a first run and check the results">
Click **Trigger** on the agent task's overview page to run it on demand. Check the run under its **Deployments** tab, and review the PR it opened (or the build configuration it updated, if you granted write access).
Click **Trigger** on the agent task's overview page to run it on demand. Check the run under its **Deployments** tab, and review the PRs it opened and the recommendations in its summary.
</Step>
</Steps>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ When an incident fires, the agent:

<Steps>
<Step title="Create the agent task">
From the **Agent use cases** section when creating a new service, pick **Incident Analyzer with Honeybadger** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)), or start from scratch and paste in the instructions above.
From your environment's **Automations** tab, click **Create agent task > Create from template** and pick **Incident Analyzer with Honeybadger** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)), or choose **Create from scratch** and paste in the instructions above.
</Step>
<Step title="Connect the repository">
Add the Qovery service(s) this agent should investigate as its Context, their linked Git repository is included automatically so the agent can read recent commits and merged PRs around the incident. Add a repository on its own only if it isn't tied to a Qovery service.
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration/agent-tasks/incident-analyser.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ When an incident fires, the agent:

<Steps>
<Step title="Create the agent task">
From the **Agent use cases** section when creating a new service, pick **Incident Analyzer with incident.io** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)), or start from scratch and paste in the instructions above.
From your environment's **Automations** tab, click **Create agent task > Create from template** and pick **Incident Analyzer with incident.io** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)), or choose **Create from scratch** and paste in the instructions above.
</Step>
<Step title="Connect the repository">
Add the Qovery service(s) this agent should investigate as its Context, their linked Git repository is included automatically so the agent can read recent commits and merged PRs around the incident. Add a repository on its own only if it isn't tied to a Qovery service.
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration/agent-tasks/jira-coding-agent.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Picks up a Jira issue and proposes the corresponding code change as a pull reque

<Steps>
<Step title="Create the agent task">
From the **Agent use cases** section when creating a new service, pick **Jira Coding Agent** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)).
From your environment's **Automations** tab, click **Create agent task > Create from template** and pick **Jira Coding Agent** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)).
</Step>
<Step title="Configure Jira access (optional)">
The template ships with three environment variables for connecting to Jira: a base URL (for example `https://company.atlassian.net`), an email, and an API token. Add `company.atlassian.net` to the domain allowlist so the agent can reach the Jira API. If you don't need Jira access for your workflow, remove these and adapt the instructions accordingly.
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration/agent-tasks/linear-coding-agent.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Picks up a Linear issue and proposes the corresponding code change as a pull req

<Steps>
<Step title="Create the agent task">
From the **Agent use cases** section when creating a new service, pick **Linear Coding Agent** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)).
From your environment's **Automations** tab, click **Create agent task > Create from template** and pick **Linear Coding Agent** (see [Creating an Agent](/configuration/agent-tasks/overview#creating-an-agent)).
</Step>
<Step title="Configure Linear access (optional)">
The template ships with one environment variable for connecting to Linear: an API key. If you don't need Linear access for your workflow, remove it and adapt the instructions accordingly.
Expand Down
51 changes: 39 additions & 12 deletions docs/configuration/agent-tasks/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,18 @@ Agent Tasks are one-time or scheduled jobs delegated to AI agents, running on yo
## Creating an Agent

<Steps>
<Step title="Create New Service">
In your environment, click **New Service > Create new service**. Under **Agent use cases**, pick a ready-made template (see [Tutorials](#tutorials) below) or **Start from scratch**.
<Step title="Create an Agent Task">
In your environment, open the **Automations** tab and click **Create agent task**. Choose **Create from template** to pick a ready-made template (see [Ready-Made Templates](#ready-made-templates) below), or **Create from scratch** to configure every part yourself.

<Frame>
<img src="/images/configuration/agent-tasks/agent-task-services-list.png" alt="Create new service screen showing the Agent use cases section" />
</Frame>
While the environment has no agent task yet, the **Automations** tab shows the template catalog directly. Selecting a template opens the creation form pre-filled with that template.
</Step>
<Step title="Add Context (Optional)">
Connect a Qovery service, a Git repository, or both, for the agent to load as context. A Qovery service's linked Git repository is included automatically, no need to add it separately, connect a repository on its own only when it isn't tied to a Qovery service.
</Step>
<Step title="Choose a Provider and Model">
Pick **Claude** (Anthropic) or **AWS Bedrock**, then select an existing token or create a new one on the fly. A token created here is saved and can be reused by any other agent task in the organization, no need to re-enter credentials each time. Tokens can also be managed centrally from **Organization Settings > Agent > Token**.
Pick **Claude** (Anthropic) or **AWS Bedrock**, then select an existing token or create a new one on the fly. A token created here is saved and can be reused by any other agent task in the organization, no need to re-enter credentials each time. Tokens can also be managed centrally from **Organization Settings > Agent > Token**. When you create an AWS Bedrock token, also select its **AWS region** (`eu-west-1` by default).

Once a token is selected, pick the **Model** the agent runs on from the list of models available to that token. The first available model is selected by default. For AWS Bedrock, the models offered depend on the token's AWS region. You can change the model later from the agent task's **Settings > AI configuration**.
Once a token is selected, pick the **Model** the agent runs on from the list of models available to that token. The first available model is selected by default. For AWS Bedrock, the models offered depend on the token's AWS region. If the models can't be loaded, check the token's API key (Claude) or its AWS credentials and region (AWS Bedrock). Use **Edit token** next to the token selector to update the selected token. You can change the model later from the agent task's **Settings > AI configuration**.
</Step>
<Step title="Add MCP Servers (Optional)">
If you added a Qovery service as Context in the previous step, Qovery's own MCP server is created and selected automatically: organization-scoped, read-only, backed by a Viewer API token. No URL, header, or token to configure. This is also preconfigured for the Incident Analyzer (incident.io and Honeybadger) and Build & deployment optimizer templates.
Expand Down Expand Up @@ -58,6 +56,18 @@ Agent Tasks are one-time or scheduled jobs delegated to AI agents, running on yo
<img src="/images/configuration/agent-tasks/agent-task-creation-flow.png" alt="New agent task form with Context, Provider, MCP, Automations, and Instructions on the left, and Resources, Governance, Environment variables, and Advanced settings on the right" />
</Frame>

## Ready-Made Templates

The template catalog groups the available templates by category:

- **Optimization**: [Build & deployment optimizer](/configuration/agent-tasks/build-deployment-optimizer)
- **Incident Analyzer**: [Incident Analyzer with incident.io](/configuration/agent-tasks/incident-analyser), [Incident Analyzer with Honeybadger](/configuration/agent-tasks/incident-analyser-honeybadger), Sentry Incident Analyzer, and Incident Analyzer
- **Coding Agent**: [Jira Coding Agent](/configuration/agent-tasks/jira-coding-agent), [Linear Coding Agent](/configuration/agent-tasks/linear-coding-agent), Slack Coding Agent, and Coding Agent

Sentry Incident Analyzer and Slack Coding Agent ship with a secret environment variable to fill in (`SENTRY_AUTH_TOKEN` and `SLACK_BOT_TOKEN` respectively), and a domain allowlist pre-filled with the hosts they need (`sentry.io` and `*.sentry.io`, or `slack.com`, plus GitHub, GitLab, and Bitbucket). Incident Analyzer and Coding Agent are not tied to a specific provider: they work on the payload sent to their webhook.

If the template you need isn't listed, click **Request agent template** in the **Automations** tab, describe the template you'd like Qovery to add next, and click **Send request**.

## Execution Mode

Choose where the agent runs when it's triggered:
Expand All @@ -69,7 +79,7 @@ Choose where the agent runs when it's triggered:
In **In Place** mode, a new trigger replaces the currently running execution, there's no run history if the agent is triggered multiple times. Use **Clone Environment** for agents that can be triggered frequently or concurrently, and **In Place** for agents on a predictable schedule where overlap isn't a concern.
</Warning>

Each ready-made template has a sensible default: Incident Analyzer (both the incident.io and Honeybadger variants), Jira Coding Agent, and Linear Coding Agent default to Clone Environment, since an incident or a labeled ticket can trigger them frequently or concurrently. Build & deployment optimizer, typically run on a schedule, defaults to In Place.
Each ready-made template has a sensible default: the Incident Analyzer and Coding Agent templates default to Clone Environment, since an incident, a ticket, or a request can trigger them frequently or concurrently. Build & deployment optimizer, typically run on a schedule, defaults to In Place.

### Limits

Expand All @@ -80,7 +90,7 @@ Each ready-made template has a sensible default: Incident Analyzer (both the inc

## Triggers and Outputs

Add a trigger to run the agent automatically, and optionally an output to send its result somewhere when it's done. You can also trigger any agent task on demand: click the **Trigger** (play) button on its overview page, or from the environment's services list.
Add a trigger to run the agent automatically, and optionally an output to send its result somewhere when it's done. You can also trigger any agent task on demand: click the **Trigger** (play) button on its overview page, or from the **Agent tasks** list in the environment's **Automations** tab.

<Frame>
<img src="/images/configuration/agent-tasks/trigger-agent-task.png" alt="Agent task overview page with the Trigger play button highlighted in the top right" />
Expand All @@ -89,7 +99,7 @@ Add a trigger to run the agent automatically, and optionally an output to send i
### Triggers

- **On a schedule**: a cron expression and timezone, for example `0 8 * * 1-5` for 8:00 AM, Monday through Friday.
- **From a webhook**: Qovery generates a unique URL for the agent task, visible later in the environment's **Agent Tasks** list (for example `https://webhook.qovery.com/api/v1/hook/...`). Anything that can send a POST request to that URL starts the agent.
- **From a webhook**: Qovery generates a unique URL for the agent task, visible later by hovering **Webhook** in the **Trigger** column of the **Agent tasks** list in the environment's **Automations** tab (for example `https://webhook.qovery.com/api/v1/hook/...`). Anything that can send a POST request to that URL starts the agent.

### Outputs

Expand Down Expand Up @@ -120,7 +130,7 @@ Some agents use a different, more direct pattern instead: storing a chat webhook
A description of what the agent does.
</Accordion>
<Accordion title="Resources" icon="gauge-high">
CPU (mCPU), memory (MB), and storage (GB) allocated to the agent, same as any other Qovery service.
CPU (mCPU), memory (MiB), and storage (GB) allocated to the agent, same as any other Qovery service. CPU and memory are required, with a minimum of 1000 mCPU and 2048 MiB. The ready-made templates start at these minimums.
</Accordion>
<Accordion title="Governance" icon="shield-check">
A domain allowlist controls which external hosts the agent task can reach: comma-separated hostnames, or `*` for all domains.
Expand All @@ -133,9 +143,26 @@ Some agents use a different, more direct pattern instead: storing a chat webhook
</Accordion>
</AccordionGroup>

On an existing agent task, the **Connections**, **Automations**, and **Outputs** settings, and the Dockerfile fragment under **Advanced settings**, are edited in a modal or side panel and saved from there with **Save**. These pages have no page-level save button. If saving fails, the modal or side panel stays open and shows an error.

## After You Create It

Agent Tasks appear in your environment overview under **Agent Tasks**, jobs delegated to AI agents, run once or on a schedule. Each one lists its status, last operation, underlying model, and a dedicated webhook URL you can call to trigger it from outside Qovery. That same webhook URL is also shown on the agent task's own overview page.
Agent tasks appear in the **Agent tasks** list of your environment's **Automations** tab, one-time tasks delegated to AI agents. Each one lists its name, whether it is enabled, its state, its last operation, and its trigger: **Schedule** with the date of the next run (or **Paused**), or **Webhook**, whose dedicated URL you can call to trigger the agent from outside Qovery. That same webhook URL is also shown on the agent task's own overview page.

## Run History

The **Runs** tab of an agent task lists its runs, with these columns:

- **Date**: when the run started and, once finished, when it ended (UTC), with the run ID. Hover the date to see the exact start and end times, or click the copy icon next to the run ID to copy it.
- **Status**: `Queued`, `Running`, `Completed`, `Failed`, or `Cancelled`.
- **Trigger**: `Manual`, `Schedule`, or `Webhook`.
- **Payload**: the payload recorded for the run, or `—` when there is none.
- **Duration**: how long the run took.
- **Prompt**: the prompt the run used.

Click a run to open its **Run details** side panel, which shows the run ID, trigger, status, start and end times (UTC), duration, full payload, and full prompt. Until the agent task has run, the tab shows **No runs yet**: use the **Trigger** (play) button in the header to start one.

The agent task's overview page also has a **Last run** section showing the trigger, how long ago the latest run happened, and its status. Click it to open that run's details, or click **See all runs** to go to the **Runs** tab. The **Deployments** tab of an agent task lists its deployments, like any other service.

## Tutorials

Expand Down
Loading
Loading