At GitLab, we continue to expand our AI capabilities so I often find myself learning and working in new codebases. Whether I'm debugging issues, implementing new features, or onboarding to different projects, understanding system architecture quickly is crucial. But let's be honest — manually tracing through complex communication flows, especially gRPC connections, can eat up hours of productive development time.
This is exactly the type of tedious, yet necessary, work GitLab Duo Agent Platform is designed to handle. Instead of replacing developers, it amplifies our capabilities by automating routine tasks so we can focus on creative problem solving and strategic technical work.
Let me show you how I used Duo Agent Platform to generate comprehensive documentation for a Golang project's gRPC communication flow — and how it transformed hours of code analysis into a few minutes of guided interaction.
You can follow along with this video:
The challenge: Understanding gRPC communication flows
I was working with a project called "Duo Workflow Executor" that communicates with a gRPC server. Rather than spending my afternoon manually tracing through the codebase to understand the communication patterns, I decided to let Duo Agent Platform handle the heavy lifting.
My goal was simple: generate a clear diagram showing how the gRPC communication works, including what payloads are received, what actions are executed, and what responses are sent back.
Working in VS Code with the GitLab Workflow extension installed, I opened the project and crafted a specific prompt for Duo Agent Platform:
"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."
Duo Agent Platform didn't just blindly execute my request — it began intelligently gathering context to create a comprehensive execution plan. The platform automatically:
- Searched through relevant Go files in the project
- Read the specific file I mentioned (runner.go)
- Identified additional files that would provide necessary context
- Analyzed the codebase structure to understand the gRPC implementation
This contextual awareness is what sets agentic AI tools with great context apart from simple code generation tools. Instead of working in isolation, Duo Agent Platform understands the relationships between different components of your project.
Collaborative refinement
Rather than making assumptions, Duo Agent Platform is designed to keep a human in the loop at critical moments in task execution to deliver better results. In this scenario, the platform paused to ask clarifying questions about the level of detail I wanted.
Agent: "Should I include error handling details in the diagram?"
Me: "Don't focus on error handling. Include all actions. Focus on gRPC payload."
This back-and-forth refinement is crucial. The agent isn't just executing commands — it's working with me to ensure the deliverable meets my specific requirements.
Execution and results
With the clarified requirements, Duo Agent Platform finalized its execution plan and requested confirmation before proceeding. I could have modified the approach at this stage, but the plan was perfectly aligned with what I needed.
The agent then executed each task in sequence, providing real-time progress updates. Within minutes, it had:
- Analyzed all relevant files across the project
- Created comprehensive documentation with a detailed mermaid diagram
- Saved everything to the requested grpc.md file
- Included valuable context about outgoing payloads and connection management
The resulting documentation wasn't just a basic diagram — it was thorough, accurate, and immediately useful for understanding the system architecture.
Reviewing the output
Here's the actual mermaid diagram that Duo Agent Platform created, showing the complete gRPC communication flow:
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
This diagram reveals several important architectural insights that would have taken considerable time to extract manually:
- Bidirectional communication: The workflow executor both initiates requests and responds to service actions.
- Rich payload structure: Each action type has specific parameters and expected responses.
- Multiple integration points: The executor interacts with local filesystem, Git repositories, and GitLab APIs.
- Comprehensive action set: Nine different action types handle everything from file operations to HTTP requests.
- Proper lifecycle management: Clear connection establishment and teardown patterns.
What impressed me most was how the agent automatically included the detailed payload structures for each action type. This level of detail transforms the diagram from a high-level overview into actionable documentation that other developers can immediately use.
Looking ahead
This demonstration represents just one use case for GitLab Duo Agent Platform. The same contextual understanding and collaborative approach that made documentation generation seamless can be applied to:
- Code reviews: Agents can analyze merge requests with full project context
- Testing: Generate comprehensive test suites based on actual usage patterns
- Debugging: Trace issues across multiple services and components
- Security scanning: Identify vulnerabilities with understanding of your specific architecture
- CI/CD optimization: Improve pipeline performance based on historical data
GitLab Duo Agent Platform will enter public beta soon so join the wait list today.
Stay tuned to the GitLab Blog and social channels for additional updates. GitLab Duo Agent Platform is evolving rapidly with specialized agents, custom workflows, and community-driven extensions on the roadmap.