agents

GitLab Duo Agent Platform - Agents

Overview

Agents are AI-powered entities that perform specialized tasks autonomously within the GitLab Duo Agent Platform. They have domain expertise, access to tools, and the ability to make decisions based on context from the Knowledge Graph and project data.

Types: Foundational (GitLab-provided), Custom (user-created), External (third-party integrations) Execution: Via flows, Chat interface, or direct API calls Context: Full access to GitLab data via APIs and Knowledge Graph

Agent Architecture

Core Components


‚                        AGENT                             ‚

‚                                                          ‚
‚    ‚
‚  ‚            System Prompt (Identity)               ‚  ‚
‚  ‚   Role definition                                ‚  ‚
‚  ‚   Capabilities and constraints                   ‚  ‚
‚  ‚   Behavioral guidelines                          ‚  ‚
‚  ˜  ‚
‚                          †                               ‚
‚    ‚
‚  ‚              AI Model (Brain)                     ‚  ‚
‚  ‚   LLM (Claude, GPT-4, etc.)                     ‚  ‚
‚  ‚   Reasoning and decision-making                 ‚  ‚
‚  ‚   Natural language understanding                ‚  ‚
‚  ˜  ‚
‚                          †                               ‚
‚    ‚
‚  ‚              Tools (Hands)                        ‚  ‚
‚  ‚   GitLab API access                             ‚  ‚
‚  ‚   Knowledge Graph queries                       ‚  ‚
‚  ‚   CI/CD interactions                            ‚  ‚
‚  ‚   External system integrations                  ‚  ‚
‚  ˜  ‚
‚                          †                               ‚
‚    ‚
‚  ‚              Context (Memory)                     ‚  ‚
‚  ‚   Current session state                         ‚  ‚
‚  ‚   Previous step results                         ‚  ‚
‚  ‚   Project/MR/Issue data                        ‚  ‚
‚  ‚   Knowledge Graph snapshot                      ‚  ‚
‚  ˜  ‚
‚                                                          ‚
˜

Foundational Agents

GitLab provides production-ready agents for common workflows. All foundational agents are enabled by default in GitLab Duo.

1. Chat Agent (@duo-developer)

Purpose: General-purpose development assistance via natural language

Capabilities:

Code generation and modification
Debugging assistance
Test writing
Documentation creation
Refactoring suggestions
Architecture guidance

Tools:

GitLab API (full access within permissions)
Knowledge Graph queries
Code analysis
File operations
Git operations

Usage:

# In Chat interface
"Generate unit tests for the UserAuth class"

"Explain what this code does"

"Refactor this function to use async/await"

"What are the dependencies of module X?"

Example System Prompt (simplified):

You are @duo-developer, a software development assistant integrated into GitLab.

Your role:
- Help developers write, understand, and improve code
- Provide context-aware suggestions using the Knowledge Graph
- Follow the project's coding standards and patterns
- Generate tests alongside implementation code
- Keep documentation up to date

Your capabilities:
- Read and write code in the repository
- Query the Knowledge Graph for code relationships
- Create and update issues and merge requests
- Run CI/CD pipelines
- Access project documentation

Guidelines:
- Always explain your reasoning
- Provide code examples with explanations
- Suggest tests for new code
- Reference related code via Knowledge Graph
- Follow existing patterns in the codebase

2. Security Analyst Agent

Purpose: Automated vulnerability analysis, triage, and security workflow management

Capabilities:

Vulnerability scanning and analysis
Risk assessment with business context
Exploitability evaluation (EPSS, CVSS, reachability)
Remediation recommendations
Security report generation
Compliance checking

Domain Knowledge:

GitLab security scanner outputs
CVE database and EPSS scores
OWASP Top 10 and security best practices
Reachability analysis patterns
Security states and severity levels

Tools:

Security Dashboard API
Dependency scanning results
SAST/DAST/Secret detection outputs
CVE and EPSS databases
Code reachability analysis

Usage:

# In vulnerability issue or MR
"@security-analyst analyze this vulnerability"

"What's the exploitability risk of CVE-2024-1234?"

