architecture
GitLab Duo Agent Platform - Architecture
Overview
The GitLab Duo Agent Platform is built on a layered architecture that integrates AI orchestration throughout the GitLab stack. This document provides a comprehensive technical view of the platform's components, communication patterns, and infrastructure.
Architectural Layers
The platform architecture consists of three primary layers:
‚ LAYER 3: AI ORCHESTRATION ‚
‚ ‚
‚ ‚ AI Gateway ‚ ‚ Duo Workflow ‚ ‚ GitLab ‚ ‚
‚ ‚ ‚‚ Service ‚‚ Runner ‚ ‚
‚ ‚ (Routing) ‚ ‚(Orchestration‚ ‚ (Execution) ‚ ‚
‚ ˜ ˜ ˜ ‚
˜
‚ LAYER 2: KNOWLEDGE & CONTEXT ‚
‚ ‚
‚ ‚ GitLab Knowledge Graph ‚ ‚
‚ ‚ ‚ ‚
‚ ‚ Semantic code search and entity recognition ‚ ‚
‚ ‚ Structural elements (files, classes, functions) ‚ ‚
‚ ‚ Code relationships (calls, inheritance, dependencies) ‚ ‚
‚ ‚ Model Context Protocol (MCP) integration ‚ ‚
‚ ‚ Live embeddable graph database ‚ ‚
‚ ˜ ‚
˜
‚ LAYER 1: CORE PLATFORM ‚
‚ ‚
‚ ‚ GitLab Rails (Core Features) ‚ ‚
‚ ‚ ‚ ‚
‚ ‚ Issues, Epics, Merge Requests ‚ ‚
‚ ‚ CI/CD Pipelines ‚ ‚
‚ ‚ Security Scanning (SAST, DAST, Dependency, Secret) ‚ ‚
‚ ‚ Container Registry ‚ ‚
‚ ‚ Wiki, Snippets, Projects, Groups ‚ ‚
‚ ‚ Authentication & Authorization ‚ ‚
‚ ˜ ‚
˜
Core Components
1. AI Gateway
Purpose: Routes and processes AI requests between GitLab and AI model providers.
Responsibilities:
- Request routing to appropriate AI models
- Load balancing across model providers
- Rate limiting and quota management
- API key and credential management
- Response caching and optimization
- Telemetry and usage tracking
Architecture:
‚ GitLab UI ‚
‚ / API ‚
˜
‚
¼
‚ AI Gateway ‚
‚ ‚
‚ ‚
‚ ‚ Request Router ‚ ‚
‚ ‚ Model selection ‚ ‚
‚ ‚ Load balancing ‚ ‚
‚ ‚ Failover ‚ ‚
‚ ˜ ‚
‚ ‚
‚ ‚
‚ ‚ Response Processor ‚ ‚
‚ ‚ Caching ‚ ‚
‚ ‚ Validation ‚ ‚
‚ ‚ Formatting ‚ ‚
‚ ˜ ‚
‚ ‚
‚ ‚
‚ ‚ Telemetry Collector ‚ ‚
‚ ‚ Usage metrics ‚ ‚
‚ ‚ Performance data ‚ ‚
‚ ‚ Error tracking ‚ ‚
‚ ˜ ‚
˜
‚
¼
‚ AI Providers ‚
‚ ‚
‚ OpenAI ‚
‚ Anthropic ‚
‚ Custom Models ‚
˜
Configuration:
- Separate model selection for Agentic Chat vs. other agents (GitLab 18.7+)
- Instance-level or group-level model configuration
- Fallback model chains for reliability
- Model-specific rate limits and quotas
2. Duo Workflow Service
Purpose: Orchestrates AI-assisted workflows and manages agent execution.
Responsibilities:
- Flow definition parsing and validation
- Agent lifecycle management
- Step-by-step execution orchestration
- Context management across agents
- State management for long-running workflows
- Error handling and retry logic
- Session tracking and logging
Workflow Execution Flow:
‚ Duo Workflow Service ‚
‚ ‚
‚ 1. Trigger Event Received ‚
‚ † ‚
‚ 2. Flow Definition Loaded ‚
‚ † ‚
‚ 3. Service Account Validated ‚
‚ † ‚
‚ 4. Context Gathered (Knowledge Graph, Issues, MRs) ‚
‚ † ‚
‚ 5. Agent Instantiated ‚
‚ † ‚
‚ 6. Action Executed ‚
‚ † ‚
‚ 7. Results Validated ‚
‚ † ‚
‚ 8. Next Step or Complete ‚
‚ † ‚
‚ 9. Session Logged ‚
‚ ‚
˜
State Management:
session: id: session-abc123 flow_id: code-review-flow trigger: mention service_account: ai-code-review-platform status: in_progress started_at: 2026-01-08T10:00:00Z context: project_id: 12345 merge_request_iid: 42 user_id: 67890 knowledge_graph_snapshot: kg-snapshot-xyz steps: - step_id: 1 agent: code_review_agent action: analyze_changes status: completed started_at: 2026-01-08T10:00:01Z completed_at: 2026-01-08T10:00:15Z result: files_analyzed: 12 issues_found: 3 - step_id: 2 agent: code_review_agent action: post_review_comments status: in_progress started_at: 2026-01-08T10:00:16Z
3. GitLab Runner
Purpose: Executes workflow jobs in isolated Docker containers.
Key Features:
- Runs flow steps in CI/CD pipelines when triggered from UI
- Provides isolated execution environments
- Manages resource allocation and limits
- Handles secrets and credential injection
- Collects logs and artifacts
Runner Configuration for Agent Workflows:
# .gitlab-ci.yml for agent-driven workflows agent_workflow: image: gitlab/agent-runner:latest variables: AGENT_PLATFORM_ENABLED: "true" KNOWLEDGE_GRAPH_ENABLED: "true" id_tokens: GITLAB_OIDC_TOKEN: aud: https://gitlab.com script: - duo-workflow-executor run --flow-id=$FLOW_ID --session-id=$SESSION_ID artifacts: reports: agent_session: session-log.json
4. GitLab Knowledge Graph
Purpose: Provides semantic understanding of codebases for AI agents.
Core Capabilities:
Entity Recognition
Entities Captured:
Structural Elements
‚ Files
‚ Directories
‚ Classes
‚ Functions
‚ Modules
‚ Interfaces
‚
Code Relationships
Function Calls
Inheritance Hierarchies
Module Dependencies
Import/Export Graphs
Data Flow Patterns
Architecture:
‚ GitLab Knowledge Graph ‚
‚ ‚
‚ ‚
‚ ‚ Parser Layer ‚ ‚
‚ ‚ Language-specific parsers (Tree-sitter) ‚ ‚
‚ ‚ Semantic analysis ‚ ‚
‚ ‚ Symbol extraction ‚ ‚
‚ ˜ ‚
‚ † ‚
‚ ‚
‚ ‚ Graph Database (Neo4j-like) ‚ ‚
‚ ‚ Nodes: Entities (files, classes, functions) ‚ ‚
‚ ‚ Edges: Relationships (calls, imports, inherits)‚ ‚
‚ ‚ Properties: Metadata (types, docs, metrics) ‚ ‚
‚ ˜ ‚
‚ † ‚
‚ ‚
‚ ‚ Embedding & Vector Store ‚ ‚
‚ ‚ Code embeddings for semantic search ‚ ‚
‚ ‚ Context retrieval for agents ‚ ‚
‚ ‚ Similarity matching ‚ ‚
‚ ˜ ‚
‚ † ‚
‚ ‚
‚ ‚ Query Interface ‚ ‚
‚ ‚ MCP server implementation ‚ ‚
‚ ‚ GraphQL API ‚ ‚
‚ ‚ Cypher-like query language ‚ ‚
‚ ˜ ‚
˜
Model Context Protocol (MCP) Integration
The Knowledge Graph connects via MCP to enable:
- Local Repository Parsing: Analyzes project structure on developer machines
- Remote Query Execution: Agents query knowledge graph from CI/CD pipelines
- Cross-Project Context: Understand dependencies across multiple projects
- Real-time Updates: Graph updates as code changes
MCP Server Configuration:
{ "mcpServers": { "gitlab-knowledge-graph": { "command": "gitlab-kg-mcp-server", "args": ["--project-id", "12345"], "env": { "GITLAB_TOKEN": "${GITLAB_API_TOKEN}", "GITLAB_URL": "https://gitlab.com" } } } }
5. GitLab Rails (Core Platform)
The existing GitLab Rails application provides:
- Data Models: Issues, MRs, Projects, Users, Groups
- API Endpoints: REST and GraphQL APIs for agent interactions
- Authentication: OAuth, OIDC, PATs, Deploy Tokens
- Authorization: Project permissions, group roles, feature flags
- CI/CD Engine: Pipeline execution, job scheduling, artifact storage
- Security Scanning: SAST, DAST, Dependency Scanning, Secret Detection
AI Feature Integration Points:
# Example: Agent API integration in Rails module Duo module AgentPlatform class FlowExecutor def initialize(flow:, trigger:, user:, service_account:) @flow = flow @trigger = trigger @user = user @service_account = service_account @knowledge_graph = KnowledgeGraph.for_project(@flow.project) end def execute session = create_session @flow.steps.each do |step| agent = instantiate_agent(step.agent_type) context = build_context(step) result = agent.execute_action( action: step.action, context: context, session: session ) session.add_step_result(step, result) break if step.terminal? || result.error? end session.complete! session end private def build_context(step) { project: @flow.project, knowledge_graph: @knowledge_graph.snapshot, merge_request: @trigger.merge_request, user: @user, service_account: @service_account, previous_results: session.results } end end end end
Communication Patterns
Agent-to-GitLab Communication
‚ Agent ‚ ‚ GitLab ‚
˜ ‚ API ‚
‚ ˜
‚ ‚
‚ 1. Query Knowledge Graph ‚
>‚
‚ 2. Return semantic context ‚
‚<
‚ ‚
‚ 3. Get MR details ‚
>‚
‚ 4. Return MR data ‚
‚<
‚ ‚
‚ 5. Perform analysis ‚
‚ (internal processing) ‚
‚ ‚
‚ 6. Post review comment ‚
>‚
‚ 7. Confirm posted ‚
‚<
‚ ‚
‚ 8. Update MR labels ‚
>‚
‚ 9. Confirm updated ‚
‚<
Multi-Agent Orchestration
‚ Security ‚ ‚ Code ‚ ‚ Planning ‚
‚ Agent ‚ ‚ Agent ‚ ‚ Agent ‚
˜ ˜ ˜
‚ ‚ ‚
‚ Parallel Execution ‚ ‚
¼
‚ ‚ ‚
¼ ¼ ¼
‚ Duo Workflow Service ‚
‚ ‚
‚ Context Sharing: ‚
‚ Shared Knowledge Graph snapshot ‚
‚ Common MR/Issue context ‚
‚ Inter-agent result passing ‚
‚ Conflict resolution ‚
‚ ‚
‚ Coordination: ‚
‚ Step dependencies ‚
‚ Conditional execution ‚
‚ Rollback on failure ‚
‚ Progress tracking ‚
˜
External System Integration (via MCP)
‚ GitLab Agent Platform ‚
˜
‚
‚ MCP Protocol
‚
¼
‚ ‚ ‚ ‚
¼ ¼ ¼ ¼
‚ Jira ‚ ‚ServiceNow ‚ ‚ ZenDesk ‚ ‚ Custom ‚
‚ MCP ‚ ‚ MCP ‚ ‚ MCP ‚ ‚ MCP ‚
‚ Server ‚ ‚ Server ‚ ‚ Server ‚ ‚ Server ‚
˜ ˜ ˜ ˜
Authentication & Authorization
Service Account Model
‚ Composite Identity ‚
‚ ‚
‚ ‚
‚ ‚ Human User ‚ + ‚ Service Account ‚ ‚
‚ ‚ ‚ ‚ ‚ ‚
‚ ‚ Role: Developer ‚ ‚ @duo-developer ‚ ‚
‚ ‚ Permissions: ‚ ‚ or ‚ ‚
‚ ‚ Read code ‚ ‚ @ai-<flow>-<grp> ‚ ‚
‚ ‚ Write comments ‚ ‚ ‚ ‚
‚ ‚ Create MRs ‚ ‚ Role: Developer ‚ ‚
‚ ˜ ‚ Permissions: ‚ ‚
‚ ‚ Limited scope ‚ ‚
‚ ‚ Audit logged ‚ ‚
‚ ˜ ‚
‚ ‚
‚ Effective Permissions = INTERSECTION of both accounts ‚
‚ ‚
‚ Security Boundary: ‚
‚ Agent cannot escalate beyond user permissions ‚
‚ All actions attributed to both identities ‚
‚ Audit trail maintained for compliance ‚
˜
OIDC Integration for CI/CD
# Agent workflow with OIDC authentication agent_deploy: id_tokens: AGENT_TOKEN: aud: https://agent-platform.gitlab.com AWS_TOKEN: aud: https://aws.amazon.com script: # Authenticate agent - duo-agent auth --token $AGENT_TOKEN # Agent can now assume AWS role - aws sts assume-role-with-web-identity \ --role-arn $AWS_ROLE_ARN \ --web-identity-token $AWS_TOKEN \ --role-session-name agent-session # Perform agent-driven deployment - duo-agent deploy --flow security-validated-deployment
Benefits:
- No long-lived credentials stored in GitLab
- Temporary tokens with precise expiration
- Granular permissions per agent and flow
- Full audit trail of token usage
Permission Model
Group/Project Permissions:
Guest (10)
‚ Cannot use agents
Reporter (20)
‚ View agent sessions
Developer (30)
‚ Trigger foundational flows
‚ Use Chat agent
‚ View custom flows
Maintainer (40)
‚ Create custom flows
‚ Configure external agents
‚ Manage service accounts
Owner (50)
All Maintainer permissions
Configure group-level agents
Set agent governance policies
Scalability & Performance
Horizontal Scaling
‚ Load Balancer ‚
˜
‚
¼
‚ ‚ ‚ ‚
¼ ¼ ¼ ¼
‚ AI Gateway ‚ ‚ AI Gateway ‚ ‚ AI Gateway ‚ ‚ AI Gateway ‚
‚ Instance 1 ‚ ‚ Instance 2 ‚ ‚ Instance 3 ‚ ‚ Instance N ‚
˜ ˜ ˜ ˜
‚ ‚ ‚ ‚
¼˜
‚
¼
‚ Duo Workflow Service Pool ‚
‚ (Auto-scaling based on load) ‚
˜
‚
¼
‚ GitLab Runner Fleet ‚
‚ (Elastic compute for workflows) ‚
˜
Caching Strategy
‚ Cache Layers ‚
‚ ‚
‚ L1: Request Cache (1 minute TTL) ‚
‚ AI Gateway responses ‚
‚ Model outputs for identical prompts ‚
‚ ‚
‚ L2: Knowledge Graph Cache (5 minutes TTL) ‚
‚ Entity relationships ‚
‚ Code embeddings ‚
‚ Semantic search results ‚
‚ ‚
‚ L3: Session Cache (1 hour TTL) ‚
‚ Flow execution context ‚
‚ Agent intermediate results ‚
‚ MR/Issue snapshots ‚
‚ ‚
‚ L4: Persistent Cache (24 hours TTL) ‚
‚ Project structure analysis ‚
‚ Dependency graphs ‚
‚ Historical agent learnings ‚
˜
Resource Limits
agent_resource_limits: per_flow: max_duration: 30m max_steps: 50 max_api_calls: 1000 max_memory: 2GB per_agent: max_concurrent_actions: 5 max_context_size: 128000 # tokens max_output_size: 32000 # tokens rate_limit: 100 # calls per minute per_session: max_agents: 10 max_parallel_agents: 3 session_timeout: 1h
Observability & Monitoring
Session Tracking
# Session log structure session: id: session-abc123 flow_name: code-review-flow project_id: 12345 merge_request_iid: 42 user: john.doe service_account: ai-code-review-platform timeline: created_at: 2026-01-08T10:00:00Z started_at: 2026-01-08T10:00:01Z completed_at: 2026-01-08T10:02:30Z duration_seconds: 149 metrics: steps_executed: 4 api_calls: 15 tokens_consumed: 45231 cost_usd: 0.23 steps: - step: analyze_changes agent: code_review_agent duration_seconds: 12 tokens: 15000 status: success - step: check_standards agent: code_review_agent duration_seconds: 8 tokens: 8500 status: success - step: post_comments agent: code_review_agent duration_seconds: 3 tokens: 1200 status: success audit_trail: - timestamp: 2026-01-08T10:00:01Z action: flow_started actor: service_account - timestamp: 2026-01-08T10:00:05Z action: knowledge_graph_query query: "get_related_files(src/auth.ts)" - timestamp: 2026-01-08T10:00:25Z action: mr_comment_posted comment_id: 98765
Metrics Collection
Key metrics exposed via Prometheus:
# Agent Platform Metrics
agent_platform_flow_executions_total{flow="code-review",status="success"} 1523
agent_platform_flow_executions_total{flow="code-review",status="failure"} 42
agent_platform_flow_duration_seconds{flow="code-review",quantile="0.5"} 15.3
agent_platform_flow_duration_seconds{flow="code-review",quantile="0.95"} 45.8
agent_platform_agent_actions_total{agent="security_analyst",action="scan"} 8921
agent_platform_agent_errors_total{agent="security_analyst",error="timeout"} 12
agent_platform_tokens_consumed_total{model="claude-3-opus"} 15234567
agent_platform_api_calls_total{endpoint="knowledge_graph"} 45123
agent_platform_cache_hit_ratio{cache="l1"} 0.85
agent_platform_cache_hit_ratio{cache="knowledge_graph"} 0.72
Logging Architecture
‚ Structured Logging ‚
‚ ‚
‚ Agent Platform Components ‚
‚ AI Gateway † logs/ai-gateway/*.json ‚
‚ Duo Workflow Service † logs/workflow/*.json ‚
‚ GitLab Runner † logs/runner/*.json ‚
‚ ‚
‚ Log Aggregation: ‚
‚ ClickHouse for queryable log storage ‚
‚ Grafana Loki for log exploration ‚
‚ Elastic for full-text search ‚
‚ ‚
‚ Query Example: ‚
‚ SELECT session_id, flow_name, duration_seconds ‚
‚ FROM agent_sessions ‚
‚ WHERE status = 'failed' ‚
‚ AND created_at > now() - interval 1 hour ‚
‚ ORDER BY duration_seconds DESC ‚
˜
Security Architecture
Threat Model
Threats Addressed:
Unauthorized Agent Access
‚ Mitigation: Composite identity, permission checks
Credential Exposure
‚ Mitigation: OIDC tokens, no long-lived secrets
Agent Prompt Injection
‚ Mitigation: Input validation, sandboxed execution
Data Exfiltration
‚ Mitigation: Rate limits, audit logging, output validation
Resource Exhaustion
‚ Mitigation: Resource limits, timeouts, circuit breakers
Supply Chain Attacks
Mitigation: Signed flows, verified agents, MCP allowlists
Sandboxing
‚ Agent Execution Sandbox ‚
‚ ‚
‚ ‚
‚ ‚ Docker Container (Agent Runtime) ‚ ‚
‚ ‚ ‚ ‚
‚ ‚ Read-only filesystem (except /tmp) ‚ ‚
‚ ‚ No network access (except allowlisted) ‚ ‚
‚ ‚ CPU limit: 2 cores ‚ ‚
‚ ‚ Memory limit: 2GB ‚ ‚
‚ ‚ Execution timeout: 30 minutes ‚ ‚
‚ ‚ ‚ ‚
‚ ‚ Allowlisted Network Access: ‚ ‚
‚ ‚ GitLab API (gitlab.com) ‚ ‚
‚ ‚ AI Gateway (internal) ‚ ‚
‚ ‚ Knowledge Graph (internal) ‚ ‚
‚ ‚ MCP Servers (configured) ‚ ‚
‚ ‚ ‚ ‚
‚ ‚ Environment Variables: ‚ ‚
‚ ‚ AGENT_TOKEN (OIDC, 1 hour TTL) ‚ ‚
‚ ‚ SESSION_ID ‚ ‚
‚ ‚ PROJECT_ID ‚ ‚
‚ ‚ (No secrets, no PATs) ‚ ‚
‚ ˜ ‚
˜
Deployment Models
SaaS (GitLab.com)
GitLab-managed Agent Platform:
Multi-tenant architecture
Shared AI Gateway and Workflow Service
Dedicated Knowledge Graphs per project
Elastic runner pools
Automatic updates with each GitLab release
Self-Managed (On-Premise)
Customer-managed Agent Platform:
Dedicated AI Gateway instance
Private Duo Workflow Service
Local Knowledge Graph deployment
Customer-provided runners
Manual updates (follows GitLab version)
Requirements:
GitLab Ultimate license
Minimum 16GB RAM for Knowledge Graph
GPU recommended for embeddings (optional)
Outbound HTTPS to AI model providers
(or use air-gapped models)
Hybrid Model
Hybrid deployment:
GitLab.com for version control and CI/CD
Self-managed AI Gateway (for compliance)
Private MCP servers (internal tools)
Public foundational agents
Custom agents (deployed internally)
Extension Points
Custom Agent Development
# Example custom agent implementation from gitlab.agent_platform import Agent, Action, Tool class CustomSecurityAgent(Agent): """Custom security agent for proprietary scanning.""" name = "custom_security_agent" description = "Performs company-specific security checks" def __init__(self, knowledge_graph, gitlab_api): self.kg = knowledge_graph self.api = gitlab_api self.scanner = ProprietaryScannerTool() @Action( name="scan_proprietary_patterns", description="Scan for company-specific security patterns" ) def scan_proprietary(self, context): # Get code from Knowledge Graph files = self.kg.query(f"related_files({context.merge_request})") # Run proprietary scanner results = self.scanner.analyze(files) # Post findings to MR for finding in results: self.api.post_mr_comment( project_id=context.project_id, mr_iid=context.mr_iid, comment=self.format_finding(finding) ) return {"findings": len(results), "status": "complete"}
MCP Server Implementation
// Example MCP server for custom tool integration import { MCPServer, Tool } from '@modelcontextprotocol/sdk'; const server = new MCPServer({ name: 'custom-compliance-tool', version: '1.0.0', }); server.registerTool({ name: 'check_sox_compliance', description: 'Verify SOX compliance requirements', parameters: { type: 'object', properties: { project_id: { type: 'string' }, merge_request_iid: { type: 'number' } }, required: ['project_id', 'merge_request_iid'] }, handler: async (params) => { // Perform compliance check const result = await performSOXCheck(params); return { compliant: result.passed, violations: result.violations, evidence: result.evidence_urls }; } }); server.listen(3000);
Next Steps
- Understand Triggers: Read triggers.md for trigger configuration
- Master Flows: Explore flows.md for flow orchestration
- Manage Agents: Review agents.md for agent lifecycle
- Integrate with CI/CD: Check integration.md for patterns
- Best Practices: Study best-practices.md for production
Last Updated: January 2026 GitLab Version: 18.7 (Beta), 18.8 GA (Upcoming)