An agent blueprint is a blueprint with autonomous mode enabled. It defines which AI runtime to use, which repositories to clone, and how to connect to your project tracker. When a matching issue appears in Linear, the system launches a workspace from this blueprint and runs the agent autonomously.Agent blueprints share the same underlying infrastructure as workspace blueprints - lifecycle states, target cluster selection, and Qovery environment mapping all work the same way. See Blueprint Management for those shared concepts.
These settings are specific to agent blueprints. They control which runtime executes the agent, how the agent connects to Linear, and how many runs can execute concurrently.
Setting
Type
Default
Description
Autonomous Enabled
Boolean
false
Enables autonomous mode on the blueprint. When disabled, the blueprint behaves as a standard workspace blueprint.
Agent Runtime
Enum
claude
The AI coding runtime that drives the agent. See Runtime Details for options.
Linear Team
String or null
null
The Linear team whose issues the agent monitors. Required when autonomous mode is enabled.
In-Progress State
String or null
null
The Linear workflow state the issue transitions to when the agent claims it. Required when autonomous mode is enabled.
In-Review State
String or null
null
The Linear workflow state the issue transitions to when the agent opens a pull request. Optional.
Needs-Human State
String or null
null
The Linear workflow state the issue transitions to when the agent fails or times out. Optional.
System Prompt
String
(empty)
Optional instructions prepended to the issue context when the agent starts. Use this to provide project-specific guidance to the AI runtime.
Max Concurrent Runs
Number
3
Maximum number of issues the agent works on simultaneously. Each concurrent run launches a separate workspace.
Run Timeout
Number (minutes)
60
Maximum duration for a single agent run. The workspace is stopped when the timeout is reached, and the issue transitions to the Needs-Human state if configured.
Each agent blueprint specifies one AI coding runtime. The runtime determines which CLI tool runs inside the workspace and which API key environment variable is required.
Agent blueprints created through the wizard use these default resource allocations. You can adjust them under Advanced during creation or by editing the blueprint later.
Resource
Default
CPU
4000 mCPU (4 vCPU)
Memory
4096 MB (4 GB)
Storage
10 GB
The target cluster defaults to the first non-production cluster in your organization.
Agent blueprints support three git providers for cloning repositories, pushing branches, and creating pull requests:
Provider
Supported
GitHub
Yes
GitLab
Yes
Bitbucket
Yes
The provider is detected automatically from the repository URL configured in the blueprint. The agent template handles authentication, branch creation, and PR creation for all three providers.
Agent blueprints created through the wizard use the official agent template (ghcr.io/qovery/autonomous-agent-template:latest) as the base Docker image. This image includes all five AI runtimes, development tooling, and the autonomous entrypoint script.You can extend the template with project-specific dependencies by creating a custom Dockerfile that builds on top of the official image. See Agent Template for details on customization, environment variables, and the governance proxy.
The API key for the selected runtime is stored as an environment variable on the blueprint’s Qovery environment. Different runtimes use different environment variable names - see the Runtime Details table for the mapping.The key is set during blueprint creation when you enter it in the wizard. To update it later:
Open the Qovery Console.
Navigate to the project and environment backing the agent blueprint.
Edit the environment variables and update the relevant API key.
The API key is stored encrypted and injected into the workspace container at launch. It is never exposed in the portal UI after initial entry.
Update the Linear team and workflow state mappings
Adjust concurrency limits and run timeout
The In-Progress State is required for the agent to claim issues. If autonomous mode is enabled but no In-Progress state is set, the save button is disabled and the agent cannot run. Configure this field before enabling autonomous mode.
If the portal does not have Linear connected via OAuth, a warning is displayed on the Autonomous tab prompting you to connect Linear first. See Linear Integration for setup instructions.
