agents
GitLab Duo Agent Platform - AI Agent Development and Orchestration
Overview
The GitLab Duo Agent Platform is a comprehensive framework for building, deploying, and orchestrating AI agents across the software development lifecycle. It reaches General Availability in January 2026 (GitLab 18.8).
Global Launch Event: February 10, 2026 - GitLab as the intelligent orchestration platform for software teams and AI agents.
Platform Architecture
Core Concepts
Agent Platform Components:
- Agents: Specialized AI workers focused on specific tasks
- Flows: YAML-defined workflows orchestrating multiple agents
- Tools: Functions agents can use to interact with GitLab and external systems
- Context: Full project context from GitLab's DevSecOps platform
- Orchestrator: Manages agent execution and coordination
Key Benefits
- Multi-Agent Parallelism: Multiple agents work simultaneously
- Full Context Awareness: Access to code, issues, MRs, CI/CD, security scans
- Governed AI: Centralized control and compliance
- Asynchronous Collaboration: Human-AI teamwork
- Dynamic Workflows: Linear processes become parallel operations
Agent Types
1. Foundational Agents
Built-in agents provided by GitLab.
Software Developer Agent
Purpose: Generate and modify code based on requirements.
Capabilities:
- Analyze issue requirements
- Generate implementation code
- Create necessary files and folders
- Follow coding standards
- Apply design patterns
Example Usage:
- agent: software_developer action: implement_feature inputs: - issue_description - architecture_guide outputs: - code_changes
Security Analyst Agent
Purpose: Review code for security vulnerabilities.
Capabilities:
- Identify security issues
- Analyze attack vectors
- Suggest remediation
- Check compliance requirements
- Validate security patterns
Example Usage:
- agent: security_analyst action: security_review inputs: - code_changes - security_policies outputs: - security_report - remediation_suggestions
Deep Research Agent
Purpose: Analyze project history and documentation.
Capabilities:
- Search codebase
- Analyze git history
- Review documentation
- Find similar implementations
- Identify patterns and anti-patterns
Example Usage:
- agent: deep_research action: analyze_history inputs: - search_query - time_range outputs: - research_findings - related_issues
Test Generator Agent
Purpose: Create comprehensive test suites.
Capabilities:
- Generate unit tests
- Create integration tests
- Produce test data
- Calculate coverage
- Identify edge cases
Example Usage:
- agent: test_generator action: generate_tests inputs: - implementation_code - test_framework outputs: - test_suite - coverage_report
Planner Agent
Purpose: Break down work and create implementation plans.
Capabilities:
- Analyze requirements
- Break down epics
- Estimate effort
- Identify dependencies
- Create task lists
Status: Beta (create and edit features)
Example Usage:
- agent: planner action: create_plan inputs: - issue_description - constraints outputs: - implementation_plan - task_breakdown
Code Reviewer Agent
Purpose: Automated code review feedback.
Capabilities:
- Identify bugs
- Check best practices
- Suggest improvements
- Verify coding standards
- Review complexity
Example Usage:
- agent: code_reviewer action: review_mr inputs: - merge_request - coding_standards outputs: - review_comments - approval_status
2. Custom Agents
Create specialized agents for your team's needs.
Creating Custom Agents
Via GitLab UI:
1. Navigate to Group Settings
2. GitLab Duo † Agents
3. Click "Create Agent"
4. Configure agent:
- Name and description
- System prompt (personality and expertise)
- Available tools
- Model selection
Agent Configuration:
# .gitlab/agents/code_quality_agent.yml name: code_quality_checker description: Reviews code for quality and maintainability model: claude-sonnet-4 system_prompt: | You are a code quality expert focused on maintainability, readability, and best practices. Review code changes and provide constructive feedback on: - Code complexity - Naming conventions - Documentation completeness - DRY principles - SOLID principles - Test coverage - Performance considerations Be specific and provide examples in your feedback. tools: - read_file - list_files - create_issue - add_comment - run_analysis settings: max_file_size: 10000 languages: - python - javascript - typescript excludes: - "*.test.js" - "vendor/**"
Custom Agent Examples
Documentation Agent:
name: documentation_specialist description: Generates and maintains project documentation system_prompt: | You are a technical writer specializing in developer documentation. Create clear, comprehensive documentation that includes: - API references - Code examples - Architecture diagrams - Getting started guides - Troubleshooting tips tools: - read_file - write_file - analyze_code - generate_diagram outputs: - markdown_docs - api_specs - diagrams
Performance Optimization Agent:
name: performance_optimizer description: Identifies and resolves performance bottlenecks system_prompt: | You are a performance optimization specialist. Analyze code for performance issues including: - Inefficient algorithms (O(n²) vs O(n log n)) - Unnecessary database queries (N+1 problems) - Memory leaks - Blocking operations - Large bundle sizes Suggest specific optimizations with before/after examples. tools: - read_file - run_profiler - analyze_queries - check_bundle_size metrics: - execution_time - memory_usage - query_count
Migration Agent:
name: framework_migration description: Assists with framework and library migrations system_prompt: | You help migrate code between frameworks and libraries. Current expertise: - React class components † Hooks - JavaScript † TypeScript - REST † GraphQL - Jest † Vitest Provide step-by-step migration plans and handle edge cases. tools: - read_file - write_file - run_codemod - validate_syntax settings: preserve_functionality: true add_type_safety: true maintain_tests: true
3. External Agents
Integrate AI providers outside GitLab.
Supported Providers
Anthropic Claude:
external_agent: name: claude_integration provider: anthropic model: claude-sonnet-4 authentication: type: api_key key_source: gitlab_managed # or user_provided configuration: temperature: 0.7 max_tokens: 4096 top_p: 0.9
OpenAI GPT:
external_agent: name: gpt_integration provider: openai model: gpt-4 authentication: type: api_key key_source: user_provided key_variable: OPENAI_API_KEY configuration: temperature: 0.8 max_tokens: 8192
Mistral:
external_agent: name: mistral_integration provider: mistral model: mistral-large authentication: type: api_key key_source: gitlab_managed configuration: temperature: 0.7 max_tokens: 32000
AI Gateway
Use GitLab-managed credentials instead of managing API keys:
Benefits:
- No key rotation required
- Centralized billing
- Usage tracking
- Rate limiting
- Security controls
Configuration:
external_agent: name: claude_via_gateway provider: anthropic authentication: type: gitlab_managed gateway: https://duo-gateway.gitlab.com monitoring: track_usage: true alert_on_limit: 80%
Flows - Agent Workflows
Pre-Built Flows
1. Software Development Flow
Status: Beta Purpose: End-to-end feature implementation
Workflow:
- Planner Agent analyzes issue
- Developer Agent generates code
- Test Generator creates tests
- Security Analyst scans for vulnerabilities
- Reviewer Agent performs code review
- Creates merge request
Configuration:
# .gitlab/duo_flows/software_development.yml flow: name: software_development description: Complete feature implementation from issue to MR version: 1.0 trigger: type: issue_label value: ai-implement agents: - planner - software_developer - test_generator - security_analyst - code_reviewer steps: - name: analyze_requirements agent: planner action: analyze_issue inputs: - issue_description: $ISSUE_BODY - architecture_docs: docs/ARCHITECTURE.md outputs: - implementation_plan - name: implement_feature agent: software_developer action: generate_code inputs: - plan: $steps.analyze_requirements.implementation_plan - coding_standards: .gitlab/standards.md outputs: - code_changes parallel: false - name: generate_tests agent: test_generator action: create_tests inputs: - code: $steps.implement_feature.code_changes - framework: pytest outputs: - test_suite - name: security_scan agent: security_analyst action: scan_code inputs: - code: $steps.implement_feature.code_changes outputs: - security_report - name: review_code agent: code_reviewer action: review inputs: - code: $steps.implement_feature.code_changes - tests: $steps.generate_tests.test_suite - security: $steps.security_scan.security_report outputs: - review_feedback - name: create_merge_request action: create_mr inputs: - branch: $ISSUE_IID-$ISSUE_SLUG - code: $steps.implement_feature.code_changes - tests: $steps.generate_tests.test_suite - description: | Auto-generated by GitLab Duo Software Development Flow ## Implementation $steps.implement_feature.summary ## Testing $steps.generate_tests.coverage ## Security $steps.security_scan.findings ## Review $steps.review_code.summary error_handling: on_failure: - create_issue_comment - notify_assignee
2. Issue-to-MR Flow
Purpose: Convert issues to merge requests automatically
Workflow:
- Analyze issue requirements
- Generate implementation plan
- Create code changes
- Generate tests
- Create MR with description
Configuration:
# .gitlab/duo_flows/issue_to_mr.yml flow: name: issue_to_mr description: Automatically create MR from issue trigger: type: issue_label value: auto-mr steps: - agent: planner action: analyze_and_plan - agent: software_developer action: implement_plan - agent: test_generator action: generate_tests - action: create_mr auto_assign: true notify_team: true
3. Convert CI File Flow
Purpose: Migrate CI/CD configs to GitLab CI format
Supported Sources:
- Jenkins (Jenkinsfile)
- GitHub Actions
- CircleCI
- Travis CI
- Azure Pipelines
Workflow:
- Parse source CI configuration
- Map to GitLab CI concepts
- Generate .gitlab-ci.yml
- Validate pipeline syntax
- Create MR with converted file
Configuration:
# .gitlab/duo_flows/convert_ci.yml flow: name: convert_ci_file description: Convert external CI configs to GitLab CI trigger: type: manual parameters: - name: source_platform type: enum values: [jenkins, github_actions, circleci, travis, azure] - name: config_file type: file steps: - agent: ci_converter action: parse_config inputs: - platform: $params.source_platform - config: $params.config_file - agent: ci_converter action: map_to_gitlab inputs: - parsed_config: $previous.output - agent: ci_converter action: optimize_pipeline inputs: - gitlab_config: $previous.output - action: validate_ci inputs: - config: $previous.output - action: create_mr inputs: - files: - path: .gitlab-ci.yml content: $previous.output
Custom Flows
Example: Bug Fix Flow
# .gitlab/duo_flows/bug_fix.yml flow: name: automated_bug_fix description: Investigate and fix bugs automatically trigger: type: issue_label value: bug-auto-fix agents: - deep_research - software_developer - test_generator steps: - name: research_bug agent: deep_research action: investigate_issue inputs: - issue: $ISSUE_BODY - search_logs: true - check_history: true outputs: - root_cause - related_issues - name: propose_fix agent: software_developer action: generate_fix inputs: - root_cause: $steps.research_bug.root_cause - affected_files: $steps.research_bug.files outputs: - fix_code - explanation - name: create_tests agent: test_generator action: generate_regression_tests inputs: - bug_description: $ISSUE_BODY - fix_code: $steps.propose_fix.fix_code outputs: - regression_tests - name: verify_fix action: run_tests inputs: - tests: $steps.create_tests.regression_tests - name: create_fix_mr condition: $steps.verify_fix.passed == true action: create_mr inputs: - title: "Fix: $ISSUE_TITLE" - description: | Auto-fix for $ISSUE_REF ## Root Cause $steps.research_bug.root_cause ## Solution $steps.propose_fix.explanation ## Testing Added regression tests to prevent recurrence - labels: [bug-fix, ai-generated] - closes: $ISSUE_REF notifications: on_success: - notify_assignee - add_issue_comment: "Auto-fix MR created: $MR_URL" on_failure: - add_issue_comment: "Auto-fix failed: $ERROR_MESSAGE"
Example: Code Review Flow
# .gitlab/duo_flows/comprehensive_review.yml flow: name: comprehensive_code_review description: Multi-agent code review process trigger: type: merge_request conditions: - draft: false - label: needs-ai-review agents: - code_reviewer - security_analyst - performance_optimizer - documentation_specialist steps: - name: parallel_reviews parallel: true steps: - agent: code_reviewer action: review_quality outputs: - quality_feedback - agent: security_analyst action: security_review outputs: - security_issues - agent: performance_optimizer action: performance_analysis outputs: - perf_suggestions - agent: documentation_specialist action: check_documentation outputs: - docs_review - name: synthesize_feedback agent: code_reviewer action: synthesize_reviews inputs: - quality: $steps.parallel_reviews.quality_feedback - security: $steps.parallel_reviews.security_issues - performance: $steps.parallel_reviews.perf_suggestions - docs: $steps.parallel_reviews.docs_review - name: post_review action: add_mr_comment inputs: - comment: $steps.synthesize_feedback.output - resolve_threads: false - name: assess_approval agent: code_reviewer action: recommend_approval outputs: - should_approve - name: auto_approve condition: $steps.assess_approval.should_approve == true action: approve_mr comment: "AI review passed - approved automatically"
Agent Tools
Built-in Tools
Agents can use these tools to interact with GitLab:
File Operations
# Read file read_file(path: str) -> str # Write file write_file(path: str, content: str) -> bool # List files list_files(path: str, pattern: str) -> List[str] # Delete file delete_file(path: str) -> bool
Issue Operations
# Create issue create_issue( title: str, description: str, labels: List[str], assignee: str ) -> Issue # Update issue update_issue( issue_id: int, title: str = None, description: str = None, state: str = None ) -> Issue # Add comment add_issue_comment( issue_id: int, comment: str ) -> Comment
MR Operations
# Create MR create_merge_request( source_branch: str, target_branch: str, title: str, description: str ) -> MergeRequest # Add MR comment add_mr_comment( mr_id: int, comment: str, position: Position = None ) -> Comment # Approve MR approve_mr(mr_id: int) -> bool
CI/CD Operations
# Run pipeline run_pipeline(ref: str) -> Pipeline # Get job logs get_job_logs(job_id: int) -> str # Retry pipeline retry_pipeline(pipeline_id: int) -> Pipeline
Analysis Tools
# Run SAST scan run_sast_scan() -> ScanResults # Check code quality check_code_quality(files: List[str]) -> QualityReport # Analyze performance analyze_performance(profiling_data: str) -> PerformanceReport
Custom Tools
Create custom tools for agents:
# .gitlab/agents/tools/custom_linter.py from gitlab_duo.tools import Tool, ToolParameter class CustomLinter(Tool): """Custom linting tool for project-specific rules""" name = "custom_lint" description = "Run project-specific linting rules" parameters = [ ToolParameter( name="files", type="array", description="Files to lint" ), ToolParameter( name="rules", type="string", description="Rule set to apply", enum=["strict", "relaxed", "security"] ) ] def execute(self, files: List[str], rules: str) -> dict: """Execute custom linting""" results = [] for file in files: violations = self.check_file(file, rules) results.append({ "file": file, "violations": violations }) return { "total_files": len(files), "total_violations": sum(len(r["violations"]) for r in results), "results": results } def check_file(self, file: str, rules: str) -> List[dict]: """Check individual file""" # Custom linting logic pass
Model Context Protocol (MCP)
The Agent Platform supports MCP for connecting to external systems.
MCP Integration
Connect to External Services:
# .gitlab/agents/mcp_config.yml mcp_servers: - name: jira url: https://jira.company.com protocol: mcp authentication: type: oauth2 client_id: $JIRA_CLIENT_ID client_secret: $JIRA_CLIENT_SECRET - name: slack url: https://slack.company.com protocol: mcp authentication: type: token token: $SLACK_BOT_TOKEN - name: database url: postgres://db.company.com protocol: mcp authentication: type: password username: $DB_USER password: $DB_PASS
Use in Agent:
agent: name: jira_sync_agent tools: - gitlab_issues - mcp:jira actions: - sync_to_jira: mcp_server: jira action: create_ticket mapping: title: $gitlab_issue.title description: $gitlab_issue.description priority: $gitlab_issue.weight
AI Catalog
Central library for sharing agents across organization.
Publishing Agents
# Publish to AI Catalog agent: name: sql_security_scanner description: Scans code for SQL injection vulnerabilities version: 1.2.0 author: security-team publish: catalog: true visibility: organization # or group, project category: security tags: - security - sql - sast
Using Catalog Agents
# Use agent from catalog flow: agents: - catalog:sql_security_scanner@1.2.0 steps: - agent: sql_security_scanner action: scan_code
Catalog Search
# Search AI Catalog gitlab-duo catalog search "security" # Results: # - sql_security_scanner (1.2.0) # - xss_detector (2.0.1) # - secrets_finder (1.5.3)
Monitoring and Analytics
Agent Performance
Track agent execution:
Agent Analytics Dashboard
Software Developer Agent:
- Executions: 156
- Success rate: 94%
- Avg duration: 3.2 minutes
- Code quality: 8.5/10
Security Analyst Agent:
- Executions: 203
- Success rate: 98%
- Avg duration: 1.8 minutes
- Issues found: 45 (12 critical)
Test Generator Agent:
- Executions: 178
- Success rate: 91%
- Avg duration: 2.5 minutes
- Coverage achieved: 87%
Flow Analytics
Software Development Flow
Completed: 42
Success rate: 88%
Avg duration: 12 minutes
Stage Breakdown:
- Planning: 2 min
- Implementation: 5 min
- Testing: 3 min
- Security: 1 min
- Review: 1 min
Common Failures:
- Test generation: 8 failures
- Security scan: 3 failures
Cost Tracking
AI Usage Report (January 2026)
By Agent:
- Software Developer: $234 (2.4M tokens)
- Security Analyst: $156 (1.6M tokens)
- Test Generator: $189 (1.9M tokens)
By Flow:
- Software Development: $412
- Issue-to-MR: $89
- Bug Fix: $78
By Model:
- Claude Sonnet 4: $456
- GPT-4: $123
- Mistral Large: $67
Total: $646
Best Practices
1. Start with Pre-Built Flows
Use provided flows before building custom:
# Start simple flow: software_development # Customize later flow: extends: software_development modifications: - add_step: custom_validation
2. Use Specific System Prompts
# Generic (less effective) system_prompt: "You are a helpful coding assistant" # Specific (more effective) system_prompt: | You are a Python backend developer specializing in FastAPI. Follow these standards: - Use type hints - Write docstrings (Google style) - Use async/await for I/O - Implement dependency injection - Add comprehensive error handling
3. Provide Context
agent: name: feature_developer context: - architecture: docs/ARCHITECTURE.md - standards: .gitlab/STANDARDS.md - examples: examples/
4. Incremental Adoption
Start with non-critical work:
trigger: type: issue_label value: ai-experiment # Test on experimental issues first
5. Human Review
Always require human approval:
flow: steps: - agent: software_developer - action: create_mr auto_approve: false # Require human review
Troubleshooting
Agent Not Responding
Check:
- Agent configuration valid
- Model provider accessible
- API quotas not exceeded
- Network connectivity
Flow Failing
Debug:
flow: debug: true # Enable verbose logging error_handling: on_failure: - capture_logs - create_debug_issue
Poor Agent Output
Improve:
- Refine system prompt
- Add more context
- Provide examples
- Adjust temperature
- Try different model
Security Considerations
Agent Permissions
agent: name: restricted_agent permissions: files: read: ["src/**"] write: [] # No write access issues: create: false comment: true mrs: create: false comment: true
Audit Logging
All agent actions are logged:
Audit Log:
- 2026-01-08 14:23: software_developer read file src/auth.py
- 2026-01-08 14:24: software_developer wrote file src/auth_new.py
- 2026-01-08 14:25: security_analyst scanned src/
- 2026-01-08 14:26: code_reviewer created MR comment
Data Privacy
agent: privacy: pii_detection: true redact_secrets: true data_retention: 30_days
Resources
Next Steps
- API - Integrate agents via API
- Best Practices - Advanced agent patterns