ContextQMD
Back to Gitlabhq

External agents

doc/user/duo_agent_platform/agents/external.md

18.11.220.9 KB
Original Source

{{< details >}}

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< collapsible title="Model information" >}}

  • Not available on GitLab Duo with self-hosted models

{{< /collapsible >}}

{{< history >}}

  • Introduced in GitLab 18.3 with a flag named ai_flow_triggers. Enabled by default.
  • Renamed from CLI agents in GitLab 18.6.
  • Enabling in groups introduced in GitLab 18.7 with a flag named ai_catalog_agents. Enabled on GitLab.com.
  • Enabling directly in projects as a maintainer introduced in GitLab 18.10 with a flag named ai_catalog_project_level_enablement. Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated by default.
  • Feature flag ai_catalog_project_level_enablement removed in GitLab 18.11.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.

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. 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.

Prerequisites

Security considerations

External agents integrate with third-party AI model providers and have different security characteristics than GitLab built-in agents and flows. By using external agents, you accept the following risks:

  • Prompt injection vulnerabilities: GitLab implements third-party prompt scanning to lower the risk of prompt injections. This scanning is not available for external agents.
  • Third-party provider dependency: The external AI model provider manages all security controls (including prompt scanning, monitoring, and alerting), not GitLab.
  • Network access: External agents make network calls to third-party AI providers. Data sent to these providers is subject to their security policies and data handling practices.
  • Limited isolation: External agents do not have the same level of network isolation and security restrictions that are applied to GitLab native agents and flows.

Before enabling external agents in your organization, review your security requirements and the security documentation provided by your chosen AI model provider.

For a broader overview of security threats and mitigations in the Duo Agent Platform, see the Duo Agent Platform security threats documentation.

Quickstart for GitLab-managed external agents

{{< details >}}

  • Tier: Premium, Ultimate
  • Offering: GitLab.com

{{< /details >}}

{{< history >}}

  • Introduced in GitLab 18.8 on GitLab.com.

{{< /history >}}

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

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

Managed external agents can use GitLab-managed credentials and can be enabled in groups without additional agent configuration necessary.

Required steps to enable and use managed agents:

  1. Access the agent in the AI Catalog. Search for the agent name, or use the direct URL.

    GitLab-managed external agents display a GitLab-maintained badge ({{< icon name="tanuki-verified" >}}).

  2. Enable the agent.

  3. Use the external agent in issues, epics or merge requests.

Claude Code Agent

The Claude Code Agent by GitLab uses GitLab-managed credentials and does not require additional configuration. This agent is available only on GitLab.com.

Codex Agent

The Codex Agent by GitLab uses GitLab-managed credentials and does not require additional configuration. This agent is available only on GitLab.com.

Amazon Q Developer Agent

The Amazon Q Developer Agent does not use GitLab-managed credentials. To use this agent, you must provide your own credentials. This agent is available only on GitLab.com.

To use the Amazon Q Developer Agent:

  • Add the following environment variables to the CI/CD settings of your project:

    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • AWS_REGION_NAME
    • AMAZON_Q_SIGV4

Develop with Gemini Agent

The Develop with Gemini Agent does not use the GitLab-managed credentials. To use this agent, you must provide your own credentials. This agent is available only on GitLab.com.

To use the Develop with Gemini Agent:

  • Add the following environment variables to the CI/CD settings of your project:

Add GitLab-managed agents to other instances

{{< details >}}

  • Offering: GitLab Self-Managed, GitLab Dedicated
  • Status: Experiment

{{< /details >}}

{{< history >}}

{{< /history >}}

Administrators can add the Claude Agent and Codex Agent to their GitLab instances.

Prerequisites:

  • You must be an administrator.

To add external agents to your instance:

  1. In the upper-right corner, select Admin.
  2. Select GitLab Duo.
  3. Under GitLab-managed external agents, select Add to AI Catalog.

You can also add external agents with the API.

Access credentials

{{< history >}}

{{< /history >}}

External agents use GitLab-managed credentials through an AI Gateway.

