파운데이셔널 플로는 에이전트 팀을 조율해 액션을 실행하고 작업을 완료하도록 미리 정의된 구조화된 단계 시퀀스입니다. 이 플로는 GitLab이 만들고 유지 관리하며, 특정 개발 워크플로에 대한 신뢰할 수 있는 자동화를 제공합니다. 파운데이셔널 플로는 GitLab 전반에서 기본으로 제공되며 GitLab Duo Self-Hosted에서도 지원됩니다. 커스텀 플로와 달리 파운데이셔널 플로는 GitLab이 만들어 배포하며 사용자가 수정할 수 없습니다.

개요#

파운데이셔널 플로는 GitLab이 유지 관리하는 AI 기반 워크플로로, 사용자가 소프트웨어 개발 수명 주기 전반의 개발 작업을 자동화하도록 돕습니다. 대화형으로 동작하는 파운데이셔널 챗 에이전트와 달리 파운데이셔널 플로의 특징은 다음과 같습니다.

• 구조화: 미리 정의된 단계 시퀀스를 따릅니다
• 자율: 사람의 지속적인 개입 없이 실행됩니다
• 작업 중심: 특정하고 반복 가능한 작업을 완료하도록 설계되었습니다
• 트리거 기반: 시스템 이벤트나 사용자 액션으로 시작할 수 있습니다

사용 가능한 파운데이셔널 플로의 전체 목록은 파운데이셔널 플로 사용자 문서를 참고합니다.

파운데이셔널 플로 생성#

파운데이셔널 플로를 만드는 방법은 AI Catalog를 사용하는 방법과 GitLab Duo Workflow Service를 사용하는 방법 두 가지입니다. AI Catalog는 사용하기 쉬운 인터페이스를 제공하므로 우선 권장되며, GitLab Duo Workflow Service에 정의를 작성하는 방식은 복잡한 사례에 더 큰 유연성을 제공합니다.

AI Catalog 사용#

1. AI Catalog에서 플로를 만들고 해당 ID를 기록합니다. 플로가 public으로 설정되어 있는지 확인합니다. 예시: ID가 123인 플로.

2. AI Catalog에서 만든 플로는 SaaS에 접근할 수 없는 자체 호스팅 환경에서도 사용할 수 있도록 GitLab Duo Workflow Service에 번들로 포함해야 합니다. 이를 위해 GitLab Duo Workflow Service에 플로 ID를 추가하는 MR을 엽니다.

   # https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/Dockerfile
   - RUN poetry run fetch-foundational-flows "https://gitlab.com" "$GITLAB_TOKEN" "developer:123" \
   + RUN poetry run fetch-foundational-flows "https://gitlab.com" "$GITLAB_TOKEN" "developer:123,<flow-reference>:<flow-catalog-id>" \
   

   위 명령은 테스트 목적으로 로컬에서 실행할 수도 있습니다. 플로 참조는 공백 없이 소문자여야 하며 플로 정의에서 사용하는 패턴과 일치해야 합니다(예시: test_flow).

3. 플로를 사용자가 선택하고 사용할 수 있게 하려면 FoundationalFlow 모델의 ITEMS 배열에 추가합니다. Dockerfile에서 사용한 참조를 그대로 사용합니다.

   {
     display_name: "Test Flow",
     description: "A flow for testing purposes",
     avatar: "test-flow.png",
     foundational_flow_reference: "<flow-reference>/v1",
     feature_maturity: "experimental",
     ai_feature: "duo_agent_platform",
     agent_privileges: [
       ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_FILES,
       ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB
     ],
     environment: "web",
     triggers: []
   }
   

4. 플로에 커스텀 아바타가 필요하면 GitLab SVGs 리포지터리에 PNG 파일을 추가합니다.

5. 새 플로에 대한 정보로 사용자 대상 문서를 업데이트합니다.

GitLab Duo Workflow Service 사용#

