## Summary You can now build custom AI flows by referencing and reusing existing agents from the AI Catalog as composable building blocks, eliminating the need to copy-paste agent definitions across flows. This means you can assemble powerful multi-agent workflows — like MR review orchestration or reliability analysis with specialized subagents — faster and with less duplication, while GitLab automatically tracks which agents your flows depend on for easier governance and impact analysis. ## 1. Summary Custom flows in the AI Catalog are currently self-contained YAML definitions that cannot reference existing agents or flows as reusable building blocks. This creates duplication, limits governance, and blocks the multi-agent composition patterns that enterprise customers and GitLab engineering teams need. This PRD proposes a sequenced, platform-safe path to composition for Duo Agent Platform. --- ## 2. Problem Statement ### 2.1 Current State - Custom flows are Flow Registry v1 YAML with inline `AgentComponent` definitions. They cannot reference catalog agents or other flows by ID. - AI Catalog manages agents, flows, and MCP servers as separate item types but has no first-class composition model — no dependency graph, no "what uses this?" query, no governed reference mechanism. ### 2.2 User Pain - **Duplication and drift**: Teams re-implement the same agent logic (code analyzer, security reviewer, test runner) in multiple flows. - **No "Lego block" composition**: Architecture-minded customers want to assemble flows from catalog items the way CI/CD components are assembled. - **Governance blind spot**: No machine-readable dependency graph means audits, approvals, and impact analysis are manual and error-prone. ### 2.3 Why This Matters - **Scalability**: Without composition capabilities, complexity grows as each new use case duplicates agent logic. - **Competitive pressure**: LangGraph, OpenAI, and Anthropic all emphasize multi-agent composition as a core pattern. Customers explicitly compare DAP against these. --- ## 3. Goals and Non-Goals ### 3.1 Goals - **Agent reuse in flows**: Allow flow authors to reference catalog agents (foundational, custom) and catalog flows (foundational, custom) from flow YAML without duplicating their definition. - **Stable supervisor + subagent pattern**: Productize the experimental supervisor/subagent concept into a supported Flow Registry v1 pattern. - **Dependency visibility**: Make agent/flow dependencies explicit, machine-readable, and surfaced in the AI Catalog UI. - **Governance alignment**: Ensure composition respects the visibility tier and approval workflow model. ### 3.2 Non-Goals - **Arbitrary recursive flow DAGs**: Initial scope is shallow composition (1-level agent references, 1-level subagent depth). Arbitrary nesting is explicitly out of scope. - **Cross-namespace agent references**: Phase 1 is scoped to agents visible within the same project/group namespace. - **Visual composition canvas**: Out of scope; the YAML model defined here must be compatible with the Visual Builder but does not implement it. --- ## 4. Users and Use Cases ### 4.1 Primary Personas - **Platform/DevEx engineers**: Maintain a central library of agents and flows. Need reusable components and a governable rollout model. - **Team-level flow authors** (senior devs, SREs, security engineers): Build flows for team-specific workflows. Want to assemble existing agents rather than learn all Flow Registry internals. - **Admins**: Need to see and control which agents are used in which flows, especially in regulated environments. ### 4.2 Representative Use Cases - **MR Review orchestration**: A custom flow references a foundational code review agent and a custom security agent, aggregates results into a single MR note — without duplicating either agent's prompt or tools. - **Reliability analysis with subagents**: A reliability flow uses a supervisor that delegates to `infra_analyzer`, `cost_analyzer`, and `security_analyzer` subagents — all defined once and reused across multiple flows. - **Mixed-agent orchestration**: A supervisor agent dynamically delegates to a combination of foundational and custom catalog agents based on the context of the task, without the flow author needing to inline each agent's definition. --- ## 5. Requirements ### 5.1 Functional Requirements **FR1 – Reference catalog agents in flows** - Flow YAML can declare an `AgentComponent` that references an AI Catalog/Flow agent by stable reference (catalog item ID or slug), mutually exclusive with inline `prompt`/`tools`. - At runtime, the flow resolves the agent's pinned version for the project/group using the existing version pinning model (managing project = latest; other projects = group pin). - Validation at flow save time: referenced agent must exist and be visible/enabled for the namespace. **FR2 – Supervisor + subagent pattern** Flow Registry v1 exposes a supported, documented pattern for supervisor + subagents: - Mark an `AgentComponent` as a supervisor with a `subagents` list. - Subagents can be defined inline (same YAML) - Execution: supervisor can delegate to subagents multiple times; subsession-scoped histories maintained per subagent; result surfaced via a well-defined `final_answer` key. - Maximum subagent depth: 1 level (supervisor + subagents, no nested supervisors). **FR3 – Dependency visibility** - For each flow in AI Catalog, store and expose a machine-readable dependency graph: which catalog agents and flows it references. - Surface in UI: "This flow uses: \[Code Review Agent\], \[Security Agent\]" with links to each catalog item. - Expose a "where is this agent used?" query at catalog level (for admins and governance). - Dependency graph is updated on every flow save. **FR4 – Governance alignment** - Flow can only reference agents/flows that are visible and enabled for the flow's project/group namespace (enforced at save and at runtime). - When a referenced agent's version is updated, the flow continues to use its pinned version until explicitly updated by the flow author. When a custom agent or custom flow is updated, the flow that references those agents or subflows should surface a notification that an update is available. **FR5 – AI Catalog UX for composition** - In the custom flow editor: allow selection of existing catalog agents as components. - Show read-only summary of selected agents: name, owner, version pin, enabled status. - On flow detail page: show dependency list with links. - On agent detail page: show "used by N flows" with list (for Maintainer/Owner). ### 6.2 Non-Functional Requirements - **Backwards compatibility**: Existing custom flows remain valid; no breaking YAML changes. - **Billing**: Credits are consumed once per actual underlying agent execution. No double-billing for agent references. - **Observability**: All composed flow executions emit `origin_type` in telemetry (`foundational`, `custom`). --- ## 6. Success Metrics | Metric | Target | Measurement Method | |--------|--------|--------------------| | Adoption: agent references | ≥ 20% of newly created custom flows reference at least one catalog agent within 2 quarters of Phase 1 GA | Telemetry: `flow_saved` with `has_catalog_agent_ref=true` | | Reuse | At least 5 catalog agents referenced by ≥ 3 distinct flows within 2 quarters of Phase 2 GA | Dependency graph query | | Customer signals | ≥ 3 named customers shipping multi-agent flows in production within 2 quarters of Phase 2 GA | CS/field tracking | | Reliability | Zero critical incidents related to dependency resolution or mis-executed composed flows in first 2 milestones post-GA | Incident tracker | | Governance | ≥ 80% of flows with catalog references have a complete, accurate dependency graph within 1 quarter of Phase 1 GA | Catalog data quality audit | --- ## 7. Risks and Mitigations | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | Composition ships before reliability baseline is ready | Medium | High | Phase 0 prerequisites are hard gates, not soft dependencies | | Deep dependency chains become hard to reason about | Medium | Medium | Enforce max depth limits (1-level subagents); clear UI visualization | | Versioning conflicts when referenced agent is updated | High | Medium | Use existing version pinning model; surface "dependency updated" notification to flow author | | Governance hole: flow references agent not approved for namespace | Medium | High | Validate at save time and runtime; block or flag unapproved references | | Billing confusion in composed flows | Medium | Medium | Document credit consumption model explicitly; emit `origin_type` in all telemetry | | Agent composition alone insufficient for customers needing live flow invocation | Low | Low | Runtime flow invocation explicitly deferred to Phase 3; revisit with customer evidence | --- ## 8. Open Questions - **Subagent depth limit**: Is 1-level (supervisor + subagents, no nested supervisors) the right constraint, or do known use cases require 2-level nesting? - **MCP servers as composable units**: Should MCP servers be includable as tool sources in composed flows? If so, which phase?