AI Catalog: Discover, create, and share agents and flows

Welcome to Part 5 of our eight-part guide, Getting started with GitLab Duo Agent Platform, where you'll master building and deploying AI agents and workflows within your development lifecycle. Follow tutorials that take you from your first interaction to production-ready automation workflows with full customization.

In this article:

• What is the AI Catalog?
• Browsing and enabling agents and flows
• Creating, sharing, and managing visibility
• Understanding versioning

🎯 Try GitLab Duo Agent Platform today!

Introduction to the AI Catalog

The AI Catalog is a central repository for discovering, creating, and sharing agents and flows across your organization. It promotes consistency, reusability, and collaboration by enabling teams to leverage pre-built solutions and best practices.

What you can do:

• Discover: Browse agents and flows created by GitLab and the community.
• Create: Create and maintain custom agents and flows in a single interface.
• Enable: Enable agents and flows at your top-level group level, then use them in your projects.
• Share: Publish your agents and flows for others to use (Public or Private).
• Duplicate: Copy and customize existing agents and flows.

Accessing and working with the AI Catalog

Navigate to Explore → AI Catalog.

The catalog currently provides two types:

• Agents — Custom agents for on-demand, interactive, or context-specific tasks.
• Flows — Custom flows for repeatable, multi-step automations, orchestrating a team of agents.

For detailed information, see the AI Catalog documentation.

Discover agents and flows

The AI Catalog makes it easy to find agents and flows that fit your needs:

How to browse:

1. Navigate to Explore → AI Catalog.
2. Select either Agents or Flows tab.
3. Browse the available agents or flows and inspect title, description and visibility status.
4. Click on any agent or flow to view more details.

Enabling agents and flows:

Once you find an agent or flow you want to use:

1. Click the agent or flow to view details.
2. Click the Enable in group button to add the agent or flow to your top-level group.
3. Enable it in your project to start using it.

Creating, sharing, and managing visibility

Create agents and flows

Here are step-by-step instructions for creating agents and flows.

Create agents:

Navigate to Explore → AI Catalog → Agents → New agent.

1. Brainstorm and define a specific task or specialization for this agent, for example, a debugging and troubleshooting agent.
2. Add a display name and description to allow others to identify the purpose and why they would want to use the agent, for example troubleshoot-debugger.
3. Specify visibility and access. Select a private project and set visibility to private to start with experiments.
4. Define the agent behavior, capabilities, and specialization in the system prompt. For details on crafting effective system prompts, see Part 3: Understanding agents.
5. Optionally select and limit the tool access for agents. For example, a debugging agent needs read access to code, issues, and merge requests, but may not require write access to make changes.

Create flows:

Navigate to Explore → AI Catalog → Flows → New flow.

1. Brainstorm and define a complex multi-step specific task, for example, a CI/CD pipeline optimizer flow.
2. Add a display name and description to allow others to identify the purpose and why they would want to use the flow, for example ci-cd-optimizer.
3. Specify visibility and access. Select a private project and set visibility to private to start with experiments.
4. Define the flow behavior and its agent components, prompts, and routers. For details on flow YAML structure, see Part 4: Understanding flows.

For more details, see:

• Custom Agents documentation
• Custom Flows documentation

Share your work and set visibility

When creating agents or flows, you can choose between Private and Public visibility to control who can access and use them.

Private:

• Can be viewed only by members of the managing project who have at least the Developer role, or by users with the Owner role for the top-level group.
• Cannot be enabled in other projects.
• Useful for team-specific or sensitive workflows.

Public:

• Viewable by anyone on the instance.
• Can be enabled in any project that meets prerequisites.
• Appears in AI Catalog for discovery.

Best practices for sharing

When publishing agents and flows to the AI Catalog, follow these guidelines:

Naming:

• Use clear, descriptive names (e.g., security-code-review, api-documentation-generator).
• Avoid generic names like agent1 or my-flow.
• Include the purpose in the name when possible.

Documentation:

• Provide a clear description of what the agent or flow does.
• Include use cases and examples.
• Document any prerequisites or dependencies.

Quality:

• Test thoroughly before publishing.
• Ensure the agent or flow solves a real problem.
• Keep it maintainable and well-documented.
• Consider edge cases and error handling.

Visibility decisions:

• Start with Private to test with your team.
• Move to Public once validated and documented.
• Only publish if it provides value to others.
• Consider the audience and use cases.

Understanding versioning

Custom agents and flows in the AI Catalog maintain a version history to track changes.

How versioning works:

• GitLab automatically creates a new version when you update an agent's system prompt or modify a flow's configuration.
• Versions use semantic versioning (e.g., 1.0.0, 1.1.0).
• GitLab manages semantic versioning automatically — updates always increment the minor version.
• Versions are immutable, ensuring consistent behavior.

Version pinning:

When you enable an agent or flow:

• In a group: GitLab pins it to the latest version.
• In a project: GitLab pins it to the same version as your top-level group.

This means:

• Your projects use a fixed, stable version of the agent or flow.
• Updates in the AI Catalog don't automatically affect your configuration.
• You must opt-in to update to new versions — updates are never automatic.
• You maintain full control over when to adopt new versions.

Viewing versions:

• Navigate to Automate → Agents or Automate → Flows.
• Select the agent or flow to view its version on the right side in the About section.

Updating to the latest version

When a new version of an agent or flow is available in the AI Catalog, you can update your projects to use it.

1. Navigate to Automate → Agents or Automate → Flows.
2. Click the agent or flow you want to update.
3. Click the Update button (appears when a newer version is available).
4. Review the changes in the new version.
5. Confirm the update to pin your project to the latest version.

What's next?

You now understand how to discover, create, and share agents and flows through the AI Catalog. Next, in Part 6, learn how to monitor agent and flow activity through sessions, set up event-driven triggers, and manage your AI workflows.

Resources

• AI Catalog documentation
• Custom Agents documentation
• Custom Flows documentation

Next: Part 6: Monitor, manage, and automate AI workflows

Previous: Part 4: Understanding flows