"Prioritize these vulnerabilities by business impact"

"Generate a security report for this sprint"

Risk Assessment Process:

1. Retrieve vulnerability data
   †
2. Analyze technical severity (CVSS)
   †
3. Check exploitability probability (EPSS)
   †
4. Perform reachability analysis
   †
5. Evaluate business context
   †
6. Calculate risk score
   †
7. Recommend priority and remediation

Example Output:

## Vulnerability Analysis: CVE-2024-5678

**Severity**: High (CVSS 8.1)
**Exploitability**: 15.3% (EPSS)
**Reachability**:  Reachable

### Risk Assessment
This vulnerability is in the `jsonwebtoken` package used in our authentication
module. The vulnerable code path is REACHABLE from our login endpoint.

### Business Impact
- Direct exposure: Public-facing authentication API
- Potential impact: Unauthorized access to user accounts
- Affected users: All users (approximately 10,000)

### Priority:  CRITICAL

### Recommended Actions
1. Update `jsonwebtoken` to version 9.0.2 or higher (immediate)
2. Implement additional token validation (short-term mitigation)
3. Audit all JWT usage patterns (follow-up task)

### Remediation Steps
```bash
npm install jsonwebtoken@9.0.2
npm test

Would you like me to create an MR with the package update?


### 3. Code Review Agent

**Purpose**: Automated code review with contextual analysis

**Capabilities:**
- Static code analysis
- Code quality assessment
- Bug detection
- Performance issue identification
- Security pattern checking
- Style and convention enforcement
- Test coverage analysis
- Documentation review

**Context Awareness:**
- Cross-file dependencies via Knowledge Graph
- Project coding standards
- Historical patterns and conventions
- Related issues and previous discussions
- Test coverage data

**Tools:**
- Merge request API
- Knowledge Graph queries
- Code analysis engines
- Test coverage reports
- CI/CD pipeline results

**Usage:**

In MR comment

"@duo-developer please review"

Or assign as reviewer


**Review Process:**

Load MR diff and context †
Query Knowledge Graph for affected code †
Analyze changes: Code quality (complexity, duplication) Potential bugs (null refs, race conditions) Performance (N+1 queries, inefficient algorithms) Security (injection, XSS, auth issues) Style (conventions, naming, formatting) †
Check test coverage †
Review documentation updates †
Generate review comments †
Post inline comments with suggestions †
Provide overall assessment and approval recommendation


**Example Review Comment:**

Code Review Feedback

Issues Found

Potential Bug (Line 45)

const user = users.find(u => u.id === id);
return user.name; //  Potential null reference

Issue: users.find() can return undefined if no user is found.

Suggestion:

const user = users.find(u => u.id === id);
if (!user) {
  throw new UserNotFoundError(id);
}
return user.name;

Performance Concern (Line 78)

for (const item of items) {
  await database.save(item); //  N+1 query pattern
}

Issue: Saving items one by one causes N database round-trips.

Suggestion: Use batch insert:

await database.batchSave(items);

Test Coverage

Unit tests added Integration test missing for error case

Documentation

Function documentation updated API documentation needs update in docs/api.md

Overall Assessment

Changes look good with the issues above addressed. The refactoring improves maintainability. Please fix the null reference bug before merging.

Recommendation: ‘ Request changes


### 4. Planning Agent (Planner)

**Purpose**: Project planning, workload balancing, and task management

**Capabilities:**
- Requirement analysis and breakdown
- Effort estimation
- Task prioritization
- Workload distribution
- Milestone tracking
- Progress reporting
- Sprint planning support

**Domain Knowledge:**
- Agile methodologies (Scrum, Kanban)
- Estimation techniques (story points, t-shirt sizing)
- Dependency management
- Team capacity planning
- GitLab issue/epic hierarchies

**Tools:**
- Issues API
- Epics API
- Milestones API
- Labels API
- Board management
- Time tracking

**Usage:**

In issue

"@planner break down this epic into tasks"

"@planner estimate effort for this feature"

"@planner suggest priority for these issues"


**Example Interaction:**

User: "@planner break down the user authentication epic into implementation tasks"

Planner Agent:

Epic Breakdown: User Authentication

Based on the epic description and project architecture, here's the breakdown:

Tasks

1. Backend Authentication Service

Epic: User Authentication Estimate: 8 story points (5 days) Priority: High Dependencies: None

Tasks:

Design authentication schema
Implement JWT token generation
Create login endpoint
Create logout endpoint
Add password hashing
Write unit tests
Write integration tests

Epic: User Authentication Estimate: 5 story points (3 days) Priority: High Dependencies: #1 (Backend Authentication Service)

Tasks:

Create login form component
Add form validation
Implement authentication flow
Add error handling
Write component tests
Update routing

3. Session Management

Epic: User Authentication Estimate: 5 story points (3 days) Priority: Medium Dependencies: #1 (Backend Authentication Service)

Tasks:

Implement session storage
Add token refresh logic
Create session timeout handling
Add remember-me functionality
Write tests

Summary

Total Estimate: 18 story points (~11 days)
Critical Path: Backend † Frontend † Session Management
Suggested Sprint: Can fit in a 2-week sprint with 1 developer

Would you like me to create these issues and link them to the epic?


### 5. Deep Research Agent

**Purpose**: Comprehensive project analysis using Knowledge Graph

**Capabilities:**
- Codebase exploration
- Dependency analysis
- Impact assessment
- Architecture understanding
- Pattern identification
- Technical debt analysis

**Special Feature**: Leverages Knowledge Graph for deep semantic understanding

**Tools:**
- Knowledge Graph (full access)
- Code search
- Git history analysis
- Documentation parsing

**Usage:**

"@deep-research analyze the impact of removing the UserService class"

"@deep-research find all code paths that call the authentication module"

"@deep-research what are the dependencies of the payment processing system?"


### 6. Product Planning Agent

**Purpose**: Product backlog management and work item assignment

**Capabilities:**
- Backlog prioritization
- Work assignment (to humans and agents)
- Timeline forecasting
- Resource allocation
- Progress tracking

**Tools:**
- Product planning APIs
- Team management APIs
- Capacity planning tools

**Usage:**

"@product-planner prioritize the backlog for next quarter"

"@product-planner assign these tasks to the team"

"@product-planner when can we ship feature X?"


## Agent Governance (GitLab 18.7+)

### Controlling Agent Availability

Administrators can control which foundational agents are available:

**Instance Level (Self-managed):**
```bash
# Disable all agents by default
glab admin agent-platform config set --all-agents disabled