1. /duo_workflow_service/agent_platform/v1/flows/configs/에 플로 구성 파일을 만듭니다(이 경로는 GDK의 PATH-TO-YOUR-GDK/gdk/gitlab-ai-gateway 아래 또는 ai-assist 리포지터리에 있습니다).

   파일: /duo_workflow_service/agent_platform/v1/flows/configs/test_flow.yml

   version: "v1"
   environment: web
   components:
     - name: "test_flow_agent"
       type: AgentComponent
       prompt_id: "test_flow_prompt"
       inputs:
         - from: "context:goal"
           as: "goal"
         - from: "context:project_id"
           as: "project_id"
       toolset:
         - "read_file"
         - "list_dir"
       ui_log_events: []
   prompts:
     - name: Test Flow Prompt
       prompt_id: "test_flow_prompt"
       model:
         params:
           max_tokens: 4_000
       prompt_template:
         system: |
           You are a helpful assistant that performs automated tasks in GitLab projects.
           Your goal is to help users by executing predefined workflows efficiently.
   
           Available tools:
           - read_file: Read the contents of a file
           - list_dir: List files in a directory
   
           Use these tools to complete the user's request.
         user: |
           {{goal}}
         placeholder: history
   routers: []
   flow:
     entry_point: "test_flow_agent"
   

2. FoundationalFlow 모델의 ITEMS 배열에 플로 정의를 추가합니다.

   {
     display_name: "Test Flow",
     description: "A flow for testing purposes",
     avatar: "test-flow.png",
     foundational_flow_reference: "test_flow/v1",
     feature_maturity: "beta",
     ai_feature: "duo_agent_platform",
     agent_privileges: [
       ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_FILES,
       ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB
     ],
     environment: "web",
     triggers: []
   }
   

3. 새 플로에 대한 정보로 사용자 대상 문서를 업데이트합니다.

플로 정의 속성#

FoundationalFlow 모델에 플로를 추가할 때는 다음 속성을 제공해야 합니다.

에이전트 권한#

에이전트 권한은 플로가 수행할 수 있는 액션을 정의합니다. 사용 가능한 권한의 전체 목록은 AgentPrivileges에 정의되어 있습니다.

권한 구성 예시입니다.

agent_privileges = [
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_FILES,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_GITLAB,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::RUN_COMMANDS,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::USE_GIT
]

트리거#

트리거는 플로를 시작하는 방식을 정의합니다. 사용 가능한 트리거 타입은 다음과 같습니다.

• ::Ai::FlowTrigger::EVENT_TYPES[:assign]: 이슈가 할당될 때 트리거됩니다
• ::Ai::FlowTrigger::EVENT_TYPES[:mention]: @ 멘션으로 트리거됩니다
• ::Ai::FlowTrigger::EVENT_TYPES[:schedule]: 시간 기반 트리거입니다(아직 구현되지 않음)

트리거 구성 예시입니다.

triggers: [::Ai::FlowTrigger::EVENT_TYPES[:assign]]

기능 플래그를 사용한 플로 릴리스#

새 파운데이셔널 플로의 릴리스는 기능 플래그로 제어합니다. 이를 통해 점진적 출시와 티어별 제공이 가능합니다.

GraphQL 리졸버 구현 예시입니다.

# ee/app/graphql/resolvers/ai/foundational_flows_resolver.rb

def resolve(*, project_id: nil, namespace_id: nil)
  project = GitlabSchema.find_by_gid(project_id)

  filtered_flows = []
  filtered_flows << 'test_flow' if Feature.disabled?(:test_flow_enabled, project)

  ::Ai::Catalog::FoundationalFlow
    .select { |flow| filtered_flows.exclude?(flow.foundational_flow_reference.split('/').first) }
    .sort_by(&:id)
end

이 방식으로 특정 티어나 사용자 그룹에만 파운데이셔널 플로를 제공할 수도 있습니다.

버전 관리#

플로 버전은 foundational_flow_reference 속성에 지정하며 GitLab Duo Workflow Service의 Flow Registry 버전에 대응합니다.

• 안정화된 Flow Registry 기능을 사용하는 플로에는 v1을 사용합니다(예시: fix_pipeline/v1)
• Flow Registry 기능의 experimental 버전은 하위 호환성을 전혀 보장하지 않으므로 어떤 파운데이셔널 플로도 사용하지 않습니다

향후 버전 해석은 시맨틱 버저닝을 기반으로 이루어질 예정이며, 이렇게 되면 인스턴스 업데이트 없이도 기존 GitLab 버전에 패치와 마이너 업데이트를 배포할 수 있습니다.

로컬 테스트#

GDK에서 파운데이셔널 플로를 로컬로 테스트할 수 있습니다.

AI Catalog 플로 테스트#

AI Catalog에서 만든 플로는 로컬로 동기화해야 합니다.

1. 로컬 AI Catalog 또는 GitLab.com AI Catalog에서 플로를 만듭니다.

