gitlab Understanding agents: Foundational, custom, and external (opens in new tab)
The GitLab Duo Agent Platform provides a tiered framework for integrating AI into the software development lifecycle through foundational, custom, and external agents. By combining built-in expertise with the ability to define bespoke behaviors or connect to specialized external models, the platform enables teams to automate complex tasks ranging from product planning to runtime debugging. This structured approach ensures that AI assistance is deeply integrated into GitLab’s ecosystem while remaining flexible enough to meet specific organizational standards. ## Foundational Agents These are pre-configured, GitLab-maintained agents available immediately in the IDE or Web UI for general and specialized SDLC tasks. * **GitLab Duo:** The primary general-purpose partner for code modification, merge request management, and issue triaging within the full platform context. * **Planner Agent:** Specifically designed to assist with product management by breaking down epics into structured issues and generating acceptance criteria. * **Security Analyst Agent:** Focuses on triaging vulnerabilities, identifying false positives from scans, and prioritizing risks based on actual impact. * **Data Analyst Agent:** Leverages GitLab Query Language (GLQL) to visualize platform data, such as merge request trends, team workloads, and issue resolution times. ## Custom Agents Organizations can create specialized agents tailored to internal workflows by defining unique system prompts and visibility settings. * **Configuration and Control:** Custom agents are defined by a system prompt that dictates their persona and expertise—such as a DevOps agent that correlates static code data with CI/CD logs. * **Visibility Tiers:** Agents can be set to "Private" for use within a specific project or "Public" to be listed in the AI Catalog for broader organizational discovery. * **Operational Use Cases:** Common implementations include onboarding assistants for company-specific practices, compliance monitors for regulatory requirements, and localized support agents for non-English languages. * **Deployment Best Practices:** It is recommended to start with read-only permissions and highly specific constraints before granting agents write access to the repository or platform. ## External Agents External agents operate asynchronously and are triggered by mentions or assignments within issues and merge requests, rather than through interactive chat. * **Asynchronous Automation:** These agents, such as Anthropic Claude or OpenAI Codex, execute tasks in the background when triggered by commands like `@ai-codex`. * **Managed Credentials:** GitLab handles API key management and rotation for these integrations, simplifying the security overhead for teams using third-party models. * **Specialized Performance:** External agents allow teams to leverage provider-specific strengths, such as Claude’s code analysis or Codex’s task delegation, while maintaining compliance with specific data residency requirements. * **Integrated Review:** A typical workflow involves assigning an external agent as a reviewer on a merge request, where it automatically analyzes code quality and posts improvement suggestions directly as comments. To maximize the value of the platform, teams should begin by leveraging foundational agents for immediate productivity gains before developing custom agents that encode specific organizational knowledge. External agents should be reserved for specialized automation tasks or when specific third-party large language models (LLMs) are required for compliance or advanced code generation.