# Enable specific agents
glab admin agent-platform config enable security_analyst_agent
glab admin agent-platform config enable code_review_agent

Group Level:

# Configure for a group
glab api groups/:group_id/duo/agent_config \
  --method PATCH \
  --data '{
    "security_analyst_agent": {"enabled": true},
    "code_review_agent": {"enabled": true},
    "planning_agent": {"enabled": false}
  }'

Policy-Based Control:

# .gitlab/duo/agent_policy.yml
agent_availability:
  # Allow these agents
  allow:
    - security_analyst_agent
    - code_review_agent

  # Block these agents
  block:
    - product_planning_agent  # Internal planning only

  # Require approval for these
  require_approval:
    - deep_research_agent  # Expensive operations

conditions:
  # Only in certain projects
  projects:
    - namespace: "production/*"
      agents: ["security_analyst_agent"]

  # Only for certain roles
  roles:
    maintainer: ["*"]  # All agents
    developer: ["code_review_agent", "chat_agent"]
    guest: []  # No agents

Custom Agents

Creating a Custom Agent

name: custom-compliance-agent
description: Company-specific compliance checking agent
version: 1.0.0

metadata:
  author: Compliance Team
  category: security
  tags:
    - compliance
    - sox
    - gdpr

agent:
  type: custom

  # Model configuration
  model:
    provider: anthropic
    name: claude-3-opus
    temperature: 0.2  # Lower for consistency
    max_tokens: 4096

  # System prompt defines agent behavior
  system_prompt: |
    You are a compliance specialist for Acme Corporation.

    Your role:
    - Verify SOX compliance requirements in code changes
    - Check GDPR data handling patterns
    - Validate audit logging implementation
    - Ensure data retention policies are followed

    Your expertise:
    - SOX section 404 requirements
    - GDPR Articles 17 (right to erasure) and 25 (data protection by design)
    - Company data classification policies
    - Audit logging standards (NIST SP 800-53 AU family)

    Your guidelines:
    - Every database change must have audit logging
    - PII must be encrypted at rest and in transit
    - Data deletion must honor retention periods
    - Changes to financial systems require dual approval

    When reviewing code:
    1. Identify compliance-sensitive changes
    2. Check for required controls
    3. Validate against company policies
    4. Provide specific remediation steps
    5. Reference relevant standards (SOX, GDPR, internal policies)

  # Tools the agent can use
  tools:
    - name: gitlab_api
      description: Access GitLab APIs
      permissions:
        - read_code
        - read_issues
        - write_comments
        - update_labels

    - name: knowledge_graph
      description: Query code relationships
      permissions:
        - query
        - analyze

    - name: compliance_database
      description: Query compliance requirements database
      endpoint: https://compliance.acme.com/api
      auth:
        type: oidc
        audience: compliance-api

    - name: audit_log_checker
      description: Verify audit logging implementation
      script: |
        #!/usr/bin/env node
        // Custom tool implementation
        const { checkAuditLogs } = require('./compliance-tools');
        module.exports = checkAuditLogs;

  # Actions the agent can perform
  actions:
    - name: check_compliance
      description: Check code changes for compliance issues
      inputs:
        - name: merge_request_iid
          type: number
          required: true
        - name: compliance_frameworks
          type: array
          required: false
          default: ["sox", "gdpr"]

    - name: generate_compliance_report
      description: Generate compliance assessment report
      inputs:
        - name: project_id
          type: number
        - name: time_range
          type: string
          default: "30d"

    - name: validate_data_handling
      description: Validate PII data handling patterns
      inputs:
        - name: file_path
          type: string

  # Resource limits
  limits:
    max_execution_time: 10m
    max_api_calls: 500
    max_tokens_per_request: 100000

  # Monitoring
  monitoring:
    track_usage: true
    alert_on_error: true
    log_level: info

