From 86d26c661db3471536d15d4c88be2a9c5302d008 Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 11:48:12 -0500 Subject: [PATCH 1/8] add first draft --- .../agent_interaction_patterns.md | 156 ++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 doc/development/duo_agent_platform/agent_interaction_patterns.md diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md new file mode 100644 index 00000000000000..b357667009fe6c --- /dev/null +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -0,0 +1,156 @@ +--- +stage: AI-powered +group: Agent Foundations +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/development/development_processes/#development-guidelines-review. +title: Agent Interaction Patterns for Developing on GitLab Duo Agent Platform +--- + +## Purpose + +This guide establishes interaction patterns and rules for agents and flows within GitLab. These patterns ensure consistent, user-friendly behavior while managing infrastructure load and maintaining a high-quality user experience. + +## Overview + +Scope: This guide targets GitLab-managed agents and flows. The patterns should also extend to custom agents created in the AI Catalog. + +### Core User Experience Principals + +1. Minimize notification noise: Agents should provide necessary updates without overwhelming users with notifications and comments. +2. Maintain transparency: Users should be able to track agent progress and understand what actions are being taken. +3. Respect infrastructure constraints: Agent behavior should be designed with scalability in mind, avoiding patterns that create excessive database load. +4. Enable human oversight: Users need clear entry points to review, approve, or intervene in agent work. + + +## Interaction Patterns + +### Comment Management + +##### Initial Comment on an Issue or MR: Create an Initial Comment + +Behavior Pattern: When a flow or agent begins work on an issue or MR, create an initial comment to signal activity. + +* Makes agent activity visible to all collaborators on the item +* Provides a persistent record beyond the sessions UI +* Establishes a comment that can be updated with progress + +Resources: + +* To do: add example template +* To do: add example how-to in the prompt +* To do: add screenshot (design) + +#### Adding Updates While Session is In Progress: Work in the Same Comment + +Behavior Pattern: While an agent is actively working on a task, it should update a single comment rather than creating multiple new comments. + +* Reduces database load and notification spam +* Provides a clean, consolidated view of agent progress +* Prevents issues and MRs from becoming cluttered with AI-generated content + +Resources: + +* To do: add example template +* To do: add example how-to in the prompt +* To do: add screenshot (design) + +##### Adding Update When Flow is Complete or Review Needed: Add a New Comment + +Behavior Pattern: When an agent completes its work or requires human review and follow-up actions, create a new comment with a summary and next steps, and @mention the relevant user. + +* New comments with @mentions create to-dos or emails for users, enaging them on their familiar notification pattern +* Signals a clear transition from "agent working" to "human action required" +* Ensures important milestones don't get lost in updated content + +Resources: + +* To do: add example template +* To do: add example how-to in the prompt +* To do: add screenshot (design) + +###### When Flow Is Completed: Always Provide a Final Summary + +Behavior Pattern: When a flow completes (successfully or with errors), always post a summary comment to the work item. + +Resources: + +* To do: add example template for success and failure +* To do: add example how-to in the prompt +* To do: add screenshot (design) for success and failure + +### Mentioning Users +Behavior Pattern: Agents use @mentions the way a human would: to communication important information to team members who they are collaborating with, while taking care not to create uneccessary noise for others. + +* @mention the user who triggered the flow in the initial comment +* @mention users who need to respond when requesting review or approval +* Avoid @mentioning in progress updates + +Rationale: + +* Ensures the triggering user is aware the agent has started +* Creates to-dos only when human action is needed +* Prevents notification fatigue from progress updates + +## Using the Session Tab in the AI Panel + +Behavior Pattern: Agents should rely on the Sessions section for logging detailed, real-time progress tracking, while using comments for milestone notifications and summaries. Users shouldn't have to go into the Sessions tab for all of their flows. They will use the Sessions tab for troubleshooting and other deeper analysis activities, as well as for managing Sessions asynchronously when they are no longer on the work item or MR related to the Session. + +Content to Show In Sessions tab: + +* Detailed step-by-step progress +* Tool invocations and responses +* Reasoning and decision-making process +* Real-time status updates + +Content to Show In Work Item and MR Comments: + +* Agent started working +* Major milestone updates (if needed) +* Follow-up requests needing human intervention +* Final summary + +## Summary of Best Practices + +### For Developement + +* Use comment IDs: Store the initial comment ID and update it rather than creating new comments +* Timestamp updates: Always include timestamps in progress updates +* Clear state transitions: Make it obvious when transitioning from "working" to "review needed" +* Graceful failures: Always post a summary comment even when errors occur +* Link to sessions: Include links to the full session details for users who want more information + +### For Prompt Engineering + +Include these behaviors in your system prompts: + +COMMENT BEHAVIOR: +* Create ONE initial status comment when you start +* Update that same comment with your progress +* Create a NEW comment when you complete or need review +* Always @mention users in completion/review comments +* Never @mention users in progress updates + +FINAL SUMMARY: +* Always post a final summary when done +* Include what you did, results, and next steps +* Link to the full session details + +### For Infrastructure Considerations + +These patterns help manage load by: + +* Updating vs. creating: Reduces database writes and notification volume +* Consolidated status: One comment per active session vs. many +* Selective @mentions: Reduces to-do item creation to meaningful moments +* Session UI for details: Keeps detailed logs out of the primary work item + +### Other Considerations + +As the Agent Platform evolves, we may need to address: + +* Collapsible progress: UI patterns for hiding detailed progress while preserving summaries +* Multi-agent coordination: How agents should communicate when multiple agents work on the same item +* User preferences: Allowing users to customize notification levels +* Enhanced session links: Making session details more discoverable from comments +* and many more things we may not have thought of yet. + +If you need help extending these patterns or introducing new ones, you should reach out to the Product Design team and the Agent Foundations team, so that you can design a new pattern together and add it into this document for future use. -- GitLab From d2111136acd848cc48ede5bd47e79e3ba97fc6ce Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 12:03:15 -0500 Subject: [PATCH 2/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- .../duo_agent_platform/agent_interaction_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md index b357667009fe6c..4efbc7a2685bf3 100644 --- a/doc/development/duo_agent_platform/agent_interaction_patterns.md +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -67,7 +67,7 @@ Resources: * To do: add example how-to in the prompt * To do: add screenshot (design) -###### When Flow Is Completed: Always Provide a Final Summary +#### When Flow Is Completed: Always Provide a Final Summary Behavior Pattern: When a flow completes (successfully or with errors), always post a summary comment to the work item. -- GitLab From 174a0fbd2de871857932bc2864480ad0ac21446b Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 12:03:24 -0500 Subject: [PATCH 3/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- .../duo_agent_platform/agent_interaction_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md index 4efbc7a2685bf3..546e616e7e6298 100644 --- a/doc/development/duo_agent_platform/agent_interaction_patterns.md +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -53,7 +53,7 @@ Resources: * To do: add example how-to in the prompt * To do: add screenshot (design) -##### Adding Update When Flow is Complete or Review Needed: Add a New Comment +#### Adding Update When Flow is Complete or Review Needed: Add a New Comment Behavior Pattern: When an agent completes its work or requires human review and follow-up actions, create a new comment with a summary and next steps, and @mention the relevant user. -- GitLab From 17570a590870f253de1b9716b9ff5c692ebb63d9 Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 12:03:29 -0500 Subject: [PATCH 4/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- .../duo_agent_platform/agent_interaction_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md index 546e616e7e6298..9159928f8d14b4 100644 --- a/doc/development/duo_agent_platform/agent_interaction_patterns.md +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -25,7 +25,7 @@ Scope: This guide targets GitLab-managed agents and flows. The patterns should a ### Comment Management -##### Initial Comment on an Issue or MR: Create an Initial Comment +#### Initial Comment on an Issue or MR: Create an Initial Comment Behavior Pattern: When a flow or agent begins work on an issue or MR, create an initial comment to signal activity. -- GitLab From 876e44162616ef9c411e412a66e94f6dd34e271e Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 12:03:35 -0500 Subject: [PATCH 5/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- .../duo_agent_platform/agent_interaction_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md index 9159928f8d14b4..a123831f96fd42 100644 --- a/doc/development/duo_agent_platform/agent_interaction_patterns.md +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -110,7 +110,7 @@ Content to Show In Work Item and MR Comments: ## Summary of Best Practices -### For Developement +### For Development * Use comment IDs: Store the initial comment ID and update it rather than creating new comments * Timestamp updates: Always include timestamps in progress updates -- GitLab From a698676462396cb0cef1f25f417ef5bdfd0ac90b Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 12:03:49 -0500 Subject: [PATCH 6/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- .../duo_agent_platform/agent_interaction_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md index a123831f96fd42..74d3f7e92d3afa 100644 --- a/doc/development/duo_agent_platform/agent_interaction_patterns.md +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -78,7 +78,7 @@ Resources: * To do: add screenshot (design) for success and failure ### Mentioning Users -Behavior Pattern: Agents use @mentions the way a human would: to communication important information to team members who they are collaborating with, while taking care not to create uneccessary noise for others. +Behavior Pattern: Agents use @mentions the way a human would: to communicate important information to team members who they are collaborating with, while taking care not to create unnecessary noise for others. * @mention the user who triggered the flow in the initial comment * @mention users who need to respond when requesting review or approval -- GitLab From aec781cb2d3712bb56e854264d449a17e3bb1d7a Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 12:04:00 -0500 Subject: [PATCH 7/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- .../duo_agent_platform/agent_interaction_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md index 74d3f7e92d3afa..9a98c5d635f67d 100644 --- a/doc/development/duo_agent_platform/agent_interaction_patterns.md +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -57,7 +57,7 @@ Resources: Behavior Pattern: When an agent completes its work or requires human review and follow-up actions, create a new comment with a summary and next steps, and @mention the relevant user. -* New comments with @mentions create to-dos or emails for users, enaging them on their familiar notification pattern +* New comments with @mentions create to-dos or emails for users, engaging them on their familiar notification pattern * Signals a clear transition from "agent working" to "human action required" * Ensures important milestones don't get lost in updated content -- GitLab From 769cb43dd022414ae181c0507139610a9d1af9ef Mon Sep 17 00:00:00 2001 From: Jacki Bauer Date: Wed, 22 Oct 2025 12:05:04 -0500 Subject: [PATCH 8/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- .../duo_agent_platform/agent_interaction_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/duo_agent_platform/agent_interaction_patterns.md b/doc/development/duo_agent_platform/agent_interaction_patterns.md index 9a98c5d635f67d..0c0aa97907a9af 100644 --- a/doc/development/duo_agent_platform/agent_interaction_patterns.md +++ b/doc/development/duo_agent_platform/agent_interaction_patterns.md @@ -13,7 +13,7 @@ This guide establishes interaction patterns and rules for agents and flows withi Scope: This guide targets GitLab-managed agents and flows. The patterns should also extend to custom agents created in the AI Catalog. -### Core User Experience Principals +### Core User Experience Principles 1. Minimize notification noise: Agents should provide necessary updates without overwhelming users with notifications and comments. 2. Maintain transparency: Users should be able to track agent progress and understand what actions are being taken. -- GitLab