When you use GitLab-managed credentials:

  • Set injectGatewayToken: true in your external agent configuration.
  • 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 for only Anthropic Claude and OpenAI Codex.

Supported models

For GitLab-managed credentials, the following AI models are supported:

Anthropic Claude:

  • claude-haiku-4-5-20251001
  • claude-opus-4-5-20251101
  • claude-opus-4-6
  • claude-sonnet-4-20250514
  • claude-sonnet-4-5-20250929
  • claude-sonnet-4-6

OpenAI Codex:

  • gpt-5
  • gpt-5-codex
  • gpt-5-mini-2025-08-07
  • gpt-5.1
  • gpt-5.1-2025-11-13
  • gpt-5.1-codex
  • gpt-5.2-2025-12-11
  • gpt-5.3-codex
  • gpt-5.4-2026-03-05
  • gpt-5.4-mini
  • gpt-5.4-nano

Configure CI/CD variables

Add variables to your project to determine how GitLab connects to the third-party provider.

Prerequisites:

  • You must have the Maintainer or Owner role for the project.

To add or update a variable in the project settings:

  1. In the top bar, select Search or go to and find your project.
  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.

CI/CD variables for external agents

The following CI/CD variables are available:

IntegrationEnvironment variableDescription
AllGITLAB_TOKEN_<integration>Personal access token for the service account user.
AllGITLAB_HOSTGitLab instance hostname (for example, gitlab.com).
Amazon QAWS_SECRET_NAMEAWS Secret Manager secret name.
Amazon QAWS_REGION_NAMEAWS region name.
Amazon QAMAZON_Q_SIGV4Amazon Q Sig V4 credentials.
Google Gemini CLIGOOGLE_CREDENTIALSJSON credentials file contents.
Google Gemini CLIGOOGLE_CLOUD_PROJECTGoogle Cloud project ID.
Google Gemini CLIGOOGLE_CLOUD_LOCATIONGoogle Cloud project location.

Enable the agent

Enable an agent to trigger it from an issue, merge request, or discussion.

When you enable an agent in a project, it is enabled in the top-level group for that project at the same time.

Prerequisites:

  • You must have the Maintainer or Owner role for the project.

{{< tabs >}}

{{< tab title="From the managing project" >}}

To enable an external agent:

  1. In the top bar, select Search or go to and find your project.
  2. Select Automate > Agents.
  3. Select the Managed tab, then select the agent you want to enable.
  4. In the upper-right corner, select Enable.
  5. Under Project, select the project you want to enable the agent in.
  6. For Add triggers, select which event types trigger the external agent:
    • Mention: When the service account user is mentioned in a comment on an issue or merge request.
    • Assign: When the service account user is assigned to an issue or merge request.
    • Assign reviewer: When the service account user is assigned as a reviewer to a merge request.
  7. Select Enable.

{{< /tab >}}

{{< tab title="From the AI Catalog" >}}

To enable an external agent:

  1. In the top bar, select Search or go to > Explore.
  2. Select AI Catalog, then select the Agents tab.
  3. Select the agent you want to enable.
  4. In the upper-right corner, select Enable.
  5. Under Project, select the project you want to enable the agent in.
  6. For Add triggers, select which event types trigger the external agent:
    • Mention: When the service account user is mentioned in a comment on an issue or merge request.
    • Assign: When the service account user is assigned to an issue or merge request.
    • Assign reviewer: When the service account user is assigned as a reviewer to a merge request.
  7. Select Enable.

{{< /tab >}}

{{< /tabs >}}

The external agent appears in the group and project Automate > Agents pages. Members of any project in the top-level group can now enable the agent in their project.

A service account is created in the group. The name of the account follows this naming convention: ai-<agent>-<group>.

Enable in a project

If an external agent is already enabled in a top-level group, you can enable it in the group's projects.

Prerequisites:

  • You must have the Maintainer or Owner role for the project.
  • The agent must be enabled in the project's top-level group.