Deploying Custom Agents

# Validate agent definition
glab duo agent validate custom-compliance-agent.yml

# Test agent locally
glab duo agent test custom-compliance-agent.yml \
  --action check_compliance \
  --input '{"merge_request_iid": 42}'

# Deploy to group
glab duo agent deploy custom-compliance-agent.yml \
  --group :group_id

# Enable agent
glab duo agent enable custom-compliance-agent \
  --group :group_id

Custom Agent Example: Deployment Validator

name: deployment-validator
description: Validates deployments meet production readiness criteria

agent:
  system_prompt: |
    You validate that deployments meet production readiness criteria.

    Required checks:
    - All tests passing (unit, integration, e2e)
    - Security scan passed with no high/critical issues
    - Performance benchmarks within thresholds
    - Documentation updated
    - Changelog entry added
    - Database migrations reviewed
    - Feature flags configured
    - Monitoring alerts configured
    - Rollback plan documented

    For each check:
    -  if passed
    -  if failed (block deployment)
    -  if warning (human review required)

  tools:
    - gitlab_api
    - ci_pipeline_api
    - monitoring_api

  actions:
    - name: validate_deployment
      description: Run all production readiness checks
      inputs:
        - name: merge_request_iid
          type: number
        - name: target_environment
          type: string
          enum: ["staging", "production"]

      implementation: |
        async function validateDeployment(context, inputs) {
          const mr = await context.gitlab.getMergeRequest(
            inputs.merge_request_iid
          );

          const checks = {
            tests: await checkTests(mr),
            security: await checkSecurity(mr),
            performance: await checkPerformance(mr),
            documentation: await checkDocumentation(mr),
            changelog: await checkChangelog(mr),
            migrations: await checkMigrations(mr),
            featureFlags: await checkFeatureFlags(mr),
            monitoring: await checkMonitoring(mr),
            rollbackPlan: await checkRollbackPlan(mr)
          };

          const passed = Object.values(checks).every(c => c.passed);
          const warnings = Object.values(checks).filter(c => c.warning);

          return {
            passed,
            checks,
            decision: passed ? "approve" : "block",
            warnings: warnings.length,
            requiresHumanReview: warnings.length > 0
          };
        }

