Register Onboarding Guide as foundational experimental (v1, experiment flag)

Neil Fryerequested to merge
onboarding-guide-foundational-experimental into master

What & why

Registers the "Duo Onboarding Guide" AI Catalog agent (item 1003979) as a foundational agent so it is selectable in GitLab Duo Chat, and adds user-facing docs. Companion to the ai-assist bundling MR.

Runbook: https://docs.gitlab.com/development/ai_features/foundational_chat_agents/

Change

  • ITEMS entry in ee/lib/ai/foundational_chat_agents_definitions.rb (id 10, reference onboarding_guide, global_catalog_id 1003979, version 'v1'), structure mirrored from ci_expert_agent (1004583).
    • tools: key intentionally omitted. Precedent: support_assistant (id 8, catalog-backed) omits it; the agent's tools ship via the bundled catalog config that fetch-foundational-agents pulls.
    • avatar omitted, mirroring ci_expert_agent (no avatar field; model default applies).
    • selectable_in_chat omitted deliberately. The key appears in that file only to opt out (duo_permissions_assistant, agentic_chat); all five catalog-backed selectable agents rely on the model default of true.
  • Feature flag gate in ee/app/graphql/resolvers/ai/foundational_chat_agents_resolver.rb: onboarding_guide_agent experiment flag, default off, applied on both GitLab.com (root namespace actor) and GitLab Self-Managed (global/nil actor).
  • Feature flag definition at config/feature_flags/experiment/onboarding_guide_agent.yml.
  • User-facing docs at doc/user/duo_agent_platform/agents/foundational_agents/onboarding_guide.md.
  • Onboarding agent added to the available agents list in doc/user/duo_agent_platform/agents/foundational_agents/_index.md.

Resolved decisions

  • Version field: stays 'v1' — confirmed by @eduardobonet; this is the flow-registry/library version, not a maturity label.
  • Experiment gating: implemented via the onboarding_guide_agent experiment feature flag (default off). Applied on both GitLab.com (root namespace as actor, enabling per-group ChatOps rollout) and GitLab Self-Managed (nil actor, global gate). Modeled after the orbit_agent reject pattern in the resolver.
  • Feedback issue: created as #606350 and linked from the docs page.
  • Rollout issue: created as #612244 and referenced from the flag YAML.

Secret-safety checklist

  • Reviewed for file-generation / CI-config / credential-handling scope.
  • Primary mitigation: the agent cannot write to repository or configuration surfaces (MCP off; cannot create, edit, or commit files, modify pipelines, or change settings). It can create and update planning items: work items, issues, epics, and notes on them. Only when the user asks or accepts an offer, only after it shows the exact content, and never unprompted. Confirmation before every write is the control, and is stated in seven places in the system prompt. Unticked 2026-08-17 — this text changed materially and needs re-reading. See "Correction" below.
  • Verbatim secret-safety guidance added to the system prompt. Pending catalog confirmation: this ships as a separate Catalog version bump on item 1003979, outside this diff, and is not verifiable from the repository. To be confirmed on the catalog item before the flag is enabled.

Correction — 2026-08-17

The secret-safety mitigation above previously read "it may create a work item or epic ... No other writes are possible." That was inaccurate, and it is now unticked pending re-review.

The live grant on catalog item 1003979 holds eight write tools, not two: create_work_item, create_epic, create_issue_note, create_work_item_note, update_work_item, update_issue, update_epic, and create_plan. The earlier plan was to prune the grant back to match the narrower claim. Testing this week showed why that does not work: prose cannot subtract a tool. Where the system prompt and the grant disagree, the grant wins, so a prompt that claims a smaller capability than it has is not a control. It is just an inaccurate description.

v2.0.0 therefore keeps the grant and corrects the prompt to describe it, with confirmation-before-write as the actual control. That part is real and tested: it holds, and it is now stated in seven places rather than relying on any single line.

Two related corrections:

  • No project boundary is claimed. The prompt previously said creation was limited to the project or group under discussion. Testing disproved it, twice: asked to create an epic in an unrelated group, the agent complied. That is now written as a default with a confirm-the-path step, which is a behaviour we can ask for, rather than a limit we cannot enforce.
  • create_plan is not a user-visible write. It tracks the agent's own internal task state, and the grant does not include the task-mutation tools that would go with it. The prompt now says so explicitly, so the agent never tells a user it filed a plan.

Availability

Premium/Ultimate; GitLab.com and GitLab Self-Managed; experiment status; not surfaced on GitLab Dedicated.

Open items (not blocking merge, tracked separately)

  • feature_issue_url is intentionally left unset in the flag YAML. Danger suggests filling it, but the originating feature issue and epic are confidential, and this is a public merge request. #606350 is the user feedback issue and #612244 is the rollout issue; neither is the originating feature issue.
  • Catalog-side secret-safety guidance on item 1003979 still needs confirming, tracked in the "Before global rollout" section of #612244.
  • The mitigation above describes Catalog version v2.0.0, authored but not yet published. The published version (v1.9.0) grants the same 31 tools, and v2.0.0 does not prune them. Behavioural testing established that prompt text cannot subtract a tool: where the prompt and the grant disagree, the grant wins. So the prompt was corrected to describe the grant accurately instead of asserting a narrower one. v2.0.0 must publish before this MR merges — tracked in the "Before global rollout" section of #612244.

Related

Status

Ready for review. The ai-assist bundling gate is satisfied: !6204 (merged) merged in v1.642.0. The agent ships behind the onboarding_guide_agent experiment flag, default off, so merging does not expose it to users.

Edited by Neil Frye

Merge request reports