# Custom agents

{{< details >}}

- Tier: [Free](../../../subscriptions/gitlab_credits.md#for-the-free-tier), Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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

- Available on [GitLab Duo with self-hosted models](../../../administration/gitlab_duo_self_hosted/_index.md)

{{< /collapsible >}}

{{< history >}}

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/549914) in GitLab 18.5 [with a feature flag](../../../administration/feature_flags/_index.md) named `global_ai_catalog`. Enabled on GitLab.com.
- Turning on agents in groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580307) in GitLab 18.7 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_agents`. Enabled on GitLab.com.
- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/568176) to beta in GitLab 18.7.
- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/work_items/585273) in GitLab 18.8.
- Feature flag `ai_catalog_agents` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/217802) in GitLab 18.9.
- Feature flag `global_ai_catalog` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/223135) in 18.10.
- Turning on agents directly in projects as a maintainer [introduced](https://gitlab.com/groups/gitlab-org/-/work_items/20743) in GitLab 18.10 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_project_level_enablement`. Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated by default.
- Available on the Free tier on GitLab.com with GitLab Credits in GitLab 18.10.
- Feature flag `ai_catalog_project_level_enablement` removed in GitLab 18.11.

{{< /history >}}

Agents use AI to perform tasks and answer complex questions. Create
custom agents to accomplish specific tasks, like creating merge
requests or reviewing code. Or, use the AI Catalog to discover agents
created by GitLab.

When you're ready to interact with an agent, turn it on and start using it
with GitLab Duo Chat in the GitLab UI, VS Code, and JetBrains IDEs.

## Prerequisites