External Agents

External agents integrate GitLab with third-party AI systems.

Creating an External Agent

name: external-copilot-integration
description: Integrate GitHub Copilot for code suggestions
type: external

external:
  provider:
    name: github-copilot
    endpoint: https://copilot-proxy.example.com/api
    authentication:
      type: api_key
      secret: gitlab-secret-key-ref

  capabilities:
    - code_completion
    - code_explanation
    - code_refactoring

  mapping:
    # Map GitLab events to external agent actions
    merge_request.opened:
      action: analyze_changes
      params:
        context: full_mr_diff

    comment.created:
      action: respond_to_query
      params:
        context: comment_and_mr

  service_account:
    # Automatically creates service account with Developer role
    auto_create: true
    username: external-copilot-agent

Agent Lifecycle Management

Agent States

Draft † Testing † Published † Active † Deprecated † Archived

Transitions:
- draft † testing: Run validation tests
- testing † published: Pass all tests, get approval
- published † active: Enable in production
- active † deprecated: Mark as superseded, set sunset date
- deprecated † archived: Disable and archive

Version Management

name: code-review-agent
version: 2.0.0

versioning:
  strategy: semantic  # semantic | date-based
  auto_upgrade: false  # Require explicit upgrade

  compatibility:
    min_gitlab_version: "18.7"
    max_gitlab_version: "19.*"

  deprecation:
    version: "1.5.0"
    sunset_date: "2026-06-01"
    replacement: "code-review-agent:2.0.0"
    migration_guide: "docs/migration-v2.md"

Agent Updates

# Check for updates
glab duo agent updates

# Update agent to latest version
glab duo agent upgrade code-review-agent --version latest

# Update with automatic approval
glab duo agent upgrade code-review-agent --auto-approve

# Rollback to previous version
glab duo agent rollback code-review-agent --version 1.9.0

Agent Observability

Session Tracking

View agent sessions:

# List recent sessions
glab duo agent sessions --agent security-analyst-agent --limit 10

# View specific session
glab duo agent session show session-abc123

# Session details
glab api duo/sessions/session-abc123

Session Data:

{
  "session_id": "session-abc123",
  "agent": "security-analyst-agent",
  "flow": "security-triage-flow",
  "triggered_by": "john.doe",
  "context": {
    "project_id": 12345,
    "merge_request_iid": 42
  },
  "steps": [
    {
      "step": "scan_vulnerabilities",
      "duration_ms": 12453,
      "status": "success",
      "tokens_used": 15234,
      "cost_usd": 0.15
    }
  ],
  "total_duration_ms": 45231,
  "total_tokens": 62341,
  "total_cost_usd": 0.62,
  "status": "completed"
}

Metrics

Key agent metrics:

# Usage metrics
agent_executions_total{agent="security-analyst", status="success"} 1523
agent_executions_total{agent="security-analyst", status="failure"} 42

# Performance metrics
agent_duration_seconds{agent="security-analyst", quantile="0.5"} 15.3
agent_duration_seconds{agent="security-analyst", quantile="0.95"} 45.8

# Cost metrics
agent_tokens_consumed_total{agent="security-analyst", model="claude-3-opus"} 1523456
agent_cost_usd_total{agent="security-analyst"} 152.34

# Quality metrics
agent_user_satisfaction{agent="security-analyst"} 4.5  # 1-5 scale
agent_correction_rate{agent="security-analyst"} 0.08  # 8% of outputs corrected by humans

Agent Security

Permissions Model

