ContextQMD
Back to Gitlabhq

Custom agents

doc/user/duo_agent_platform/agents/custom.md

18.11.212.2 KB
Original Source

{{< details >}}

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

{{< /details >}}

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

{{< /collapsible >}}

{{< history >}}

  • Introduced in GitLab 18.5 with a flag named global_ai_catalog. Enabled on GitLab.com.
  • Enabling in groups introduced in GitLab 18.7 with a flag named ai_catalog_agents. Enabled on GitLab.com.
  • Changed to beta in GitLab 18.7.
  • Generally available in GitLab 18.8.
  • Feature flag ai_catalog_agents removed in GitLab 18.9.
  • Feature flag global_ai_catalog removed in 18.10.
  • 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.
  • 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, enable it and start using it with GitLab Duo Chat in the GitLab UI, VS Code, and JetBrains IDEs.

Prerequisites

Agent visibility

{{< history >}}

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

{{< /history >}}

When you create a custom 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.

You cannot make a public agent private if the agent is currently enabled.

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.
  2. Select Automate > Agents.
    • To view agents enabled 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

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.

  2. Select Automate > Agents.

  3. Select New agent.

  4. Under Basic information:

    1. In Display name, enter a name for the agent.
    2. In Description, enter a description for the agent.

  5. Under Visibility & access, for Visibility, select Private or Public.

  6. Under Prompts, in System prompt, enter a prompt to define the agent's personality, expertise, and behavior.

  7. 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 Web UI. For more information, see the list of agent tools.

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

  2. Select AI Catalog, then select the Agents tab.

  3. Select New agent.

  4. Under Basic information:

    1. In Display name, enter a name for the agent.
    2. In Description, enter a description for the agent.

  5. Under Visibility & access:

    1. From the Managed by dropdown list, select a project for the agent.
    2. For Visibility, select Private or Public.

  6. Under Prompts, in System prompt, enter a prompt to define the agent's personality, expertise, and behavior.

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

    For a list of available tools, see the built-in tool definitions.

  8. Select Create agent.

{{< /tab >}}

{{< /tabs >}}

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

Enable an agent

Enable an agent to use it with Chat.

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

{{< /tab >}}

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

To enable an 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. Select Enable.

{{< /tab >}}

{{< /tabs >}}

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

In the project, you can start a new chat with the agent. For more information, see select an agent.

Enable in a project

If an 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 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 agent you want to enable.
  5. Select Enable.

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

In the project, you can start a new chat with the agent.

Use an agent

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

In the GitLab UI

Prerequisites:

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

  2. Open an issue, epic, or merge request.

  3. On the GitLab Duo sidebar, select Add new chat ({{< icon name="pencil-square" >}}).

  4. From the dropdown list, select the custom agent.

    A Chat conversation opens in the GitLab Duo sidebar on the right side of your screen.

  5. Enter your question or request.

In VS Code

Prerequisites:

To use a custom agent in VS Code:

  1. In VS Code, in the left sidebar, select GitLab Duo Agent Platform ({{< icon name="duo-agentic-chat" >}}).
  2. Select the Chat tab.
  3. From the New chat ({{< icon name="duo-chat-new" >}}) dropdown list, select the custom agent.
  4. Enter your question or request.

In JetBrains IDEs

Prerequisites:

First, enable the GitLab Duo Agent Platform:

  1. In your JetBrains IDE, go to Settings > Tools > GitLab Duo.
  2. Under GitLab Duo Agent Platform, select the Enable GitLab Duo Agent Platform checkbox.
  3. 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" >}}).
  2. Select the Chat tab.
  3. From the New chat ({{< icon name="duo-chat-new" >}}) dropdown list, select the custom agent.
  4. Enter your question or request.

Disable an agent

Prerequisites:

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

To disable an agent:

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

The agent no longer appears in the project, and is not available in Chat.

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.
  2. Select AI Catalog, then select the Agents tab.
  3. Select the agent you want to duplicate.
  4. In the upper-right corner, select Actions ({{< icon name="ellipsis_v" >}}) > Duplicate.
  5. Optional. Edit any fields you want to change.
  6. 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.
  2. Select Automate > Agents.
  3. Select the agent you want to edit.
  4. In the upper-right corner, select Edit.
  5. 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 enable it. However, they can still interact with the agent in the groups and projects it is already enabled in.

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.
  2. Select Automate > Agents.
  3. Find the agent you want to hide and select Actions ({{< icon name="ellipsis_v" >}}) > Hide.
  4. In the confirmation dialog, select Confirm.

Delete an agent

Delete an agent to permanently remove it from the instance.

Prerequisites:

  • You must be an administrator.
  1. In the top bar, select Search or go to and find your group or project.
  2. Select Automate > Agents.
  3. Find the agent you want to delete and select Actions ({{< icon name="ellipsis_v" >}}) > Delete.
  4. In the confirmation dialog, select Delete.