diff --git a/docs/docs.json b/docs/docs.json index 919dd941..063b3f11 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -617,6 +617,23 @@ } ] }, + { + "tab": "Autonomous Agents", + "icon": "robot", + "groups": [ + { + "group": "Autonomous Agents", + "pages": [ + "rde/agents/overview", + "rde/agents/getting-started", + "rde/agents/agent-blueprints", + "rde/agents/managing-runs", + "rde/agents/linear-integration", + "rde/agents/agent-template" + ] + } + ] + }, { "tab": "For Users", "icon": "user", diff --git a/docs/rde/admin/blueprint-management.mdx b/docs/rde/admin/blueprint-management.mdx index 47531255..5bd8db34 100644 --- a/docs/rde/admin/blueprint-management.mdx +++ b/docs/rde/admin/blueprint-management.mdx @@ -15,6 +15,10 @@ From a technical perspective, each blueprint maps to a **Qovery project and envi As an admin, you decide what each blueprint contains, who can access it, and what it can connect to. This is where governance happens - invisibly to the builder, but completely under your control. The blueprint itself is a standard Qovery environment, managed through the Qovery Console, CLI, or [Terraform](/rde/admin/blueprint-management#managing-blueprints-with-terraform) as usual. + +Blueprints come in two types: **Workspace Blueprints** (the default, covered on this page) and **Agent Blueprints** (for autonomous AI agents). When you click "Create Blueprint", a chooser dialog lets you select the type. For agent blueprint configuration, see [Agent Blueprints](/rde/agents/agent-blueprints). + + ## Registering a Blueprint diff --git a/docs/rde/agents/agent-blueprints.mdx b/docs/rde/agents/agent-blueprints.mdx new file mode 100644 index 00000000..9aee5ce5 --- /dev/null +++ b/docs/rde/agents/agent-blueprints.mdx @@ -0,0 +1,133 @@ +--- +title: "Agent Blueprints" +description: "Configure blueprints for autonomous AI agents - runtime selection, repository setup, Linear integration, and resource tuning." +--- + +import RdePreviewWarning from "/snippets/rde-preview-warning.mdx"; + + + +## 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. 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](/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 @mentioned or assigned on issue | +| **Appears in catalog** | Yes | No | +| **Additional config** | None | Runtime, repositories, Linear 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, 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](#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. | + +## 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](/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 + +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 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](/rde/agents/linear-integration#connecting-linear) 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. + + diff --git a/docs/rde/agents/agent-template.mdx b/docs/rde/agents/agent-template.mdx new file mode 100644 index 00000000..f9f6755d --- /dev/null +++ b/docs/rde/agents/agent-template.mdx @@ -0,0 +1,191 @@ +--- +title: "Agent Template" +description: "The official Docker image template for running autonomous AI agents on Qovery - architecture, environment variables, customization, and governance." +--- + +import RdePreviewWarning from "/snippets/rde-preview-warning.mdx"; + + + +## Overview + +The [autonomous agent template](https://github.com/Qovery/autonomous-agent-template) is the official Docker image for running headless AI agents on Qovery. When deployed as a workspace, the container automatically fetches a Linear issue, runs an AI agent, opens a pull request, and exits. + +You can use the template directly or extend it with project-specific dependencies. + +## Quick Start + +### Use the image directly + +```dockerfile +FROM ghcr.io/qovery/autonomous-agent-template:latest + +# Add your project-specific dependencies +RUN apt-get update && apt-get install -y your-deps +``` + +### Or build from source + +```bash +git clone https://github.com/Qovery/autonomous-agent-template.git +cd autonomous-agent-template +docker build -t my-autonomous-agent . +``` + +Then register the image as a blueprint in the portal and enable autonomous mode. See [Getting Started](/rde/agents/getting-started) for the full walkthrough. + +## How the Agent Run Works + +When the portal launches a workspace from the template, the container executes a 7-step autonomous cycle: + + + + If configured, the entrypoint starts an HTTP proxy that intercepts all outbound traffic from the agent and applies organization policies (allowlists, secret detection, rate limiting). + + + + The script reads the issue ID from environment variables, calls the Linear API, and writes the issue title and description to a task file. + + + + The target repository is cloned using the configured git token. A branch is created automatically from the issue key and title (e.g., `agent/ENG-123-fix-login-validation`). + + + + The configured runtime executes headlessly with the task file as the prompt: + + | Runtime | Command | + |---------|---------| + | Claude Code | `claude -p ""` | + | OpenCode | `opencode run ""` | + | Codex | `codex --full-auto ""` | + | Gemini CLI | `gemini -p ""` | + | Cursor CLI | `cursor-agent ""` | + + The command is wrapped in a `timeout` using the configured run timeout. Exit code 124 indicates a timeout. + + During execution, the agent can stream live progress updates to Linear via the portal's progress endpoint. These appear as real-time "thought" activities in the Linear issue, giving your team visibility into what the agent is doing. + + + + If the agent made code changes, they are committed and pushed to the branch. If no changes were made, the run reports a failure ("no code changes"). + + + + A PR is created on the git provider (GitHub, GitLab, or Bitbucket) with the issue context in the body. The PR title includes the Linear issue key. + + + + The container calls back to the portal API to record the result. The portal then emits structured activities to the Linear agent session - updating the plan to completed, adding external URLs (dashboard link, PR link), and posting a response or error activity visible inline in Linear. A lifecycle comment is also posted on the issue for audit purposes. The workspace is automatically cleaned up after completion. + + + +## Environment Variables + +These variables are injected automatically by the portal when it launches the workspace. You do not set them manually. + +| Variable | Description | +|----------|-------------| +| `LINEAR_API_TOKEN` | Linear API token for reading issues and posting comments | +| `LINEAR_ISSUE_ID` | Linear issue node ID to work on | +| `LINEAR_ISSUE_KEY` | Human-readable issue key (e.g., `ENG-123`) | +| `RDE_AUTONOMOUS_AGENT` | Runtime to use: `claude`, `opencode`, `codex`, `gemini`, or `cursor` | +| `RDE_RUN_CALLBACK_URL` | Portal API callback URL for reporting results | +| `RDE_RUN_TIMEOUT_MIN` | Hard timeout for the agent run (minutes) | +| `RDE_LINEAR_STATE_REVIEW_ID` | Linear workflow state ID for the In-Review transition (optional) | +| `RDE_LINEAR_STATE_FAILED_ID` | Linear workflow state ID for the Needs-Human transition (optional) | +| `ANTHROPIC_API_KEY` | API key for Claude Code, OpenCode, or Cursor runtimes | +| `OPENAI_API_KEY` | API key for Codex runtime | +| `GEMINI_API_KEY` | API key for Gemini CLI runtime | +| `BLUEPRINT_GIT_REPOSITORY` | Target repository URL | +| `BLUEPRINT_GIT_TOKEN` | Git token for clone, push, and PR creation | +| `BLUEPRINT_GIT_PROVIDER` | Git provider: `github`, `gitlab`, or `bitbucket` | + +## Git Provider Support + +The template supports three git providers for cloning repositories, pushing branches, and creating pull requests: + +| Provider | Value | PR API | +|----------|-------|--------| +| GitHub | `github` | GitHub REST API | +| GitLab | `gitlab` | GitLab REST API | +| Bitbucket | `bitbucket` | Bitbucket REST API | + +The provider is determined by the `BLUEPRINT_GIT_PROVIDER` environment variable, which is set automatically based on the repository URL configured in the agent blueprint. + +## RDE Configuration + +The template includes a `.config.rde.qovery.yml` file that customizes which components are installed by the Qovery RDE install script. It disables web IDE components that are not needed for headless autonomous mode while keeping all AI runtimes and development tooling. + +**Enabled components:** +- All AI runtimes (Claude Code, OpenCode, Codex, Cursor) +- Development tools (Node.js, Python, Ruby, Go) +- Git tooling (gh CLI, Qovery CLI) +- Terminal utilities (zellij, fzf, ripgrep) + +**Disabled components:** +- Code Server (web IDE) - not needed for headless mode +- Standard entrypoint - replaced by the autonomous entrypoint +- Browser-based extensions and resources + +See [Blueprint Management](/rde/admin/blueprint-management#official-workspace-template) for details on the RDE install script and `.config.rde.qovery.yml` configuration. + +## Agent Governance Proxy + +When the `RDE_PROXY_SCRIPT_GZ_B64` environment variable is set, the template starts an HTTP proxy before running the agent. This proxy intercepts all outbound HTTP/HTTPS traffic from the AI agent and enforces organization policies. + +The proxy supports: +- **Allowlists** - restrict which external hosts the agent can reach +- **Secret detection** - prevent accidental exfiltration of credentials +- **Rate limiting** - throttle API calls to prevent abuse +- **Kill switch** - immediately halt all agent egress + +The proxy runs on port 8877 and is transparent to the agent. All outbound traffic is routed through it automatically. + + +The governance proxy is configured at the organization level by the Qovery team. Contact Qovery support to enable and configure proxy policies for your autonomous agents. + + +## Customizing the Template + +To extend the template for your project: + +```dockerfile +FROM ghcr.io/qovery/autonomous-agent-template:latest + +# Add project-specific dependencies +RUN apt-get update && apt-get install -y \ + postgresql-client \ + redis-tools + +# Add custom agent instructions +COPY AGENTS.md /home/coder/project/AGENTS.md + +# Add custom scripts +COPY my-setup.sh /usr/local/bin/my-setup.sh +RUN chmod +x /usr/local/bin/my-setup.sh +``` + +Common customizations: +- **Project dependencies** - install language-specific packages or system libraries your codebase requires +- **Agent instructions** - add an `AGENTS.md` or `.claude/` directory with project-specific context for the AI agent +- **Setup scripts** - run initialization steps before the agent starts (e.g., database migrations, seed data) +- **Additional tools** - install linters, formatters, or test frameworks the agent needs + + +Keep the base image as your `FROM` layer and add customizations on top. This ensures you get updates to the AI runtimes, governance proxy, and core scripts automatically when the base image is updated. + + +## Next Steps + + + + Set up your first autonomous agent from scratch. + + + Configure runtime, repositories, and Linear integration. + + + Configure the issue flow, labels, and workflow states. + + diff --git a/docs/rde/agents/getting-started.mdx b/docs/rde/agents/getting-started.mdx new file mode 100644 index 00000000..af96f0de --- /dev/null +++ b/docs/rde/agents/getting-started.mdx @@ -0,0 +1,159 @@ +--- +title: "Getting Started with Autonomous Agents" +description: "Set up your first autonomous agent - from creating a blueprint to triggering your first run and reviewing the pull request." +--- + +import RdePreviewWarning from "/snippets/rde-preview-warning.mdx"; + + + +## 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](/rde/getting-started/admin-setup) +- A running Kubernetes cluster on Qovery +- Linear connected to the portal via OAuth - see [Linear Integration](/rde/agents/linear-integration#connecting-linear) +- A git repository the agent will work on +- An API key for your chosen AI runtime (Anthropic, OpenAI, or Google) + +## Create an Agent Blueprint + + + + Go to **Admin > Blueprints** and click **Create Blueprint**. In the type chooser dialog, select **Agent Blueprint**. + + + + 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. + + + + 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. + + + + 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. + + + + + 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](https://github.com/Qovery/autonomous-agent-template) as the base image. For advanced customization - adding project dependencies, custom agent instructions, or setup scripts - see [Agent Template](/rde/agents/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: + +```mermaid +stateDiagram-v2 + classDef qoveryPurple fill:#642DFF,color:#fff,stroke:#7C3FFF + [*] --> claimed:::qoveryPurple + claimed --> launching:::qoveryPurple + launching --> running:::qoveryPurple + running --> pr_opened:::qoveryPurple + running --> failed + running --> timed_out + pr_opened --> [*] + failed --> [*] + timed_out --> [*] +``` + +- **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 + + + + Deep dive on agent blueprint configuration, runtimes, and resource tuning. + + + Monitor active runs, review logs, and handle failures. + + + Configure the issue flow, labels, and workflow state mapping. + + diff --git a/docs/rde/agents/linear-integration.mdx b/docs/rde/agents/linear-integration.mdx new file mode 100644 index 00000000..65347a7d --- /dev/null +++ b/docs/rde/agents/linear-integration.mdx @@ -0,0 +1,232 @@ +--- +title: "Linear Integration" +description: "Connect autonomous agents to Linear via OAuth for instant, webhook-driven issue resolution." +--- + +import RdePreviewWarning from "/snippets/rde-preview-warning.mdx"; + + + +## Overview + +Autonomous agents integrate with Linear via OAuth. When a user @mentions or assigns the agent on a Linear issue, Linear sends a webhook to the portal, which instantly claims the issue, launches a workspace, and streams progress back to Linear. No polling and no labels are required for triggering. + +Linear is the currently supported project tracker. Jira and GitHub Issues integrations are planned. + +## Connecting Linear + + + + Navigate to **Admin > Settings** in the portal. + + + In the **Autonomous Agent** section, click the **Add to Linear** button. + + + Authorize the Qovery agent in Linear's consent screen. The agent requests access to issues, comments, workflow states, and teams. + + + You are redirected back to the portal. A green **Linear Agent connected** badge confirms the connection. + + + +The OAuth token auto-refreshes automatically. No manual token management is required. + + +Without a connected Linear workspace, agent blueprints cannot respond to issues. + + +## How the Issue Flow Works + +The following diagram shows the end-to-end flow from @mentioning or assigning the agent on an issue to receiving a pull request. + +```mermaid +sequenceDiagram + participant Dev as Developer + participant Linear as Linear + participant Portal as Portal Session Handler + participant DB as Database + participant WS as Workspace + + Dev->>Linear: @mentions or assigns agent on issue + Linear->>Portal: AgentSessionEvent webhook (HMAC-SHA256) + Portal->>Portal: Verifies signature + Portal->>Portal: Acknowledges within 10s + Portal->>Portal: Finds matching blueprint by team + Portal->>DB: Claims issue atomically + Note over DB: UNIQUE constraint on
(org_id, linear_issue_id)
prevents duplicates + Portal->>Linear: Sets agent as delegate on issue + Portal->>Linear: Posts 4-step plan activity + Portal->>WS: Launches workspace with agent config + + WS->>Linear: Streams thought activities (progress) + + alt Success + WS->>Portal: Callback with PR URL + Portal->>Linear: Updates plan (all steps completed) + Portal->>Linear: Adds external URL (PR link) + Portal->>Linear: Posts response activity with PR URL + Portal->>Linear: Transitions issue state + Portal->>WS: Keeps workspace briefly, then cleans up + else Failure or Timeout + WS->>Portal: Callback with error + Portal->>Linear: Updates plan (failed step) + Portal->>Linear: Posts error activity with details + Portal->>Linear: Transitions to Needs-Human state + Portal->>WS: Deletes workspace + end + + style Dev fill:#642DFF,color:#fff + style Linear fill:#7C3FFF,color:#fff + style Portal fill:#965FFF,color:#fff + style DB fill:#B080FF,color:#fff + style WS fill:#7C3FFF,color:#fff +``` + +## Configuring Teams + +Each agent blueprint monitors one Linear team. Only issues from the configured team are picked up by that blueprint. + +The team dropdown in the blueprint settings uses the OAuth connection to list all available teams. To monitor multiple teams, create separate agent blueprints - one per team. + +| Blueprint Setting | Value | +|---|---| +| **Linear Team** | Required. The team whose issues the agent monitors. | + +## Workflow State Mapping + +Agent blueprints map three Linear workflow states to key moments in the run lifecycle. These state transitions keep your Linear board in sync with agent activity. + +### In-Progress State (required) + +Set when the agent claims the issue. This signals to the team that work has started and prevents the issue from being picked up by another agent or assigned manually. + +The blueprint cannot function without this state configured. If autonomous mode is enabled but no In-Progress state is set, the blueprint will not process issues. + +### In-Review State (optional) + +Set when the agent successfully opens a pull request. If not configured, the issue state is not changed on success - only a lifecycle comment with the PR URL is posted. + +### Needs-Human State (optional) + +Set when the agent fails or the run times out. If not configured, the issue state is not changed on failure - only a lifecycle comment with the failure reason is posted. + +```mermaid +stateDiagram-v2 + classDef purple fill:#642DFF,color:#fff,stroke:#7C3FFF + classDef midPurple fill:#7C3FFF,color:#fff,stroke:#965FFF + classDef lightPurple fill:#965FFF,color:#fff,stroke:#B080FF + classDef successState fill:#7C3FFF,color:#fff,stroke:#642DFF + classDef failState fill:#B080FF,color:#fff,stroke:#965FFF + + [*] --> Backlog:::purple : Issue created + Backlog --> Triggered:::midPurple : Agent @mentioned or assigned + Triggered --> InProgress:::lightPurple : Agent claims issue + InProgress --> InReview:::successState : PR opened (optional) + InProgress --> NeedsHuman:::failState : Failed / timed out (optional) +``` + +| State | Required | When Set | Fallback if Not Configured | +|---|---|---|---| +| **In-Progress** | Yes | Agent claims the issue | Blueprint will not process issues | +| **In-Review** | No | Agent opens a PR | Comment posted, state unchanged | +| **Needs-Human** | No | Agent fails or times out | Comment posted, state unchanged | + +## Agent Activities in Linear + +When a run starts, the agent posts structured activities directly in the Linear issue - visible inline to all team members. + +### Agent Plan + +A 4-step checklist appears in the Linear issue: + +1. **Analyzing issue** +2. **Setting up workspace** +3. **Running AI agent** +4. **Opening pull request** + +Each step updates to in-progress or completed as the run progresses. If a step fails, it is marked accordingly. + +### Progress Updates + +The agent streams live "thought" activities from the workspace. These appear as real-time status updates in the Linear issue thread, giving the team visibility into what the agent is doing at each moment. + +### External URLs + +The session sidebar in Linear shows direct links to: + +- The **RDE dashboard** for the current run +- The **pull request** (when available) + +### Final Result + +On success, the agent posts a **response** activity containing the PR link. On failure, it posts an **error** activity with the failure details. + + +Traditional comments are also posted on the issue for audit trail purposes. + + +## Interacting with Agents from Linear + +### Bidirectional Messaging + +While an agent is running, users can post follow-up instructions as comments on the Linear issue. The agent processes these messages and can adjust its approach. Messages are delivered to the workspace via a polling endpoint (approximately every 5 seconds). + +### Stop Signal + +Linear's native stop button works. When pressed, the portal stops the workspace and marks the run as failed. + +### Slash Commands + +You can also control agents by posting a comment with one of these commands: + +| Command | Action | +|---------|--------| +| `/stop` | Stop the agent and its workspace environment | +| `/restart` | Restart the workspace environment | +| `/delete` | Stop the agent and mark the run as done | +| `/status` | Show the current agent status and workspace state | + +Commands are processed by the portal and take effect within seconds. The system posts a confirmation comment on the issue when the action completes. + + +This gives your team a way to guide autonomous agents without leaving Linear. If an agent is heading in the wrong direction, post a clarifying comment or stop it and provide more context. + + +## Concurrency and Timing + +### Max Concurrent Runs + +Each blueprint has a configurable concurrency cap (default: **3**). When the number of active runs (status `claimed`, `launching`, or `running`) reaches this limit, incoming webhooks for that blueprint are queued until a slot opens. + +### Run Timeout + +Each run has a maximum duration (default: **60 minutes**). When the timeout is reached, the workspace is stopped, the run status is set to `timed_out`, and a lifecycle comment is posted on the Linear issue. If a Needs-Human state is configured, the issue transitions to that state. + +### Atomic Claiming + +When the webhook fires, the session handler claims the issue atomically via a database unique constraint on `(org_id, linear_issue_id)`. This prevents duplicate runs even if the agent is @mentioned multiple times on the same issue. + +## Disconnecting Linear + +To disconnect, navigate to **Admin > Settings** and click the **Disconnect** link under the **Autonomous Agent** section. This revokes the OAuth tokens and removes the organization mapping. Existing runs are not affected, but no new runs can be triggered. + +## Future Integrations + + +**Jira** and **GitHub Issues** integrations are planned. The agent blueprint configuration will be extended with additional project tracker options. If you need a specific integration, contact the Qovery team. + + +## Next Steps + + + + Configure blueprints that define how agents run, including runtimes, repositories, and resource limits. + + + Monitor active runs, review results, and troubleshoot failures. + + + Set up your first autonomous agent from scratch. + + diff --git a/docs/rde/agents/managing-runs.mdx b/docs/rde/agents/managing-runs.mdx new file mode 100644 index 00000000..f396fb07 --- /dev/null +++ b/docs/rde/agents/managing-runs.mdx @@ -0,0 +1,203 @@ +--- +title: "Managing Runs" +description: "Monitor and manage autonomous agent runs - from the admin dashboard to individual run actions and lifecycle tracking." +--- + +import RdePreviewWarning from "/snippets/rde-preview-warning.mdx"; + + + +## Overview + +When a user @mentions or assigns the agent on a Linear issue that matches a blueprint's team, the system creates a **run**. A run tracks the full lifecycle from issue claim to pull request creation (or failure). This page covers the admin dashboard, run lifecycle, and management actions available to administrators. + +## Run Statuses + +Every run moves through a series of statuses that reflect its current stage. + +| Status | Description | +|--------|-------------| +| `claimed` | Issue claimed in Linear, workspace preparation started | +| `launching` | Workspace environment is deploying on your cluster | +| `running` | Agent is actively working on the issue | +| `pr_opened` | Agent completed successfully and opened a pull request. Workspace is kept alive briefly, then auto-deleted. | +| `failed` | Agent encountered an error or was stopped manually. Workspace environment is auto-deleted. | +| `timed_out` | Run exceeded the configured timeout. Workspace environment is auto-deleted. | +| `done` | Run was deleted by an admin | + +```mermaid +stateDiagram-v2 + classDef purple fill:#642DFF,color:#fff,stroke:#7C3FFF + classDef midPurple fill:#7C3FFF,color:#fff,stroke:#965FFF + classDef lightPurple fill:#965FFF,color:#fff,stroke:#B080FF + classDef terminalFail fill:#ef4444,color:#fff + classDef terminalDone fill:#6b7280,color:#fff + + [*] --> claimed:::purple + claimed --> launching:::midPurple + launching --> running:::lightPurple + running --> pr_opened:::purple + running --> failed:::terminalFail + running --> timed_out:::terminalFail + claimed --> failed:::terminalFail : stop / delete + launching --> failed:::terminalFail : stop / delete + failed --> claimed:::purple : retry + timed_out --> claimed:::purple : retry + pr_opened --> [*] + failed --> [*] + timed_out --> [*] + claimed --> done:::terminalDone : delete + launching --> done:::terminalDone : delete + running --> done:::terminalDone : delete + done --> [*] +``` + +## Agents Overview Dashboard + +Navigate to **Admin > Agents > Overview** for a high-level view of all agent activity. + +### Stats Bar + +The top of the page displays aggregate counters: + +- **Active** - runs currently in `claimed`, `launching`, or `running` status +- **Completed** - runs that reached `pr_opened` +- **Failed** - runs in `failed` status +- **Timed Out** - runs in `timed_out` status +- **Total** - all runs across all statuses + +### Agent Topology Graph + +Below the stats bar, a visual graph maps the relationship between clusters, blueprints, and individual runs. + +- **Top level** - Kubernetes clusters where agents execute +- **Middle level** - agent blueprints deployed to each cluster +- **Bottom level** - individual run pills, color-coded by status + +Click a run pill to view its detail page. Click a blueprint node to edit its settings. + +Use the filter toggle to switch between **Active only** (default) and **All runs**. + +### Recent Runs + +A table at the bottom shows the latest 10 runs across all blueprints. The dashboard auto-refreshes every 30 seconds. + +## Runs Dashboard + +Navigate to **Admin > Agents > Runs** for the full runs table. + +The table includes these columns: + +| Column | Description | +|--------|-------------| +| Issue | Linear issue key, linked to the run detail page | +| Owner | Assigned owner email, with a fallback badge if applicable | +| Status | Current run status | +| PR | Link to the pull request (when available) | +| Started | Timestamp when the run was claimed | +| Updated | Last status change timestamp | +| Failure Reason | Error message for failed or timed-out runs | +| Actions | Dropdown with available management actions | + +The table auto-refreshes every 30 seconds. + +## Run Actions + +Each run supports a set of actions based on its current status. + +| Action | Available When | Effect | +|--------|---------------|--------| +| **Stop** | `claimed`, `launching`, `running` | Stops the workspace, marks the run as `failed` with reason "Stopped via portal", and posts a comment on the Linear issue | +| **Restart** | `running` (with active workspace) | Restarts the workspace environment and posts a comment on the Linear issue | +| **Retry** | `failed`, `timed_out` | Resets the run, re-claims the Linear issue, and launches a new workspace | +| **Delete** | `claimed`, `launching`, `running` | Stops the workspace, marks the run as `done` with reason "Deleted via portal", and posts a comment on the Linear issue | +| **View Workspace** | Any run with an active workspace | Opens the workspace in the portal | + + +All actions that modify a run are reflected in the Linear issue as lifecycle comments. This keeps your project tracker in sync with agent activity. + + +## Run Detail Page + +View detailed information for a single run at **Admin > Agents > Runs > [Run]**. + +The detail page shows: + +- **Linear issue title and description** - the full context the agent is working from +- **Status** - current run status with timestamps +- **Owner** - assigned owner, with a dropdown to reassign +- **PR URL** - link to the pull request (when available) +- **Timestamps** - when the run was claimed and last updated + +Quick links at the top provide direct access to: + +- **Workspace** - open the agent's workspace in the portal +- **Qovery Console** - view the underlying environment in the Qovery dashboard +- **Linear issue** - jump to the issue in Linear + + +When a run is assigned to the system fallback account, a **fallback** badge appears next to the owner. This indicates no human assignee was found on the Linear issue. + + +## Creating a Run Manually + +You can trigger a run manually without @mentioning the agent in Linear. + + + + Navigate to **Admin > Agents > Runs** and click **Create**. + + + + Type a Linear issue title or identifier (e.g., `ENG-142`) to search. Select the issue you want the agent to work on. + + + + The portal auto-matches an agent blueprint based on the issue's team. You can override the selection if multiple blueprints are available. + + + + Select an organization member as the run owner. If left empty, the system uses the Linear issue assignee or falls back to the system account. + + + + Click **Create**. The system validates that the selected blueprint has autonomous mode enabled and the In-Progress state is configured, then launches the run. + + + + +Manual run creation requires a blueprint with autonomous mode enabled and a configured In-Progress workflow state. If either is missing, the creation will fail with a validation error. + + +## Owner Assignment + +Runs are assigned an owner based on the following logic: + +1. **Linear issue assignee** - the email of the person assigned to the Linear issue is used by default. +2. **System fallback** - if the Linear issue has no assignee, the run is assigned to `autonomous-agent@qovery.com` and marked with `owner_fallback = true`. A **fallback** badge appears in the UI. +3. **Admin reassignment** - administrators can change the owner from the run detail page using the owner dropdown. + +## My Runs (User View) + +Users can view their assigned runs from their personal dashboard. The **My Runs** view shows the latest 50 runs assigned to the authenticated user, including: + +- Run status +- Linear issue link +- Pull request link (when available) +- Timestamps + +This view is read-only. Management actions (stop, restart, retry, delete) are only available from the admin dashboard. + +## Next Steps + + + + Configure blueprints that define how agents run, including runtimes, repositories, and resource limits. + + + Set up the OAuth connection, issue flow, and workflow state mapping. + + + Diagnose and resolve common agent failures. + + diff --git a/docs/rde/agents/overview.mdx b/docs/rde/agents/overview.mdx new file mode 100644 index 00000000..c9739927 --- /dev/null +++ b/docs/rde/agents/overview.mdx @@ -0,0 +1,98 @@ +--- +title: "Autonomous Agents" +description: "AI agents that autonomously resolve issues from your project tracker and open pull requests." +--- + +import RdePreviewWarning from "/snippets/rde-preview-warning.mdx"; + + + +Autonomous agents pick up issues from your project tracker, work on them in isolated cloud environments, and open pull requests - without human intervention. They use the same blueprint and governance infrastructure as workspaces, but operate autonomously. + +Linear is currently supported as the project tracker. Jira and GitHub Issues integrations are planned. + +## How It Works + +When a user @mentions or assigns the agent on a Linear issue, the agent claims it instantly, launches a workspace, writes the code, opens a pull request, and shuts down. Progress is streamed back to Linear in real time. + +```mermaid +flowchart LR + A["Agent @mentioned\nor assigned"] --> B["Agent\nclaims issue"] + B --> C["Workspace\nlaunches"] + C --> D["Agent\nwrites code"] + D --> E["PR opened"] + E --> F["Workspace\nstopped"] + + style A fill:#642DFF,color:#fff + style B fill:#7C3FFF,color:#fff + style C fill:#965FFF,color:#fff + style D fill:#965FFF,color:#fff + style E fill:#7C3FFF,color:#fff + style F fill:#642DFF,color:#fff +``` + +## Agents vs Workspaces + +Autonomous agents and workspaces share the same underlying infrastructure but serve different workflows. + +| | Workspaces | Autonomous Agents | +|---|---|---| +| **Trigger** | Human clicks "Create" | Agent @mentioned or assigned on issue | +| **Interaction** | Human works in browser | AI agent runs autonomously | +| **Output** | Running application | Pull request | +| **Lifecycle** | Manual start/stop | Auto-launch, auto-stop on completion | +| **Blueprint type** | Workspace Blueprint | Agent Blueprint | +| **Admin view** | Workspace Management | Agents Dashboard & Runs | + +## Supported Runtimes + +Each agent blueprint specifies which AI coding runtime to use. The runtime determines the CLI tool that drives the agent inside the workspace. + + + + Anthropic's coding agent. Runs `claude -p` with the issue description as the prompt. + + + Open-source coding agent. Runs `opencode run` to process the issue autonomously. + + + OpenAI's coding agent. Runs `codex --full-auto` for fully autonomous operation. + + + Google's coding agent. Runs `gemini -p` with the issue context as input. + + + Cursor's agent mode. Runs `cursor-agent` to resolve the issue. + + + +## Shared Infrastructure + +Autonomous agents run on the same Kubernetes cluster as workspaces. They use the same split architecture - the portal orchestrates agent runs from `rde.qovery.com`, while the agent containers execute on your infrastructure. The same security model applies: no inbound ports, outbound-only TLS/gRPC tunnels, and all code stays on your cluster. + +For details on the underlying infrastructure, see [Architecture](/rde/reference/architecture) and [Security & Data Residency](/rde/reference/security). + +## Supported Project Trackers + +**Linear** is the currently supported project tracker. You connect your Linear workspace via OAuth, and your team triggers agents by @mentioning or assigning them on issues. The agent responds instantly with a real-time plan and progress updates visible directly in Linear. + + +**Jira** and **GitHub Issues** integrations are planned. If you need a specific integration, contact the Qovery team. + + +## Next Steps + + + + Set up your first autonomous agent with Linear integration. + + + Configure blueprints that define how agents run. + + + Monitor agent runs, review results, and troubleshoot failures. + + + Connect Linear, configure labels, and manage issue routing. + + diff --git a/docs/rde/overview.mdx b/docs/rde/overview.mdx index aaff7997..da8b2280 100644 --- a/docs/rde/overview.mdx +++ b/docs/rde/overview.mdx @@ -12,7 +12,7 @@ description: "A self-service web portal that gives every team member their own i -Looking for the CLI-based approach? See [Remote Development Environments with the CLI](/getting-started/guides/use-cases/remote-development-environments) for managing RDEs via `qovery rde` commands. +Looking for the CLI-based approach? See [Remote Development Environments with the CLI](/cli/commands/rde) for managing RDEs via `qovery rde` commands. ## Your Team Is Already Building with AI @@ -85,6 +85,9 @@ The portal includes a **built-in terminal with Claude Code and OpenCode chat** f Route workspaces to specific Kubernetes clusters per blueprint for data residency, resource isolation, or specialized hardware requirements. + + Connect AI agents to your project tracker. They pick up issues, write code in isolated environments, and open pull requests - autonomously. + ## Secure by Design @@ -141,6 +144,11 @@ A **blueprint** is a pre-configured workspace template created by your platform The platform team controls what each blueprint can access: which databases, which internal APIs, which credentials. That governance is invisible to the builder. From their perspective, they just pick a template and get to work. +Blueprints come in two types: + +- **Workspace Blueprints** - The default. A human creates a workspace, works in the browser with built-in AI tools, and publishes their application. +- **Agent Blueprints** - Configured for autonomous AI agents. Instead of a human, an AI agent runs in the workspace, picks up issues from your project tracker, writes code, and opens pull requests. See [Autonomous Agents](/rde/agents/overview) for details. + Different teams get different blueprints, scoped to what they actually need: @@ -235,4 +243,7 @@ Before using the AI Builder Portal, make sure you have: Understand how the portal works under the hood. + + Let AI agents resolve issues and open pull requests autonomously. + diff --git a/docs/rde/reference/architecture.mdx b/docs/rde/reference/architecture.mdx index e9d9d3ad..fc68f064 100644 --- a/docs/rde/reference/architecture.mdx +++ b/docs/rde/reference/architecture.mdx @@ -302,11 +302,57 @@ The portal splits data storage between its database and the Qovery API: | User tags | Portal database | | Connection audit logs | Portal database | | Firewall rules and events | Portal database | +| Autonomous run state | Portal database | +| Linear issue mapping | Portal database | +| Agent run results (PR URL, failure reason) | Portal database | No source code, AI conversations, or application data is stored in the portal database. All development data lives exclusively in workspace containers on your cluster. +## Autonomous Agent Architecture + +Autonomous agents extend the portal with an automated issue-to-PR pipeline. Three components are added on top of the existing workspace infrastructure: + +**Background Runner** - A polling job that runs every 60 seconds. It scans all organizations with agent blueprints enabled, queries Linear for issues matching the configured team and label, claims them atomically via a database unique constraint, and launches workspaces. + +**Agent Workspace** - A standard workspace environment with the AI runtime (Claude Code, OpenCode, Codex, Gemini CLI, or Cursor CLI) pre-configured. The agent receives the Linear issue context, works on the code, and reports results via a callback endpoint. + +**Result Callback** - When the agent finishes, the workspace calls back to the API server with the result (PR opened, failed, or timed out). The API server updates the run status, stops the workspace, and posts a lifecycle comment on the Linear issue. + +```mermaid +sequenceDiagram + participant Linear + participant Runner as Background Runner + participant API as API Server + participant DB as Database + participant CP as Qovery Control Plane + participant Agent as Agent Workspace + + Runner->>Linear: Query issues with trigger label + Linear-->>Runner: Matching issues + Runner->>DB: Claim issue (atomic) + Runner->>Linear: Transition to In-Progress + Runner->>Linear: Post comment + Runner->>CP: Launch workspace + CP->>Agent: Deploy environment + Agent->>Agent: AI agent works on issue + Agent->>API: Report result + API->>DB: Update run status + API->>CP: Stop workspace + API->>Linear: Post result comment + API->>Linear: Transition state + + style Runner fill:#642DFF,color:#fff + style API fill:#642DFF,color:#fff + style DB fill:#642DFF,color:#fff + style CP fill:#1a1a2e,color:#fff + style Agent fill:#0d9488,color:#fff + style Linear fill:#1a1a2e,color:#fff +``` + +For a full walkthrough of the Linear integration, issue flow, and lifecycle comments, see [Linear Integration](/rde/agents/linear-integration). + ## Next Steps diff --git a/docs/rde/reference/troubleshooting.mdx b/docs/rde/reference/troubleshooting.mdx index dcb7c928..1b53454a 100644 --- a/docs/rde/reference/troubleshooting.mdx +++ b/docs/rde/reference/troubleshooting.mdx @@ -264,6 +264,60 @@ This page covers common issues you may encounter with the AI Builder Portal and +## Autonomous Agent Issues + + + + **Symptoms:** You @mentioned or assigned the agent on a Linear issue but nothing happened. + + **Solutions:** + - Verify **Linear is connected** via OAuth in **Admin > Settings**. The Autonomous Agent section should show a green "Linear Agent connected" badge. + - Verify the agent blueprint's **Linear team** matches the issue's team. The system finds blueprints by team - if no blueprint is configured for the issue's team, the agent cannot respond. + - Make sure you **@mentioned or assigned the agent** on the issue. Labeling an issue alone does not trigger the agent. + - Verify the blueprint has **autonomous mode enabled** in **Admin > Blueprints > [Blueprint] > Autonomous**. + - The **In-Progress state** must be configured on the blueprint. Without it, the agent cannot claim issues. + - Check that the blueprint's **max concurrent runs** limit has not been reached. View active runs in **Admin > Agents > Runs**. + - If the agent still does not respond, the webhook configuration may need attention. Contact Qovery support. + + + + **Symptoms:** A run was created but never progresses to 'running'. + + **Solutions:** + - The workspace environment may be failing to deploy. Check the **Qovery Console** for deployment errors on the workspace environment. + - Common causes: container image pull failure, insufficient cluster resources, invalid environment variables. + - Try **stopping** the run from **Admin > Agents > Runs**, then **retrying** it. + + + + **Symptoms:** The run status shows 'timed_out'. + + **Solutions:** + - The run exceeded the configured timeout. The issue may have been too complex for the agent. + - You can **retry** the run from the Runs dashboard. Consider increasing the timeout in the blueprint's Autonomous settings. + - Check the workspace logs in the Qovery Console for errors the agent encountered before timing out. + + + + **Symptoms:** The run status shows 'failed' with a failure reason. + + **Solutions:** + - Read the **failure reason** shown in the Runs dashboard or the run detail page. + - Common failures: invalid API key for the chosen runtime, repository clone failure (incorrect URL or expired token), agent crash. + - Check the workspace logs in the Qovery Console for detailed error output. + - Fix the underlying issue (e.g., update the API key or repository token) and **retry** the run. + + + + **Symptoms:** Multiple runs appear for the same Linear issue. + + **Solutions:** + - This should not happen under normal operation. The system uses a database unique constraint to prevent duplicate claims. + - If you see duplicates, one may have been created manually via the **Create** button while a webhook also triggered a run. The atomic constraint prevents this, but check if the runs are for different blueprints (which is allowed). + - Contact Qovery support if genuine duplicates appear for the same blueprint and issue. + + + ## Performance Issues diff --git a/docs/snippets/rde-preview-warning.mdx b/docs/snippets/rde-preview-warning.mdx new file mode 100644 index 00000000..95d93f29 --- /dev/null +++ b/docs/snippets/rde-preview-warning.mdx @@ -0,0 +1,3 @@ + +**Preview**: AI Builder Portal is in preview. Features and capabilities are under active development and may change. +