External agents

GitLab Duo agents work in parallel to help you create code, research results, and perform tasks simultaneously.

You can create an agent and integrate it with an external AI model provider to customize it to your organization’s needs. You use your own API key to integrate with the model provider.

Then, in a project issue, epic, or merge request, you can mention that external agent in a comment or discussion and ask the agent to complete a task.

The external agent:

• Reads and analyzes the surrounding context and repository code.
• Decides the appropriate action to take, while adhering to project permissions and keeping an audit trail.
• Runs a CI/CD pipeline and responds inside GitLab with either a ready-to-merge change or an inline comment.

The following integrations have been tested by GitLab and are available:

• Anthropic Claude
• OpenAI Codex
• Opencode
• Amazon Q
• Google Gemini CLI

For a click-through demo, see DAP with Amazon Q.

Prerequisites

Before you can create an agent and integrate it with an external AI model provider, you must meet the prerequisites.

AI model provider credentials

To integrate your agent with an external AI model provider, you must have access credentials. You can use either an API key for that model provider or GitLab-managed credentials.

API keys

To integrate your agent with an external AI model provider, you can use an API key for that model provider:

• For Anthropic Claude and Opencode, use an Anthropic API key.
• For OpenAI Codex, use an OpenAI API key.

GitLab-managed credentials

Instead of using your own API keys for external AI model providers, you can configure external agents to use GitLab-managed credentials through an AI gateway. This way, you do not have to manage and rotate API keys yourself.

When you use GitLab-managed credentials:

• Set injectGatewayToken: true in your flow configuration file.
• Remove the API key variables (for example, ANTHROPIC_API_KEY) from your CI/CD variables.
• Configure the external agent to use the GitLab AI gateway proxy endpoints.

The following environment variables are automatically injected when injectGatewayToken is true:

• AI_FLOW_AI_GATEWAY_TOKEN: the authentication token for AI Gateway
• AI_FLOW_AI_GATEWAY_HEADERS: formatted headers for API requests

GitLab-managed credentials are available only for Anthropic Claude and Codex.

Create a service account

Prerequisites:

• On GitLab.com, you must have the Owner role for the top-level group the project belongs to.
• On GitLab Self-Managed and GitLab Dedicated, you must have one of the following:
  • Administrator access to the instance.
  • The Owner role for a top-level group and permission to create service accounts.

Each project that mentions an external agent must have a unique group service account. Mention the service account username when you assign tasks to the external agent.

To set up the service account, take the following actions. If you do not have sufficient permissions, ask your instance administrator or top-level group Owner for help.

1. Create a service account.
2. Create a personal access token for the service account with the following scopes:
   • write_repository
   • api
   • ai_features
3. Add the service account to your project with the Developer role. This ensures the service account has the minimum permissions necessary.

When adding the service account to your project, you must enter the exact name of the service account. If you enter the wrong name, the external agent does not work.

Configure CI/CD variables

Prerequisites:

• You must have at least the Maintainer role for the project.

Add the following CI/CD variables to your project’s settings:

To add or update a variable in the project settings:

1. On the left sidebar, select Search or go to and find your project. If you’ve turned on the new navigation, this field is on the top bar.
2. Select Settings > CI/CD.
3. Expand Variables.
4. Select Add variable and complete the fields:

   • Type: Select Variable (default).

   • Environments: Select All (default).

   • Visibility: Select the desired visibility.

     For the API key and personal access token variables, select Masked or Masked and hidden.

   • Clear the Protect variable checkbox.

   • Clear the Expand variable reference checkbox.

   • Description (optional): Enter a variable description.

   • Key: Enter the environment variable name of the CI/CD variable (for example, GITLAB_HOST).

   • Value: The value of the API key, personal access token, or host.

5. Select Add variable.

For more information, see how to add CI/CD variables to a project’s settings.

Create an external agent

Create an external agent and configure it to run on your environment with a flow configuration.

By using the AI Catalog

Prerequisites:

• You must have at least the Maintainer role for the project.

1. On the left sidebar, select Search or go to and find your project. If you’ve turned on the new navigation, this field is on the top bar.
2. Select Automate > Flows.
3. Select New flow.
4. Under Basic information:
   1. In Display name, enter a name.
   2. In Description, enter a description.
5. Under Visibility & access:
   1. For Visibility, select Private or Public.
6. Under Configuration, enter your flow configuration. You can write your own configuration, or edit one of the templates below.
7. Select Create flow.

The external agent appears in the AI Catalog.

By using a flow configuration file

If you create external agents by manually adding flow configuration files, you must create a different AI flow configuration file for each external agent.

Prerequisites:

• You must have at least the Developer role for the project.

To create a flow configuration file:

1. In your project, create a YAML file, for example: .gitlab/duo/flows/claude.yaml
2. Populate the file by using one of the flow configuration file examples.

Enable an external agent

If you created an external agent from the AI Catalog, you must enable it in a project to use it.

Prerequisites:

• You must have at least the Maintainer role for the project.

To enable an external agent in a project:

1. On the left sidebar, select Search or go to > Explore.
2. Select AI Catalog.
3. Select the Flows tab.
4. Select your external agent, then select Enable in project.
5. From the dropdown list, select the project you want to enable the external agent in.
6. Select Enable.

The external agent appears in the project’s Flows list.

Create a trigger

You must now create a trigger, which determines when the external agent runs.

For example, you can specify the agent to be triggered when you mention a service account in a discussion, or when you assign the service account as a reviewer.

Use an external agent

Prerequisites:

• You must have at least the Developer role for the project.
• If you created an external agent from the AI Catalog, the agent must be enabled in your project.

1. In your project, open an issue, merge request, or epic.

2. Add a comment on the task you want the external agent to complete, mentioning the service account user. For example:

   @service-account-username can you help analyze this code change?

3. Under your comment, the external agent replies Processing the request and starting the agent….

4. While the external agent is working, the comment Agent has started. You can view the progress here is displayed. You can select here to see the pipeline in progress.

5. After the external agent has completed the task, you see a confirmation, and either a ready-to-merge change or an inline comment.