Die Analyse komplexer Kommunikationsflüsse in modernen Software-Architekturen erfordert systematische Dokumentation. Die manuelle Nachverfolgung von gRPC-Verbindungen zwischen Microservices kann mehrere Stunden Entwicklungszeit pro System beanspruchen – Zeit, die für die eigentliche Entwicklungsarbeit fehlt. GitLab Duo Agent Platform automatisiert diese Aufgabe durch kontextbasierte Codeanalyse und erstellt detaillierte Architekturdiagramme mit vollständiger Payload-Spezifikation.
Die Duo Agent Platform reduziert mehrere Stunden Codeanalyse auf wenige Minuten durch automatisierte Analyse, kontinuierliche menschliche Kontrolle und systematische Dokumentationserstellung. Die folgende Demonstration zeigt die Erstellung einer vollständigen gRPC-Dokumentation für ein Golang-Projekt.
Das folgende Video dokumentiert den vollständigen Workflow:
Aufgabenstellung: gRPC-Kommunikationsflüsse analysieren
Das Beispielprojekt "Duo Workflow Executor" kommuniziert mit einem gRPC-Server über bidirektionale Streaming-Verbindungen. Die Dokumentationsaufgabe umfasst die Darstellung des vollständigen Kommunikationsflusses mit empfangenen Payloads, ausgeführten Aktionen und zurückgesendeten Responses.
Die Implementierung erfolgt in VS Code mit installierter GitLab Workflow Extension. Der spezifische Prompt für die Duo Agent Platform definiert die Anforderungen präzise:
"Can you prepare a mermaid diagram that shows the gRPC connection between duo-workflow-service and this project. It should show what this project receives in gRPC payload, and what actions it executes based on the payload, and what it sends back. Study internal/services/runner/runner.go, especially the Run method, and write the mermaid output to a grpc.md file."
Die Duo Agent Platform analysiert die Anforderung und erstellt einen systematischen Ausführungsplan. Der Agent führt automatisch folgende Schritte aus:
- Durchsuchen relevanter Go-Dateien im Projekt
- Lesen der spezifizierten Datei runner.go
- Identifizierung zusätzlicher Dateien für notwendigen Kontext
- Analyse der Codebase-Struktur zur Erfassung der gRPC-Implementierung
Diese kontextbasierte Analyse unterscheidet Agenten-Systeme mit vollständigem Projektverständnis von einfachen Code-Generierungs-Tools. Die Duo Agent Platform erfasst die Beziehungen zwischen verschiedenen Komponenten des Projekts und berücksichtigt diese bei der Dokumentationserstellung.
Kollaborative Verfeinerung
Die Duo Agent Platform ist darauf ausgelegt, bei kritischen Momenten der Aufgabenausführung menschliche Rückmeldung einzuholen. Im vorliegenden Beispiel pausiert der Agent zur Klärung des gewünschten Detailgrads.
Agent: "Should I include error handling details in the diagram?"
Antwort: "Don't focus on error handling. Include all actions. Focus on gRPC payload."
Dieser iterative Verfeinerungs-Prozess stellt sicher, dass die Dokumentation die spezifischen Anforderungen erfüllt. Der Agent arbeitet kollaborativ mit dem Entwickler zusammen, anstatt Annahmen über die gewünschte Ausgabe zu treffen.
Ausführung und Ergebnisse
Nach der Klärung finalisiert die Duo Agent Platform den Ausführungsplan und fordert Bestätigung vor der Ausführung an. Der Plan kann zu diesem Zeitpunkt noch angepasst werden.
Der Agent führt anschließend die Aufgaben sequenziell aus und liefert Fortschrittsmeldungen in Echtzeit. Innerhalb weniger Minuten werden folgende Ergebnisse erstellt:
- Analyse aller relevanten Dateien im Projekt
- Erstellung detaillierter Dokumentation mit vollständigem Mermaid-Diagramm
- Speicherung in der angeforderten Datei grpc.md
- Integration wertvoller Kontextinformationen zu ausgehenden Payloads und Verbindungsverwaltung
Die resultierende Dokumentation ist nicht nur ein grundlegendes Diagramm, sondern eine detaillierte, präzise und unmittelbar verwendbare Architekturübersicht.
Analyse der Ausgabe
Das folgende Mermaid-Diagramm zeigt den vollständigen gRPC-Kommunikationsfluss, den die Duo Agent Platform erstellt hat:
sequenceDiagram
participant DWS as duo-workflow-service
participant DWE as duo-workflow-executor
participant Runner as ExecutionRunner
participant ActionExecutor as Action Executor
participant FileSystem as File System/Commands
Note over DWS, DWE: gRPC Bidirectional Streaming (ExecuteWorkflow)
%% Connection Establishment
DWE->>DWS: gRPC Connection with Headers
Note over DWE, DWS: Headers: authorization (Bearer token)<br/>x-gitlab-authentication-type: oidc<br/>x-gitlab-realm, x-gitlab-global-user-id<br/>x-gitlab-oauth-token, x-gitlab-base-url<br/>x-gitlab-instance-id, x-request-id<br/>x-gitlab-namespace-id, x-gitlab-project-id
%% Workflow Start Request
DWE->>DWS: ClientEvent{StartWorkflowRequest}
Note over DWE, DWS: StartWorkflowRequest:<br/>- ClientVersion<br/>- WorkflowDefinition<br/>- Goal<br/>- WorkflowID<br/>- WorkflowMetadata<br/>- ClientCapabilities[]
%% Action Processing Loop
loop Action Processing
DWS->>DWE: Action Message
Note over DWS, DWE: Action Types:<br/>- Action_RunCommand {program, flags[], arguments[]}<br/>- Action_RunGitCommand {command, arguments[], repositoryUrl}<br/>- Action_RunReadFile {filepath}<br/>- Action_RunWriteFile {filepath, contents}<br/>- Action_RunEditFile {filepath, oldString, newString}<br/>- Action_RunHTTPRequest {method, path, body}<br/>- Action_ListDirectory {directory}<br/>- Action_FindFiles {namePattern}<br/>- Action_Grep {searchDirectory, pattern, caseInsensitive}<br/>- Action_NewCheckpoint {}<br/>- Action_RunMCPTool {}
DWE->>Runner: Receive Action
Runner->>Runner: processWorkflowActions()
Runner->>ActionExecutor: executeAction(ctx, action)
alt Action_RunCommand
ActionExecutor->>FileSystem: Execute Shell Command
Note over ActionExecutor, FileSystem: Executes: program + flags + arguments<br/>in basePath directory
FileSystem-->>ActionExecutor: Command Output + Exit Code
else Action_RunReadFile
ActionExecutor->>FileSystem: Read File
Note over ActionExecutor, FileSystem: Check gitignore rules<br/>Read file contents
FileSystem-->>ActionExecutor: File Contents
else Action_RunWriteFile
ActionExecutor->>FileSystem: Write File
Note over ActionExecutor, FileSystem: Check gitignore rules<br/>Create/overwrite file
FileSystem-->>ActionExecutor: Success/Error Message
else Action_RunEditFile
ActionExecutor->>FileSystem: Edit File
Note over ActionExecutor, FileSystem: Read → Replace oldString with newString → Write<br/>Check gitignore rules
FileSystem-->>ActionExecutor: Edit Result Message
else Action_RunGitCommand
ActionExecutor->>FileSystem: Execute Git Command
Note over ActionExecutor, FileSystem: Git operations with authentication<br/>Uses provided git config
FileSystem-->>ActionExecutor: Git Command Output
else Action_RunHTTPRequest
ActionExecutor->>DWS: HTTP Request to GitLab API
Note over ActionExecutor, DWS: Method: GET/POST/PUT/DELETE<br/>Path: API endpoint<br/>Body: Request payload<br/>Headers: Authorization
DWS-->>ActionExecutor: HTTP Response
else Action_ListDirectory
ActionExecutor->>FileSystem: List Directory Contents
Note over ActionExecutor, FileSystem: Respect gitignore rules
FileSystem-->>ActionExecutor: Directory Listing
else Action_FindFiles
ActionExecutor->>FileSystem: Find Files by Pattern
Note over ActionExecutor, FileSystem: Recursive search with name pattern<br/>Respect gitignore rules
FileSystem-->>ActionExecutor: File Paths List
else Action_Grep
ActionExecutor->>FileSystem: Search Text Pattern
Note over ActionExecutor, FileSystem: Recursive text search<br/>Case sensitive/insensitive option
FileSystem-->>ActionExecutor: Search Results
else Action_NewCheckpoint/Action_RunMCPTool
ActionExecutor->>ActionExecutor: No-op Action
Note over ActionExecutor: Returns empty success result
end
ActionExecutor-->>Runner: Action Result (string)
alt Result Size Check
Runner->>Runner: Check if result > 4MB
Note over Runner: If result exceeds MaxMessageSize (4MB)<br/>Replace with error message about size limit
end
Runner->>DWE: ActionResponse
DWE->>DWS: ClientEvent{ActionResponse}
Note over DWE, DWS: ActionResponse:<br/>- RequestID (matches Action.RequestID)<br/>- Response (execution result string)
end
%% Workflow Completion
DWE->>DWS: CloseSend()
Note over DWE, DWS: Signal end of workflow execution
%% Analytics and Cleanup
Runner->>Runner: Send Analytics Event (Finish)
DWE->>DWE: Token Revocation (if enabled)
DWE->>DWS: Close gRPC Connection
Das Diagramm zeigt mehrere wichtige Architektur-Aspekte, deren manuelle Erfassung erhebliche Zeit erfordern würde:
- Bidirektionale Kommunikation: Der Workflow Executor initiiert Requests und antwortet auf Service-Aktionen.
- Strukturierte Payload-Definitionen: Jeder Aktionstyp definiert spezifische Parameter und erwartete Responses.
- Multiple Integrationspunkte: Der Executor interagiert mit lokalem Filesystem, Git-Repositories und GitLab-APIs.
- Vollständiger Aktionssatz: Neun verschiedene Aktionstypen decken Dateioperationen, HTTP-Requests und Git-Kommandos ab.
- Lebenszyklus-Verwaltung: Klare Muster für Verbindungsaufbau, Ausführung und Token-Widerruf.
Der Agent integriert automatisch die detaillierten Payload-Strukturen für jeden Aktionstyp in das Diagramm. Dieser Detailgrad transformiert eine Übersicht auf hohem Level in eine unmittelbar verwendbare technische Dokumentation für Entwickler-Teams.
Systematische Anwendungsfälle
Der Agent-Workflow folgt einem systematischen Ansatz: Kontexterfassung durch Analyse relevanter Dateien, kollaborative Verfeinerung durch gezielte Rückfragen, Erstellung eines Ausführungsplans zur Bestätigung, schrittweise Ausführung mit Fortschrittsmeldungen. Diese Transparenz entspricht den Anforderungen an nachvollziehbare Automatisierung in Entwicklungsteams.
Das demonstrierte Vorgehen kann auf weitere DevSecOps-Aufgaben übertragen werden:
- Code Reviews: Agenten analysieren Merge Requests mit vollständigem Projekt-Kontext
- Testing: Generierung umfassender Test-Suites basierend auf tatsächlichen Nutzungsmustern
- Debugging: Nachverfolgung von Problemen über multiple Services und Komponenten
- Security Scanning: Identifizierung von Schwachstellen unter Berücksichtigung der spezifischen Architektur
- CI/CD-Optimierung: Verbesserung der Pipeline-Performance basierend auf historischen Daten
Die GitLab Duo Agent Platform tritt demnächst in die öffentliche Beta-Phase ein. Registrierung für die Warteliste möglich.
Weitere Updates zum Stand der Entwicklung werden im GitLab Blog sowie über die Social-Media-Kanäle veröffentlicht. Die Roadmap umfasst spezialisierte Agenten, Custom Workflows und Community-Extensions.