Aegis Contextual Architect

An autonomous AI agent for GitLab Duo that performs deep Knowledge Graph reasoning to deliver concrete "Senior Intelligence" security and regression briefings upon issue assignment.

Comment

The Inspiration 💡 When developers are assigned a new issue, they typically stare at a blank slate or a vague bug description. They lack historical context—who wrote the code, what past security vulnerabilities touched those files, or what "legacy ghosts" (code written 2+ years ago) might break if modified. We wanted to build an AI that acts like a Senior Architect, doing this deep research instantly upon assignment.

What it does 🛠️ Aegis is an autonomous "Handoff Agent" integrated directly into the GitLab AI Catalog. When triggered, it executes a multi-stage Gravity Flow pipeline:

Ingest: Maps the GitLab Knowledge Graph out to a Level-2 depth (Issue → MRs → Files → Commits & CVEs). Reason: A Google Antigravity-powered Node performs four critical analyses: Legacy Ghost Detection: Finds heavily-relied-upon code logic pushed over 2 years ago in the dependency tree. Specialist Identification: Maps a 4-factor Contribution Heatmap (frequency, acceptance, recency decay, and file specificity) to find the absolute best developer to pair with. Temporal Correlation: Links previous CVEs to current files even if function names have changed. Danger Scoring: Compiles a 0-100 risk score matrix based on historical reverts and fan-out. Synthesis: Outputs a structured, professional, evidence-backed Markdown comment directly to the GitLab issue.

How we built it ⚙️

GitLab AI Catalog & Duo: Uses Custom Flows (

flows/contextual-briefing.yml ) and Agent YAML definitions mapped via

.ai-catalog-mapping.json . Knowledge Graph API: Traverses the GitLab API using a sophisticated Level-2 BFS (Breadth-First Search) Pruner to prevent memory explosion. Google Antigravity ADK: The Reasoning Engine runs completely on a 2026-era Antigravity Python Backend (

aegis_engine.py ), utilizing Gemini 3.1 Pro models for semantic graph cross-referencing. Model Context Protocol (MCP): Uses a formalized MCP handshake to connect Antigravity's offline architecture to GitLab's live issue endpoints.

Challenges we ran into 🧩

Knowledge Graph Explosion: Traversing MRs and files recursively easily triggered API rate limits and timeouts. We had to build a custom edge-weight BFS Pruner to cap out at 500 nodes and strictly limit traversal strictly to depth 2. AI Catalog Approval: Enforcing strict parsing requirements in the AI Catalog YAMLs for custom Flows (inputs: formats and git_tag mapping).

Accomplishments that we're proud of We set out to build something that goes far beyond simple code generation or chatbot-style assistance, and we are incredibly proud of achieving an autonomous, enterprise-grade architecture:

The "Legacy Ghost" Concept: We successfully built a reasoning engine capable of identifying and isolating "Legacy Ghosts"—critical logic written over two years ago that still governs files being modified today. This moves AI assistance from reactive bug-fixing into proactive risk management. The 4-Factor Specialist Engine: Instead of the standard (and often inaccurate) "who wrote the most lines of code" metric, we formulated a weighted, 4-factor algorithm prioritizing Recent Accepted MRs to find the true, up-to-date domain expert for any given file. The "Gravity Flow" Pipeline: We architected a robust, 6-stage backend pipeline (Connect → Ingest → Cross-Reference → Reason → Synthesize → Handoff) that flawlessly orchestrates multiple AI functions into a single structured output. 100% Test Coverage: Hackathon projects are often held together with duct tape, but we prioritized engineering excellence. We are proud to submit Aegis with a comprehensive 58-test suite ensuring every component—from the Breadth-First-Search Pruner to the Danger Score formula—is fully verified and production-ready.

🧠 What we learned Building Aegis taught us critical lessons about orchestrating AI agents within large scale, real-world systems:

Knowledge Graph Complexity Management: We learned very quickly that traversing a live, enterprise-scale Knowledge Graph (Issues → MRs → Files → Commits → CVEs) can easily trigger API rate limits and memory explosions. We had to learn how to aggressively cap graph depth (strictly Level-2) and build a custom BFS Pruner with edge-weight filtering to keep the context window focused and performant. GitLab AI Catalog Architecture: We gained deep, hands-on experience navigating the new GitLab AI Catalog interface (

.ai-catalog-mapping.json ). We learned the nuances of defining Custom Flows and Agents via YAML, managing version syncing, and working within the strict constraints of GitLab Duo Workflow components. The Power of the Model Context Protocol (MCP): Implementing an MCP handshake taught us how to securely bridge the gap between flexible, high-memory offline reasoning engines (like Google Antigravity) and the strict, authenticated API ecosystems of platforms like GitLab. Structured AI Outputs: We learned that to deliver true value to Senior Developers, AI cannot return generic summaries. We had to engineer strict prompts requiring concrete citations (MR IDs, Dates, CVE Severities) to ensure our "Contextual Briefing" was always evidence-backed and actionable.

What's next for Aegis 🚀 We plan to introduce a predictive deployment halt parameter into the workflow. If the Danger Score of affected files pushes above an 85/100, Aegis could automatically intercept the deployment pipeline and require a manual review from the designated Heatmap Specialist.

Built With

  • gemini-3.1-pro
  • gitlab-duo
  • google-antigravity-adk
  • knowledge-graph-api
  • mcp
  • python-3.11
Share this project:

Updates