> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Blueprints
> Configure blueprints for autonomous AI agents - runtime selection, repository setup, Linear or Jira integration, and resource tuning.
**Preview**: AI Builder Portal is in preview. Features and capabilities are under active development and may change.
## Overview
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 (Linear or Jira). When a matching issue is triggered, 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](/docs/rde/admin/blueprint-management) for those shared concepts.
## Workspace vs Agent Blueprints
| Aspect | Workspace Blueprint | Agent Blueprint |
| ---------------------- | ----------------------------------- | ------------------------------------------- |
| **Purpose** | Human development environment | Autonomous AI agent |
| **Trigger** | User creates workspace from catalog | Agent triggered from a Linear or Jira issue |
| **Appears in catalog** | Yes | No |
| **Additional config** | None | Runtime, repositories, tracker mapping |
| **Lifecycle states** | Testing / Enabled / Disabled | Testing / Enabled / Disabled |
| **Target cluster** | Configurable | Configurable |
| **Access control** | ACLs apply | N/A (not in user catalog) |
## Configuration Reference
These settings are specific to agent blueprints. They control which runtime executes the agent, which tracker the agent connects to, 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](#runtime-details) for options. |
| **Provider** | Enum | `linear` | The project tracker the agent connects to: `linear` or `jira`. Defaults to whichever tracker is connected. |
| **Team / Project** | String or null | `null` | The Linear team or Jira project whose issues the agent monitors. Required when autonomous mode is enabled. |
| **Claimed State / Status** | String or null | `null` | The workflow state (Linear) or status (Jira) the issue transitions to when the agent claims it. Required when autonomous mode is enabled. |
| **Review State / Status** | String or null | `null` | The state or status the issue transitions to when the agent opens a pull request. Optional. |
| **Failed State / Status** | String or null | `null` | The state or status 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 failed state if configured. |
Tracker-specific field names and semantics differ slightly between Linear and Jira. See [Linear Integration](/docs/rde/agents/linear-integration#workflow-state-mapping) and [Jira Integration](/docs/rde/agents/jira-integration#status-mapping) for the exact mappings.
## Runtime Details
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.
| Runtime | CLI Command | API Key Env Var |
| ----------- | ------------------- | ------------------- |
| Claude Code | `claude -p` | `ANTHROPIC_API_KEY` |
| OpenCode | `opencode run` | `ANTHROPIC_API_KEY` |
| Codex | `codex --full-auto` | `OPENAI_API_KEY` |
| Gemini CLI | `gemini -p` | `GEMINI_API_KEY` |
| Cursor CLI | `cursor-agent` | `ANTHROPIC_API_KEY` |
## Resource Defaults
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.
## Git Provider Support
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.
## Official Agent Template
Agent blueprints created through the wizard use the [official agent template](https://github.com/Qovery/autonomous-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](/docs/rde/agents/agent-template) for details on customization, environment variables, and the governance proxy.
## API Key Management
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](#runtime-details) table for the mapping.
The key is set during blueprint creation when you enter it in the wizard. To update it later:
1. Open the Qovery Console.
2. Navigate to the project and environment backing the agent blueprint.
3. 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.
## Editing Agent Blueprint Settings
New agent blueprints are created from the **Admin > Agent Blueprints** page using the **Create Agent Blueprint** wizard. This page lists all agent blueprints, each tagged with a Linear or Jira provider badge.
To modify an existing agent blueprint:
1. Navigate to **Admin > Blueprints** in the portal.
2. Click the blueprint name to open its settings.
3. Select the **Autonomous** tab.
From this tab you can:
* Enable or disable autonomous mode
* Change the AI runtime
* Update the tracker's team/project and state/status mappings
* Adjust concurrency limits and run timeout
The **claimed state/status** is required for the agent to claim issues. If autonomous mode is enabled but no claimed 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 the selected tracker connected via OAuth, a warning is displayed prompting you to connect it first. See [Linear Integration](/docs/rde/agents/linear-integration#connecting-linear) or [Jira Integration](/docs/rde/agents/jira-integration#connecting-jira) for setup instructions.
## Next Steps
Set up your first autonomous agent from scratch.
Monitor active runs, review results, and troubleshoot failures.
Configure labels, workflow states, and issue routing.
Configure the project, status mapping, and assignment triggering.