- Meet the [prerequisites for the GitLab Duo Agent Platform](../_index.md#prerequisites).
- Have [custom agents turned on](#turn-custom-agents-on-or-off).

## Agent visibility

{{< history >}}

- Roles that can view private agents [expanded](https://gitlab.com/gitlab-org/gitlab/-/work_items/582507) in GitLab 18.7.
- Restricted visibility [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/603253) in GitLab 19.3 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_internal_visibility`. Enabled by default.
- Generally available in GitLab 19.4. Feature flag `ai_catalog_internal_visibility` removed.

{{< /history >}}

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

Public agents:

- Can be viewed by anyone and can be turned on in any project that meets the prerequisites.

Restricted agents:

- Can be viewed and used by members of any project in the top-level group of the managing project.
- Can be turned on in other projects in the same top-level group.
- Cannot be viewed or turned on outside that top-level group.
- Cannot be viewed in the AI Catalog in Explore.
- Can be created only from a project, not from the AI Catalog in Explore.

You cannot make a public agent restricted if the agent has been turned on by a project outside of that top-level group.

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 turned on in projects other than the managing project.

You cannot make a public or restricted agent private if the agent has been turned on by a project other than the managing project.

## View the agents for your project

Prerequisites:

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

To view a list of agents associated with your project:

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Agents**.
   - To view agents turned on in the project, select the **Enabled** tab.
   - To view agents managed by the project, select the **Managed** tab.

Select an agent to view its details.

## Create an agent

{{< history >}}

- Restricted visibility [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/603253) in GitLab 19.3 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_internal_visibility`. Enabled by default.
- Generally available in GitLab 19.4. Feature flag `ai_catalog_internal_visibility` removed.

{{< /history >}}

You can create an agent from a project, or by using the AI Catalog.

Prerequisites:

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

{{< tabs >}}

{{< tab title="From a project" >}}

To create an agent:

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Agents**.
1. Select **New agent**.
1. Under **Basic information**:
   1. In **Display name**, enter a name for the agent.
   1. In **Description**, enter a description for the agent.
1. Under **Visibility & access**, for **Visibility**, select **Private**, **Restricted**, or **Public**.
1. Under **Prompts**, in **System prompt**, enter a prompt to define
   the agent's personality, expertise, and behavior.
1. Optional. Under **Available tools**, from the **Tools** dropdown list,
   select which tools the agent can access.
   For example, for the agent to create issues automatically, select **Create issue**.

   > [!note]
   > Some tools require the IDE extension and are not available in the GitLab UI.
   > For more information, see the list of [agent tools](tools.md).
1. Select **Create agent**.

{{< /tab >}}

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

To create an agent:

1. In the top bar, select **Search or go to** > **Explore**.
1. Select **AI Catalog**, then select the **Agents** tab.
1. Select **New agent**.
1. Under **Basic information**:
   1. In **Display name**, enter a name for the agent.
   1. In **Description**, enter a description for the agent.
1. Under **Visibility & access**:
   1. From the **Managed by** dropdown list, select a project for the agent.
   1. For **Visibility**, select **Private** or **Public**.
1. Under **Prompts**, in **System prompt**, enter a prompt to define
   the agent's personality, expertise, and behavior.
1. Optional. Under **Available tools**, from the **Tools** dropdown list,
   select which tools the agent can access.
   For example, for the agent to create issues automatically, select **Create issue**.

   > [!note]
   > Some tools require the IDE extension and are not available in the GitLab UI.
   > For more information, see the list of [agent tools](tools.md).
1. Select **Create agent**.

{{< /tab >}}

{{< /tabs >}}

The agent appears in the AI Catalog. To use the agent with Chat, you must turn it on.

## Turn on an agent

{{< history >}}

- Turning on a public agent for multiple projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/600526) in GitLab 19.2 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_bulk_item_consumer_create`. Enabled by default.
- Feature flag `ai_catalog_bulk_item_consumer_create` removed in GitLab 19.4.
- Turning on an agent for all projects in a top-level group [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/627512) in GitLab 19.5 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_group_inherited_consumers`. Disabled by default.

{{< /history >}}

Turn on an agent to use it with Chat.

When you turn on an agent in a project, it is turned on in the top-level group for that project at the same time.
You can turn on an agent or flow up to 30 times per minute.

{{< tabs >}}

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

Prerequisites:

- Have the Maintainer or Owner role for the project.

To turn on an agent:

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Agents**.
1. Select the **Managed** tab, then select the agent you want to turn on.
1. In the upper-right corner, select **Enable**.
1. In the dialog, select **Enable**.

{{< /tab >}}

{{< tab title="From the top-level group" >}}

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

When you turn on an agent in a top-level group, the agent is turned on for all projects in the group.
Projects that you create in or transfer to the group later also get access to the agent.
You do not have to turn on the agent in each project.

Prerequisites:

- Have the Maintainer or Owner role for the top-level group.
- The agent is public, or restricted to the same top-level group.

To turn on an agent for all projects in a top-level group:

1. In the top bar, select **Search or go to** and find your top-level group.
1. In the left sidebar, select **AI** > **Agents**.
1. Select the agent you want to turn on.
1. In the upper-right corner, select **Enable for all projects**.
1. Select **Enable for all projects**.

   If the agent is already turned on in one or more projects in the group,
   select **Replace and enable for all projects**.
   The project configurations are deleted and the group configuration is used instead.

In the group, the agent is labeled **Enabled for all projects**.
In each project, the agent is labeled **Enabled by** followed by the group name.

To turn off the agent for all projects, on the agent's page, select **Disable for all projects**, then select **Disable**.

{{< /tab >}}

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

Prerequisites:

- Have the Maintainer or Owner role for the project.

To turn on an agent:

1. In the top bar, select **Search or go to** > **Explore**.
1. Select **AI Catalog**, then select the **Agents** tab.
1. Select the agent you want to turn on.
1. In the upper-right corner, select **Enable**.
1. Under **Select projects**, select the project you want to turn on the agent in.

   To turn on a public or restricted agent for multiple projects, select the relevant projects.
   You can select up to 100 projects.
   You can turn on an agent for multiple projects up to 10 times per minute.

1. Select **Enable**.

{{< /tab >}}

{{< /tabs >}}

The agent appears in the group and project **AI** > **Agents** pages.
If you turned on the agent in a project, maintainers of other projects in the top-level group
can also turn on the agent in their projects following the steps above.

In the project, you can start a new chat with the agent.
For more information, see [select an agent](../../gitlab_duo_chat/agentic_chat.md#select-an-agent).

## Use an agent

You can use a custom agent in the GitLab UI, VS Code, JetBrains IDEs, and as a subagent in a custom flow.

### In the GitLab UI

Prerequisites:

- Turn on the agent in the project you want to use it in.

To use a custom agent in the GitLab UI:

1. In the top bar, select **Search or go to** and find your project or group.
1. Open an issue, epic, or merge request.
1. On the GitLab Duo sidebar, select **Add new chat** ({{< icon name="pencil-square" >}}).
1. From the dropdown list, select the custom agent.

   A Chat conversation opens in the GitLab Duo sidebar on the right side of your screen.
1. Enter your question or request.

### In VS Code

Prerequisites:

- Turn on the agent in the project you want to use it in.
- Install and configure [GitLab for VS Code](../../../editor_extensions/visual_studio_code/setup.md)
  version 6.47.0 or later.
- Set a [default GitLab Duo namespace](../../profile/preferences.md#set-a-default-gitlab-duo-namespace).

To use a custom agent in VS Code:

1. In VS Code, in the Secondary Side Bar, select **GitLab Duo**.
1. Under the message box, from the agent dropdown list, select the custom agent.
   In the [classic layout](../../gitlab_duo_chat/agentic_chat.md#change-the-layout-in-your-ide), select the **Chat** tab, then from the
   **New chat** ({{< icon name="duo-chat-new" >}}) dropdown list, select the custom agent.
1. Enter your question or request.

### In JetBrains IDEs

Prerequisites:

- Turn on the agent in the project you want to use it in.
- Install and configure the [GitLab Duo plugin for JetBrains IDEs](../../../editor_extensions/jetbrains_ide/setup.md)
  version 3.19.0 or later.
- Set a [default GitLab Duo namespace](../../profile/preferences.md#set-a-default-gitlab-duo-namespace).

First, turn on the GitLab Duo Agent Platform:

1. In your JetBrains IDE, go to **Settings** > **Tools** > **GitLab Duo**.
1. Under **GitLab Duo Agent Platform**, select the **Enable GitLab Duo Agent Platform** checkbox.
1. Restart your IDE if prompted.

Then, to use a custom agent:

1. In your JetBrains IDE, on the right tool window bar, select **GitLab Duo Agent Platform** ({{< icon name="duo-agentic-chat" >}}).
1. Under the message box, from the agent dropdown list, select the custom agent.
   In the [classic layout](../../gitlab_duo_chat/agentic_chat.md#change-the-layout-in-your-ide), select the **Chat** tab, then from the
   **New chat** ({{< icon name="duo-chat-new" >}}) dropdown list, select the custom agent.
1. Enter your question or request.

### In a custom flow

A custom flow can use the agent as a subagent.
This feature is in [beta](../../../policy/development_stages_support.md#beta).
The flow lists the agent by item ID and exact version in its YAML, and a component of the flow
delegates tasks to it.
The agent does not have to be turned on in the project of the flow.
For the YAML, the rules, and the flag, see [`include`](../flows/custom_flows_schema.md#include).

When the agent is a subagent, the model that runs the flow reads its name and its description.
The model uses them to decide when to delegate a task to the agent.
Write the description so that a model can tell what the agent does and when to use it.
A description written only for people to read in the AI Catalog might not be enough.

## Turn off an agent

Prerequisites:

- For groups, you must have the Maintainer or Owner role.
- For projects, you must have the Maintainer or Owner role.

To turn off an agent:

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Agents**.
1. Find the agent you want to remove and select **Actions** ({{< icon name="ellipsis_v" >}}) > **Disable**.
1. On the confirmation dialog, select **Disable**.

The agent no longer appears in the project, and is not available in Chat.
You can turn off an agent or flow up to 30 times per minute.

## Duplicate an agent

To make changes to an agent without overwriting the original, create a copy of an existing agent.

Prerequisites:

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

To duplicate an agent:

1. In the top bar, select **Search or go to** > **Explore**.
1. Select **AI Catalog**, then select the **Agents** tab.
1. Select the agent you want to duplicate.
1. In the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}) > **Duplicate**.
1. Select the project where you want to duplicate the agent.
1. Optional. Edit any fields you want to change.
1. Select **Create agent**.

## Edit an agent

Edit an agent to change its configuration.

Prerequisites:

- You must be a member of the managing project and have the Maintainer or Owner role.

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Agents**.
1. Select the agent you want to edit.
1. In the upper-right corner, select **Edit**.
1. Edit any fields you want to change, then select **Save changes**.

## Hide an agent

Hide an agent to remove it from the AI Catalog.

After you hide an agent, users can't turn it on. However, they can still interact with the agent in the groups and projects it is already turned on in.

When a custom flow uses the agent as a subagent, hiding the agent stops that flow.
The flow stops at run time because the subagent can no longer be used.
To run the flow again, remove the agent from the `include` list of the flow, or replace it with a different agent.

Prerequisites:

- You must be a member of the managing project and have the Maintainer or Owner role.

To hide an agent:

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Agents**.
1. Find the agent you want to hide and select **Actions** ({{< icon name="ellipsis_v" >}}) > **Hide**.
1. In the confirmation dialog, select **Confirm**.

## Delete an agent

Delete an agent to remove it from the instance.

When you delete an agent, you can choose one of two deletion methods:

- **Delete permanently**: The agent is removed from the instance. This action cannot be undone.
- **Hide from the AI Catalog**: The agent is hidden instead of removed. Users can continue to use
  the agent in the groups and projects it is turned on in.

If a project other than the managing project has turned on the agent,
or a custom flow uses the agent as a subagent, the agent is always hidden instead of removed,
even when you choose **Delete permanently**.

When a flow uses a hidden agent as a subagent, a save that changes its YAML or increases its visibility fails.
The error shows the item ID and version of the agent, not its name.
To save the flow, remove the agent from the `include` list of the flow, or replace it with a different agent.

Prerequisites:

- You must be an administrator.

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Agents**.
1. Find the agent you want to delete and select **Actions** ({{< icon name="ellipsis_v" >}}) > **Delete**.
1. In the confirmation dialog, under **Deletion method**, select **Delete permanently** or **Hide from the AI Catalog**.
1. Select **Confirm**.

## Turn custom agents on or off

{{< history >}}

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/594615) in GitLab 19.0.

{{< /history >}}

By default, custom agents are turned on.
You can turn them on or off for a top-level group or for an instance.

When custom agents are turned off:

- Users cannot create, turn on, turn off, or execute custom agents.
- Existing custom agents are no longer visible
  in the project under **AI** > **Agents** > **Enabled**.
- Custom agents created in the project appear
  under **AI** > **Agents** > **Managed**, but cannot be executed.
- [Foundational agents](foundational_agents/_index.md) and [external agents](external.md) remain available.

{{< tabs >}}

{{< tab title="GitLab.com" >}}

Prerequisites:

- You must have the Owner role for the group.

1. In the top bar, select **Search or go to** and find your group.
1. In the left sidebar, select **Settings** > **GitLab Duo**.
1. Select **Change configuration**.
1. Under **Custom and external agents and flows**, select or clear the
   **Allow custom agents** checkbox.
1. Select **Save changes**.

This setting cascades to all subgroups in the group.

{{< /tab >}}

{{< tab title="GitLab Self-Managed" >}}

Prerequisites:

- You must be an administrator.

1. In the upper-right corner, select **Admin**.
1. In the left sidebar, select **GitLab Duo**.
1. Select **Change configuration**.
1. Under **Custom and external agents and flows**, select or clear the
   **Allow custom agents** checkbox.
1. Select **Save changes**.

When the instance-level setting is turned off,
group-level settings cannot override it.

{{< /tab >}}

{{< /tabs >}}