To enable an external agent in a project:

  1. In the top bar, select Search or go to and find your project.
  2. Select Automate > Agents.
  3. In the upper-right corner, select Enable agent from group.
  4. From the dropdown list, select the external agent you want to enable.
  5. For Add triggers, select which event types trigger the external agent:
    • Mention: When the service account user is mentioned in a comment on an issue or merge request.
    • Assign: When the service account user is assigned to an issue or merge request.
    • Assign reviewer: When the service account user is assigned as a reviewer to a merge request.
  6. Select Enable.

The external agent appears in the project's Automate > Agents list.

The top-level group's service account is added to the project. This account is assigned the Developer role.

Use an external agent

Prerequisites:

  • You must have the Developer, Maintainer, or Owner role for the project.
  • For GitLab-managed external agents and custom external agents created in the AI Catalog, the external agent must be enabled in your project.
  • To allow the agent to push to agent-created branches (branches starting with ^duo/(fix|feature|refactor|docs/).*`), you might have to create branch rules.

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

  2. Mention, assign, or request a review from the service account user. For example:

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

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

Create a custom external agent

{{< details >}}

  • Offering: GitLab Self-Managed

{{< /details >}}

{{< history >}}

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.

On GitLab Self-Managed, if the ai_catalog_create_third_party_flows feature flag is enabled, you can create an external agent with the AI Catalog and configure it to run in your environment.

On GitLab.com, you cannot create custom external agents. Instead, use a GitLab-managed external agent.

The preferred workflow is:

  1. Create the agent in the AI Catalog.
  2. Enable the agent for your project and specify a trigger that determines how you call the agent.

In this case, a service account is created for you. When the agent runs, it uses a combination of the user's memberships and the service account memberships. This combination is called a composite identity.

If you'd prefer, you can create an external agent manually.

Agent visibility

{{< history >}}

  • Roles that can view private agents expanded in GitLab 18.7.

{{< /history >}}

When you create a custom external agent, you select a project to manage it and choose whether the agent is public or private.

Public agents:

  • Can be viewed by anyone and can be enabled in any project that meets the prerequisites.

Private agents:

  • Can be viewed only by members of the managing project who have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role.
  • Cannot be enabled in projects other than the managing project.

Create the agent in the AI Catalog

Start by creating the external agent in the AI Catalog.

Prerequisites:

  • You must have the Maintainer or Owner role for the project.

To create an external agent:

  1. In the top bar, select Search or go to and find your project.
  2. Select Automate > Agents.
  3. Select New agent.
  4. Under Basic information:
    1. In Display name, enter a name.
    2. In Description, enter a description.
  5. Under Visibility & access, for Visibility, select Private or Public.
  6. Under Configuration:
    1. Select External.
    2. Enter your external agent configuration. You can write your own YAML, or edit an example configuration.
  7. Select Create agent.

The external agent appears in the AI Catalog.

Create an external agent manually

If you prefer to not follow the UI flow, you can create an external agent manually:

  1. Create a configuration file in your project.
  2. Create a service account.
  3. Create a trigger that determines how you call the agent.
  4. Use the agent.

In this case, you manually create the service account that is used to run the agent.

Create a configuration file

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

Prerequisites:

  • You must have the Developer, Maintainer, or Owner role for the project.

To create a 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 configuration file examples.

Create a service account

You must create a service account that has access to the projects where you expect to use an external agent.

When the agent runs, it uses a combination of the user's memberships and the service account memberships. This combination is called a composite identity.

Prerequisites:

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.

If you create an external agent from the AI Catalog and enable it in a top-level group, a service account is automatically created with the name ai-<agent>-<group>. For example, if you enable an agent named Claude code agent in the GitLab Duo group, the service account name is ai-claude-code-agent-gitlab-duo.

[!warning] If you use the same service account across multiple projects, that gives the external agent attached to that service account access to all of those projects.

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. For the top-level group, create a service account. Service accounts created for the instance are not supported.

    [!note] When you configure an existing service account as an external agent, no personal access tokens can be associated with that account. This behavior is meant to keep service accounts secure.

  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.

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.