2. $GDK/gitlab-ai-gateway에서 다음 명령을 실행합니다.

   poetry run fetch-foundational-flows "http://gdk.test:3000 or https://gitlab.com" "<token-to-your-local-gdk>" \
     "<flow-reference>:<flow-id-in-local-catalog>" \
     --output-path duo_workflow_service/agent_platform/experimental/flows/configs
   

3. GitLab Duo Workflow Service를 재시작합니다.

   gdk restart duo-workflow-service
   

4. FoundationalFlow 모델을 변경했다면 이제 로컬 웹 인터페이스에서 파운데이셔널 플로를 테스트할 수 있습니다.

GitLab Duo Workflow Service 플로 테스트#

GitLab Duo Workflow Service에 직접 정의한 플로는 다음과 같이 테스트합니다.

1. 로컬 gitlab-ai-gateway 디렉터리의 duo_workflow_service/agent_platform/v1/flows/configs/에 플로 YAML 구성을 만듭니다.

2. GitLab 리포지터리의 ee/app/models/ai/catalog/foundational_flow.rb에 플로 정의를 추가합니다.

3. GitLab Duo Workflow Service를 재시작합니다.

   gdk restart duo-workflow-service
   

4. GitLab UI 또는 API로 플로를 테스트합니다.

디버깅 팁#

• GitLab Duo Workflow Service 로그를 확인합니다: gdk tail duo-workflow-service
• 플로 구성이 로드되었는지 확인합니다: 서비스 시작 로그를 확인합니다
• 플로 실행을 테스트합니다: GitLab UI에서 플로를 트리거하고 실행 과정을 모니터링합니다
• 권한을 검증합니다: 플로에 필요한 에이전트 권한이 있는지 확인합니다
• 더 자세한 디버깅 안내는 Flow Registry 디버깅 문서를 참고합니다

아키텍처 설계#

파운데이셔널 플로는 GitLab이 개발하며 모든 GitLab 배포 형태(GitLab.com, Self-Managed, Dedicated)에서 사용할 수 있어야 합니다.

파운데이셔널 플로를 제공하는 아키텍처는 런타임에 AI Catalog에 연결해 정의를 가져오지 않도록 설계되었으며, GitLab 엔지니어링 팀이 릴리스 시점을 완전히 통제할 수 있게 합니다.

모노리스의 파운데이셔널 플로#

모노리스에 파운데이셔널 플로를 정의하면 하위 호환성과 릴리스 제어를 확보할 수 있습니다. FoundationalFlow 모델을 통해 팀은 GitLab 인스턴스 버전별로 플로 버전을 관리하고, 티어·기능 플래그·배포 유형 같은 조건으로 제공 여부를 제어할 수 있습니다.

GitLab Duo Workflow Service에 번들링#

ai-assist Dockerfile을 통해 플로를 GitLab Duo Workflow Service에 번들로 포함하면 GitLab.com에 접근할 수 없는 자체 호스팅 배포에서도 AI Catalog 플로를 사용할 수 있습니다. 이렇게 하면 모노리스에 YAML 정의를 포함하지 않아도 됩니다. 플로 정의가 모노리스에 있다면 플로 하나를 고치는 데도 GitLab 인스턴스 전체 업데이트를 배포해야 합니다. 정의를 DWS 이미지에 번들로 넣으면 인스턴스 업그레이드 없이 DWS 릴리스만으로 플로 수정을 전달할 수 있습니다.

다음 다이어그램은 플로가 생성된 뒤 실행 중인 인스턴스에서 사용 가능해지기까지의 과정을 보여 줍니다.

%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational flow creation flow
    accDescr: Sequence diagram showing the process of creating a foundational flow from AI Catalog through to GitLab monolith
    participant Team
    participant AI Catalog
    participant DWS Repo as DWS Repository
    participant CI
    participant Monolith
Team->>AI Catalog: Create foundational flow
Team->>DWS Repo: Add flow ID to Dockerfile
DWS Repo->>CI: Trigger build
CI->>AI Catalog: Pull flow definitions
AI Catalog->>CI: Returns all required versions
CI->>CI: Store definitions in DWS image
CI->>CI: Ships images with definitions
Team-&gt;&gt;Monolith: Add flow to FoundationalFlow model</code></pre></details></div>

사용 플로#
Mermaid 다이어그램 (16줄)
소스 코드 보기
%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational flow usage flow
    accDescr: Sequence diagram showing how users interact with foundational flows through GitLab monolith and Duo Workflow Service
    participant User
    participant Monolith
    participant DWS as GitLab Duo Workflow Service
    participant Runner
