AI Catalog

The AI Catalog is a central list of agents and flows. Add these agents and flows to your project to get started orchestrating agentic AI tasks.

Use the AI Catalog to:

• Discover agents and flows created by the GitLab team and community members.
• Create custom agents and flows, and share them with other users.
• Enable agents and flows in your projects to use them across the GitLab Duo Agent Platform.

View the AI Catalog

Prerequisites:

• Meet the GitLab Duo Agent Platform prerequisites.
• Have the Agent Platform turned on.
• On GitLab Self-Managed, have GitLab Duo turned on for the instance.
• To enable agents and flows from the AI Catalog:
  • In a group, you must have the Maintainer or Owner role.
  • In a project, you must have the Maintainer or Owner role.

To view the AI Catalog, you can either:

• Use the top bar:
  1. In the top bar, select Search or go to > Explore.
  2. Select AI Catalog.
• Use the GitLab Duo sidebar:
  1. In the top bar, select Search or go to and find your project.
  2. On the GitLab Duo sidebar, select GitLab Duo AI Catalog ( ).

A list of agents is displayed.

On GitLab Self-Managed, the following agents are not displayed in the AI Catalog:

• Custom agents created on GitLab.com.
• GitLab-managed external agents that have not been added to the instance.

To view available flows, select the Flows tab.

Agent and flow versions

Each custom agent and flow in the AI Catalog maintains a version history. When you make changes to an item’s configuration, GitLab automatically creates a new version. Foundational agents and flows do not use versioning.

GitLab uses semantic versioning to indicate the scope of changes. For example, an agent can have a version number like 1.0.0 or 1.1.0. GitLab manages semantic versioning automatically. Updates to agents or flows always increment the minor version.

Versioning ensures that your projects and groups continue to use a stable, tested configuration of an agent or flow. This prevents unexpected changes from affecting your workflows.

Creating versions

GitLab creates a version when you:

• Update a custom agent’s system prompt.
• Modify an external agent or flow’s configuration.

To ensure consistent behavior, versions are immutable.

Version pinning

When you enable an AI Catalog item:

• In a group, GitLab pins the latest version.
• In a project that does not manage that item, GitLab pins the same version as the project’s top-level group.

Version pinning means:

• Your project or group uses a fixed version of the item.
• Updates to the agent or flow in the AI Catalog do not affect your configuration.
• You maintain control over when to adopt new versions.

This approach provides stability and predictability for your AI-powered workflows.

When you enable an AI Catalog item in the project that manages the item, GitLab does not pin a version. Instead, the manager project always uses the latest version of the item.

If you enabled an agent or flow in its manager project before GitLab 18.10, your configuration remains at the pinned version.

After you update to the latest version for the first time, GitLab automatically uses the latest version from then onwards.

View the current version

Prerequisites:

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

To view the current version of an agent or flow:

1. In the top bar, select Search or go to and find your project or group.
2. In the left sidebar, select either:
   • AI > Agents
   • AI > Flows
3. Select the agent or flow to view its details.

The details page displays:

• The pinned version your project or group is using.
• The version identifier. For example, 1.2.0.
• Details about that specific version’s configuration.

Update to the latest version

Prerequisites:

• You must have the Maintainer or Owner role.

To make your group or project use the latest version of an agent or flow:

1. In the top bar, select Search or go to and find your project or group.
2. In the left sidebar, select either:
   • AI > Agents
   • AI > Flows
3. Select the agent or flow you want to update.
4. Review the latest version carefully. To update, select View latest version > Update to <x.y.z>.

Configuration size limits

The configuration of an AI Catalog item cannot exceed a maximum size:

Flows and external agents have a lower limit. GitLab stores both the YAML you enter and the structured configuration that GitLab generates from it. Together, these are about twice the size of the YAML.

If your configuration exceeds the limit, GitLab displays an error and does not save the item. To resolve the error, reduce the size of your configuration.

Item visibility

When you create an agent or flow, you select a project to manage it and choose whether the item is public, private, or restricted. Visibility controls who can view, enable, and run the item. These rules apply to custom agents, external agents, and flows.

Public items

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

Private items

• 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 item private if the item has been turned on by a project other than the managing project.

Restricted items

• 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.
• Cannot be created from the AI Catalog in Explore.

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

Restricted items and shared projects or groups

GitLab lets you share a project or group into another project or group. The restricted visibility rules around enablement consider only the actual top-level group of the managing project. It does not consider shared project or group relationships.

A collaborator who gains access to a project or group through a share can view, enable, and run restricted items only while working inside that shared container. The share does not extend restricted access into the collaborator’s own top-level group.

Confine the AI Catalog to a group hierarchy

In a top-level group, you can confine the AI Catalog so that, for a project in that group hierarchy, users can see, enable, and run only:

• Foundational agents and flows maintained by GitLab.
• Public agents and flows owned by projects in the same top-level group hierarchy.
• Private agents and flows owned by the project itself.

Agents and flows owned by projects outside the hierarchy are:

• Hidden from the AI Catalog.
• Blocked from being enabled.
• Blocked from running, even if a project previously enabled them.

You can configure this setting only on a top-level group. It applies to all projects in that hierarchy. Changes to this setting are recorded in the audit log.

Prerequisites:

• You must have the Owner role for the top-level group.

To confine the AI Catalog to your group hierarchy:

1. In the top bar, select Search or go to and find your top-level group.
2. Select Settings > GitLab Duo.
3. Select Change configuration.
4. In the Data and privacy section, under AI Catalog, select the Confine the AI Catalog to this group checkbox.
5. Select Save changes.

Related topics

• Agents
• External agents