Adds agents service using SystemNoteService to track agent activity in work item timelines

Shola Quadrirequested to merge
570291/sq/implement-agent-activity-tracking-in-work-items into master

What does this MR do and why?

This MR addresses #570291.

It implements system notes to track GitLab Duo agent activity on work items timelines.

Problem

Users have no visibility into when and how GitLab Duo agents interact with their work items, making it difficult to understand agent activities and troubleshoot workflow executions.

Solution

We're creating automatic system notes in work item timelines when agents start, complete or fail sessions. This provides transparency and audit trails for all agent interactions in work items.

Scope

This implementation focuses on the issue_to_merge_request flow use case as a first iteration but is set up in a reusable way for other workflow types, i.e. software_development, convert_to_gitlab_ci, etc.

When a GitLab Duo agent performs activities related to a work item, users will see that an Agent is working on the work-item in the work items timeline.

Implementation

  • System note creation at three workflow lifecycle points:

    • Session started (when workflow begins)
    • Session completed (on successful completion)
    • Session failed (on cancellation or error)

  • Updated SystemNoteService to support agent session tracking

  • New AgentsService for creating agent-specific system notes

How to set up and validate locally

Prequisites

  • An active Ultimate license.
  • Duo Enterprise subscription configured: bundle exec 'rake gitlab:duo:setup[duo_enterprise]'
  • Remote Flows configured locally. Follow these steps to set up and configure.

Once the correct license and Remote Flows have been set up locally, follow the validation steps below.

Validation Steps

  1. Navigate to an issue in the UI: for example http://gdk.test:3000/gitlab-duo/test/-/issues and select any of the issue
  2. Test agent started note:
    • Click Generate MR with Duo button to trigger the issue_to_merge_request workflow
    • Verify a system note appears in the Issue timeline: "started Duo Developer session ID triggered by Issue to MR"
  3. Test agent completed note:
    • Wait for the workflow from step 2 to complete successfully
    • Verify a system note appears in the Issue timeline: "Duo Developer completed session ID"
  4. Test agent failed note:
    • Trigger another issue_to_merge_request workflow by clicking the Generate MR with Duo button
    • Navigate to the workflow job and cancel it manually
    • Return to the issue and verify a system note appears: "Duo Developer session ID failed (dropped)"

Expected Results

  • All three system notes should appear in the issue timeline with:
    • Clickable links to the agent session details
    • Appropriate trigger source or failure reason
    • Correct timestamps

Screenshots

1. System note creation in a top level project

Screenshot_2025-10-20_at_13.34.55

2. System note creation in a nested project

Screenshot_2025-10-20_at_13.32.47

3. System note creation in a deeply nested project

Screenshot_2025-10-20_at_13.32.02

Acceptance Criteria

  • Agent session activities appear in work item timelines
  • Session IDs are included for traceability
  • Trigger sources are captured and displayed
  • Integration works with existing timeline/activity feed UI
  • Performance impact is minimal
  • Tests cover the new functionality

References

Screenshots or screen recordings

Before After

How to set up and validate locally

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Shola Quadri

Merge request reports