User-&gt;&gt;Monolith: Trigger foundational flow
Monolith-&gt;&gt;DWS: Request specific flow version
DWS-&gt;&gt;DWS: Resolve flow version
DWS-&gt;&gt;Runner: Execute flow steps
Runner-&gt;&gt;DWS: Return execution results
DWS-&gt;&gt;Monolith: Return response
Monolith-&gt;&gt;User: Display results</code></pre></details></div>

실행 흐름은 사용자가 로컬 모노리스, GitLab SaaS, 클라우드 연결형 DWS, 로컬 설치 DWS 중 무엇을 사용하든 동일합니다.
팁#

코드베이스에 추가하기 전에 AI Catalog에서 플로를 테스트합니다. 동일한 구성으로 private 플로를 만들고 테스트 프로젝트에서 활성화한 다음, 결과가 만족스러울 때까지 반복합니다.
최소한의 에이전트 권한으로 시작하고 필요한 경우에만 권한을 추가합니다.
플로의 목적이 분명히 드러나는 foundational_flow_reference 이름을 사용합니다(예시: fp/v1이 아니라 fix_pipeline/v1).

관련 문서#

파운데이셔널 플로 사용자 문서
파운데이셔널 챗 에이전트 개발 가이드
GitLab Duo Agent Platform 용어집

agent_privileges = [
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_FILES,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_GITLAB,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::RUN_COMMANDS,
  ::Ai::DuoWorkflows::Workflow::AgentPrivileges::USE_GIT
]

triggers: [::Ai::FlowTrigger::EVENT_TYPES[:assign]]

# ee/app/graphql/resolvers/ai/foundational_flows_resolver.rb

def resolve(*, project_id: nil, namespace_id: nil)
  project = GitlabSchema.find_by_gid(project_id)

  filtered_flows = []
  filtered_flows << 'test_flow' if Feature.disabled?(:test_flow_enabled, project)

  ::Ai::Catalog::FoundationalFlow
    .select { |flow| filtered_flows.exclude?(flow.foundational_flow_reference.split('/').first) }
    .sort_by(&:id)
end

%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational flow creation flow
    accDescr: Sequence diagram showing the process of creating a foundational flow from AI Catalog through to GitLab monolith
    participant Team
    participant AI Catalog
    participant DWS Repo as DWS Repository
    participant CI
    participant Monolith
Team->>AI Catalog: Create foundational flow
Team->>DWS Repo: Add flow ID to Dockerfile
DWS Repo->>CI: Trigger build
CI->>AI Catalog: Pull flow definitions
AI Catalog->>CI: Returns all required versions
CI->>CI: Store definitions in DWS image
CI->>CI: Ships images with definitions
Team-&gt;&gt;Monolith: Add flow to FoundationalFlow model</code></pre></details></div>

사용 플로#
Mermaid 다이어그램 (16줄)
소스 코드 보기
%%{init: {"sequence": {"actorMargin": 50}}}%%
sequenceDiagram
    accTitle: Foundational flow usage flow
    accDescr: Sequence diagram showing how users interact with foundational flows through GitLab monolith and Duo Workflow Service
    participant User
    participant Monolith
    participant DWS as GitLab Duo Workflow Service
    participant Runner
User-&gt;&gt;Monolith: Trigger foundational flow
Monolith-&gt;&gt;DWS: Request specific flow version
DWS-&gt;&gt;DWS: Resolve flow version
DWS-&gt;&gt;Runner: Execute flow steps
Runner-&gt;&gt;DWS: Return execution results
DWS-&gt;&gt;Monolith: Return response
Monolith-&gt;&gt;User: Display results</code></pre></details></div>

실행 흐름은 사용자가 로컬 모노리스, GitLab SaaS, 클라우드 연결형 DWS, 로컬 설치 DWS 중 무엇을 사용하든 동일합니다.
팁#

코드베이스에 추가하기 전에 AI Catalog에서 플로를 테스트합니다. 동일한 구성으로 private 플로를 만들고 테스트 프로젝트에서 활성화한 다음, 결과가 만족스러울 때까지 반복합니다.
최소한의 에이전트 권한으로 시작하고 필요한 경우에만 권한을 추가합니다.
플로의 목적이 분명히 드러나는 foundational_flow_reference 이름을 사용합니다(예시: fp/v1이 아니라 fix_pipeline/v1).

관련 문서#

파운데이셔널 플로 사용자 문서
파운데이셔널 챗 에이전트 개발 가이드
GitLab Duo Agent Platform 용어집