Understanding agents: Foundational, custom, and external

Welcome to Part 3 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 are agents?
• Types of agents
• Common use cases
• How to create a custom agent
• Best practices

🎯 Try GitLab Duo Agent Platform today!

What are agents?

Agents are specialized AI collaboration partners within GitLab Duo Agent Platform. Each agent type serves different purposes and runs in different contexts.

Types of agents

Foundational agents

Built and maintained by GitLab, these agents are available immediately with no setup required. The availability of foundational agents can be managed by namespace owners or instance administrators. Start the interaction with foundational agents by opening GitLab Duo Agentic Chat in the IDE or Web UI.

GitLab Duo

This is the default agent, your general-purpose development collaboration partner for creating and modifying code, opening merge requests, triaging and updating issues/epics, and running workflows with full SDLC platform context.

Example prompts:

• "Explain how the authentication system works."
• "Where is the user profile logic located?"
• "How should I implement feature X?"

Planner Agent

Helps with product planning, breaking down epics, and creating structured issues.

Example prompts:

• "Create an epic for the new payment system with subtasks."
• "Break down issue #789 into smaller tasks."
• "Generate acceptance criteria for this feature."

Learn more about Planner Agent.

Security Analyst Agent

Triages vulnerabilities, identifies false positives, and prioritizes security risks.

Example prompts:

• "Triage all vulnerabilities from the latest scan."
• "Which SAST findings are false positives?"
• "Prioritize security issues by actual risk"

Learn more about Security Analyst Agent.

Data Analyst Agent

Queries, visualizes, and surfaces data across the GitLab platform using GitLab Query Language (GLQL) to provide actionable insights about your projects and teams.

Example prompts:

• "How many merge requests were created in the last quarter?"
• "Show me what each team member has worked on this month."
• "What are the trends in issue resolution times?"
• "Find all open issues with the 'bug' label in my project."
• "Generate a GLQL query to count merge requests by author."

Learn more about Data Analyst Agent.

Custom agents

Create your own agents tailored to your team's specific workflows and standards.

Common use cases

• Troubleshooting and Debugging Agent: Debug software bugs and regressions, and analyze deployment failures.
• Documentation Agent: Maintain docs following your conventions.
• Onboarding Assistant: Help new team members with company-specific practices.
• Compliance Monitor: Ensure regulatory requirements are met.
• Localized Support Agent: Triage support issues in a localized language, for example, German.

Watch the GitLab DACH Roadshow Vienna 2025 Duo Agent Platform use cases talk recording:

🎯 Try it now: Interactive demo of Custom Agents — Explore how to create and configure custom agents.

How to create a custom agent

Custom agents are configured through your project or group settings. The key component is the system prompt, which defines your agent's behavior and expertise.

System Prompt Example from the custom agent devops-debug-failures-agent:

      Your speciality is that you can correlate static SDLC data with runtime data from CI/CD pipelines, logs, and other tool calls necessary.
Expect that the user has advanced knowledge, but always provide commands and steps to reproduce your analysis so they can learn from you.
Start with a short summary and suggested actions, and then go into detail with thoughts, analysis, suggestions.
Think creative and consider unknown unknowns in your debug journey.

    

Visibility options:

• Private: Only viewable by members of the managing project (Developer role+). Cannot be enabled in other projects.
• Public: Can be viewed by anyone and enabled in any project that meets the prerequisites. Appears in the AI Catalog for discovery.

Full setup guide available in the documentation.

Best practices

System prompt tips:

• Be specific about the agent's role and responsibilities.
• Define clear quality standards and constraints.
• Include examples of expected output.
• Keep prompts focused on one primary task.

Start small:

• Begin with read-only permissions.
• Test thoroughly before granting write access.
• Gather team feedback and iterate.

External agents

External agents run in the background on the GitLab platform when triggered by mentions (e.g., @ai-codex) or assignments in issues and merge requests. Unlike foundational and custom agents that work interactively in chat, external agents execute asynchronously, enabling powerful automation with specialized AI providers.

Credential management: Starting with GitLab Duo Agent Platform general availability, GitLab-managed credentials will be used to support external agents, preventing the need for customers to manage and rotate API keys themselves.

When to use external agents

• You need specific agentic AI behavior or LLMs for specialized tasks.
• You want event-triggered automation (not interactive chat).
• You need to meet specific compliance or data residency requirements.

Why use external agents?

• Leverage specialized AI models: Access provider-specific capabilities like Claude Code's code analysis or OpenAI Codex's task delegation.
• Meet compliance requirements: Keep data within approved AI providers for regulatory or security policies.
• Experiment with providers: Test different agentic AI and LLM behavior to find the best fit for your workflows.
• Access unique features: Use provider-specific tools like Claude Code's code analysis or OpenAI Codex's task delegation.

Real-world example

A development team uses OpenAI Codex as an external agent for code review. When developers create merge requests, they assign Codex as a reviewer. The agent:

1. Analyzes the code changes in the MR.
2. Checks for best practices and code quality issues.
3. Suggests improvements and optimizations.
4. Posts detailed review comments with specific recommendations.
5. Links to relevant documentation.

All of this happens automatically in the background while the developer continues working, with results posted directly in the merge request.

Supported external agents

The following integrations have been tested and are available:

• Anthropic Claude — Code generation, review, and analysis
• OpenAI Codex — GPT-powered code assistance

Example usage:

@ai-codex Please implement this issue

This triggers a runner execution job that runs the external AI tool and posts results back to GitLab.

Setting up external agents

For complete setup instructions including service accounts, triggers, and configuration examples, see the External Agents documentation.

Customizing agent behavior with AGENTS.md

Customize how agents using AGENTS.md files following the agents.md standard. Learn more in Part 8: Customizing GitLab Duo Agent Platform: Chat rules, prompts, and workflows.

Choosing the best agent type for your use cases

Summary

GitLab Duo Agent Platform offers these agent types:

• Foundational: Ready-to-use agents for common tasks (Chat, Planner, Security Analyst, Data Analyst)
• Custom: Create team-specific agents with custom prompts and behaviors
• External: Integrate external AI tools

Start with foundational agents, create custom agents for team-specific needs, and explore external agents when you need specialized AI providers.

Next: Part 4: Understanding flows

Previous: Part 2: GitLab Duo Agentic Chat