Getting Started with Autonomous Agents

Set up your first autonomous agent - from creating a blueprint to triggering your first run and reviewing the pull request.

Preview: AI Builder Portal is in preview. Features and capabilities are under active development and may change.

Overview

Autonomous agents pick up Linear issues, work on them in isolated cloud workspaces, and open pull requests - without human intervention. This guide walks you through creating an agent blueprint and triggering your first run.

Prerequisites

Before starting, make sure you have:

• AI Builder Portal configured - see Admin Setup
• A running Kubernetes cluster on Qovery
• Linear connected to the portal via OAuth - see Linear Integration
• A git repository the agent will work on
• An API key for your chosen AI runtime (Anthropic, OpenAI, or Google)

Create an Agent Blueprint

1. Navigate to Blueprints

   Go to Admin > Blueprints and click Create Blueprint. In the type chooser dialog, select Agent Blueprint.

2. Choose a Runtime

   Select one of the five supported AI runtimes:

   Runtime	Command	API Key Variable
   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

   Optionally enter the API key for the selected runtime. The key is stored encrypted and injected into the workspace at launch.

3. Configure Repositories

   Add one or more git repositories the agent will work on.

   For each repository:

   • URL (required) - the HTTPS clone URL
   • Branch - defaults to main
   • Token - optional, required for private repositories

   At least one repository URL must be provided.

4. Connect to Linear

   Configure the Linear integration that drives the agent’s work queue.

   Required fields:

   • Linear Team - the team whose issues the agent will respond to
   • In-Progress State - the workflow state the issue transitions to when claimed by the agent

   Optional fields:

   • In-Review State - the workflow state when the agent opens a PR
   • Needs-Human State - the workflow state when the agent fails or times out

   Resource limits:

   • Max concurrent runs - how many issues the agent works on simultaneously (default: 3)
   • Run timeout - maximum duration per run in minutes (default: 60)

   The wizard also shows a label field (default: qovery-agent-ready). This label is stored for organization and display purposes. Triggering happens when users @mention or assign the agent on an issue - not via labels.

   Under Advanced, you can customize the blueprint name (default: Autonomous Agent), description, target cluster, and resource allocation (CPU, memory, storage). The defaults - 4000 mCPU, 4096 MB memory, 10 GB storage - work well for most workloads.

5. Create the Blueprint

   Click Create. The portal provisions a Qovery project and environment for the agent. Once complete, the blueprint appears in your admin panel under Admin > Blueprints.

The wizard uses the official agent template as the base image. For advanced customization - adding project dependencies, custom agent instructions, or setup scripts - see Agent Template.

Trigger Your First Run

1. Open your Linear workspace and navigate to the team you configured in the blueprint.
2. Open an existing issue or create a new one.
3. @mention the agent in a comment, or assign the agent to the issue.
4. The agent responds within seconds - a plan with four steps appears directly in the Linear issue.
5. The issue automatically transitions to the In-Progress state.

The agent is triggered by @mention or assignment, not by labels. The response is instant - driven by webhooks, not polling.

Monitor the Run

Navigate to Admin > Agents > Runs to watch the agent work.

A run progresses through these statuses:

• claimed - the agent has picked up the issue and reserved it
• launching - the cloud workspace is being provisioned
• running - the AI runtime is actively working on the issue
• pr_opened - the agent opened a pull request (success)
• failed - the agent encountered an error
• timed_out - the run exceeded the configured timeout

The runs table auto-refreshes every 30 seconds. When a run completes successfully, the PR URL appears in the table.

You can also follow the agent’s progress directly in the Linear issue, where it posts a real-time plan and status updates as structured activities.

What Happens Under the Hood

Here is what the system does end-to-end when the agent is triggered:

1. A user @mentions or assigns the agent on a Linear issue.
2. Linear sends a webhook to the portal. The session handler acknowledges within 10 seconds.
3. The handler finds the matching agent blueprint by the issue’s team.
4. It claims the issue atomically - a database constraint prevents duplicate runs.
5. A 4-step plan appears in the Linear issue, and the issue transitions to the In-Progress state.
6. A cloud workspace launches with the configured runtime, repositories, and API key.
7. The AI agent works on the code, streaming live progress updates to the Linear issue.
8. When the agent finishes, the portal updates the plan, posts the PR link (or error), transitions the issue state, and cleans up the workspace.

Next Steps

Agent Blueprints

Deep dive on agent blueprint configuration, runtimes, and resource tuning.

Managing Runs

Monitor active runs, review logs, and handle failures.

Linear Integration

Configure the issue flow, labels, and workflow state mapping.