파운데이셔널 플로우는 에이전트 팀을 오케스트레이션하여 작업을 실행하고 태스크를 완료하는 사전 정의된 구조적인 단계 시퀀스입니다. 이 플로우는 GitLab에서 생성하고 유지 관리하며, 특정 개발 워크플로에 대한 신뢰할 수 있는 자동화를 제공합니다. 파운데이셔널 플로우는 GitLab 전반에 걸쳐 기본적으로 사용 가능하며 GitLab Duo Self-Hosted에서도 지원됩니다. 커스텀 플로우와 달리, 파운데이셔널 플로우는 GitLab이 빌드하고 제공하므로 사용자가 수정할 수 없습니다.

이 가이드는 파운데이셔널 플로우를 다룹니다. 파운데이셔널 에이전트에 대해서는 파운데이셔널 채팅 에이전트 가이드를 참조하세요. 에이전트와 플로우의 차이점을 이해하려면 용어집을 참조하세요.

개요#

파운데이셔널 플로우는 GitLab이 유지 관리하는 AI 기반 워크플로로, 사용자가 소프트웨어 개발 라이프사이클 전반에 걸쳐 개발 태스크를 자동화하는 데 도움을 줍니다. 파운데이셔널 채팅 에이전트(대화형)와 달리, 파운데이셔널 플로우는 다음과 같은 특성을 갖습니다:

• 구조적: 사전 정의된 단계 시퀀스를 따릅니다.

• 자율적: 지속적인 사람의 입력 없이 실행됩니다.

• 태스크 지향적: 특정 반복 가능한 태스크를 완료하도록 설계되었습니다.

• 트리거 기반: 시스템 이벤트 또는 사용자 액션으로 시작할 수 있습니다.

사용 가능한 파운데이셔널 플로우의 전체 목록은 파운데이셔널 플로우 사용자 문서를 참조하세요.

파운데이셔널 플로우 생성#

파운데이셔널 플로우를 생성하는 방법은 두 가지입니다: AI Catalog를 사용하거나 GitLab Duo Workflow Service를 사용하는 방법입니다. AI Catalog는 사용자 친화적인 인터페이스를 제공하는 권장 방법이지만, GitLab Duo Workflow Service에서 직접 정의를 작성하면 복잡한 경우에 더 많은 유연성을 제공합니다.

AI Catalog 사용#

AI Catalog에서 플로우를 생성하고 해당 ID를 기록해 둡니다. 플로우가 public으로 설정되어 있는지 확인하세요. 예시: ID가 123인 플로우.

AI Catalog에서 생성한 플로우는 GitLab Duo Workflow Service에 번들로 포함되어야 하며, 이를 통해 SaaS에 접근할 수 없는 Self-hosted 설정에서도 사용할 수 있습니다. 이를 위해 플로우 ID를 추가하는 MR을 GitLab Duo Workflow Service에 오픈합니다:

# 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).

플로우를 선택 가능하게 하고 사용자가 이용할 수 있도록 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",
  pre_approved_agent_privileges: [
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_FILES,
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB
  ],
  environment: "web",
  triggers: []
}

플로우에 커스텀 아바타가 필요한 경우, PNG 파일을 GitLab SVGs 리포지터리에 추가합니다.

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

GitLab Duo Workflow Service 사용#

/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"

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",
  pre_approved_agent_privileges: [
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_FILES,
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB
  ],
  environment: "web",
  triggers: []
}

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

플로우 정의 속성#

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

에이전트 권한#

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

권한 구성 예시:

pre_approved_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에서 생성한 플로우의 경우, 플로우를 로컬로 동기화해야 합니다:

로컬 AI Catalog 또는 GitLab.com AI Catalog에서 플로우를 생성합니다.

$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

GitLab Duo Workflow Service를 재시작합니다:

gdk restart duo-workflow-service

FoundationalFlow 모델의 변경 사항이 적용되면, 이제 웹 인터페이스에서 로컬로 파운데이셔널 플로우를 테스트할 수 있습니다.

GitLab Duo Workflow Service 플로우 테스트#

GitLab Duo Workflow Service에서 직접 정의한 플로우의 경우:

로컬 gitlab-ai-gateway 디렉터리의 duo_workflow_service/agent_platform/v1/flows/configs/에 플로우 YAML 구성 파일을 생성합니다.

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

GitLab Duo Workflow Service를 재시작합니다:

gdk restart duo-workflow-service

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에 번들링#

플로우를 GitLab Duo Workflow Service에 번들링(ai-assist Dockerfile을 통해)하면 GitLab.com에 접근할 수 없는 Self-hosted 배포에서도 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->>Monolith: Add flow to FoundationalFlow model

사용 플로우#

%%{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->>Monolith: Trigger foundational flow
Monolith->>DWS: Request specific flow version
DWS->>DWS: Resolve flow version
DWS->>Runner: Execute flow steps
Runner->>DWS: Return execution results
DWS->>Monolith: Return response
Monolith->>User: Display results

실행 플로우는 사용자가 로컬 모노리스, GitLab SaaS, 클라우드 연결 DWS 또는 로컬 DWS 설치를 사용하는 경우에도 동일합니다.

팁#

플로우를 코드베이스에 추가하기 전에 AI Catalog에서 테스트하세요. 동일한 구성으로 private 플로우를 생성하고, 테스트 프로젝트에서 활성화한 다음, 결과가 만족스러울 때까지 반복합니다.

최소한의 에이전트 권한으로 시작하고 필요한 경우에만 추가합니다.

플로우의 목적을 명확하게 나타내는 설명적인 foundational_flow_reference 이름을 사용합니다 (예시: fp/v1이 아닌 fix_pipeline/v1).

관련 문서#

• 파운데이셔널 플로우 사용자 문서

• 파운데이셔널 채팅 에이전트 개발 가이드

• GitLab Duo Agent Platform 용어집