agent:
  name: security-analyst-agent

  permissions:
    gitlab:
      # Read permissions
      read:
        - code
        - issues
        - merge_requests
        - security_reports
        - ci_pipelines

      # Write permissions
      write:
        - comments
        - labels
        - merge_request_status

      # Forbidden (even if service account has access)
      forbidden:
        - merge
        - delete
        - project_settings
        - group_settings

    knowledge_graph:
      - query
      - analyze

    external_apis:
      - name: compliance_api
        methods: ["GET", "POST"]
        endpoints: ["/check", "/validate"]

  rate_limits:
    api_calls: 1000/hour
    knowledge_graph_queries: 500/hour
    token_usage: 1000000/day

Audit Logging

All agent actions are logged:

{
  "timestamp": "2026-01-08T10:15:30Z",
  "agent": "security-analyst-agent",
  "action": "post_comment",
  "context": {
    "project_id": 12345,
    "merge_request_iid": 42,
    "comment_id": 98765
  },
  "user": "john.doe",
  "service_account": "ai-security-platform",
  "composite_identity": true,
  "permissions_checked": [
    "can_write_comments",
    "can_access_security_reports"
  ],
  "result": "success"
}

Best Practices

1. Design Focused Agents

#  Good: Focused agent
name: api-documentation-agent
description: Generates and maintains API documentation
# Specialized for one domain

#  Bad: Unfocused agent
name: do-everything-agent
description: Does code review, security, docs, and deployments
# Too many responsibilities

2. Provide Clear System Prompts

system_prompt: |
  You are a security specialist.

  #  Clear role and boundaries
  Your role: Identify security vulnerabilities in code changes
  Your constraints: You cannot approve or merge changes, only review
  Your expertise: OWASP Top 10, secure coding practices, CVE database

  #  Specific guidelines
  When reviewing:
  1. Focus on security, not style or performance
  2. Explain WHY something is a security issue
  3. Provide remediation steps
  4. Reference relevant standards (OWASP, CWE)

  #  Example outputs
  Format your findings as:
  **Severity**: Critical/High/Medium/Low
  **Issue**: [description]
  **Risk**: [what could happen]
  **Fix**: [how to remediate]

3. Implement Resource Limits

agent:
  limits:
    max_execution_time: 5m  # Prevent runaway agents
    max_api_calls: 500      # Prevent API abuse
    max_tokens: 100000      # Control costs
    max_retries: 3          # Limit retry attempts

4. Monitor and Alert

monitoring:
  track_usage: true
  track_cost: true
  track_performance: true

  alerts:
    - condition: error_rate > 0.05
      action: notify_team
      channel: "#agent-platform-alerts"

    - condition: p95_duration > 60s
      action: notify_team

    - condition: daily_cost > 100 USD
      action: notify_and_throttle

5. Test Thoroughly

# Unit test agent logic
npm test agents/security-analyst

# Integration test with mock data
glab duo agent test security-analyst-agent \
  --mock-context test/fixtures/mr-context.json

# Canary deployment
glab duo agent deploy security-analyst-agent \
  --canary \
  --traffic-percentage 10

Next Steps

CI/CD Integration: Read integration.md for pipeline patterns
Best Practices: Study best-practices.md for production deployment

Last Updated: January 2026 GitLab Version: 18.7 (Beta), 18.8 GA (Upcoming)

agents

GitLab Duo Agent Platform - Agents

Overview

Agent Architecture

Core Components

Foundational Agents

1. Chat Agent (@duo-developer)

2. Security Analyst Agent

In MR comment

Or assign as reviewer

Issues Found

Potential Bug (Line 45)

Performance Concern (Line 78)

Test Coverage

Documentation

Overall Assessment

In issue

Epic Breakdown: User Authentication

Tasks

1. Backend Authentication Service

2. Frontend Login UI

3. Session Management

Summary

Custom Agents

Creating a Custom Agent

Deploying Custom Agents

Custom Agent Example: Deployment Validator

External Agents

Creating an External Agent

Agent Lifecycle Management

Agent States

Version Management

Agent Updates

Agent Observability

Session Tracking

Metrics

Agent Security

Permissions Model

Audit Logging

Best Practices

1. Design Focused Agents

2. Provide Clear System Prompts

3. Implement Resource Limits

4. Monitor and Alert

5. Test Thoroughly

Next Steps