InfoGrab DocsInfoGrab Docs

파운데이셔널 플로 관리

요약

파운데이셔널 플로는 에이전트 팀을 조율해 액션을 실행하고 작업을 완료하도록 미리 정의된 구조화된 단계 시퀀스입니다. 이 가이드는 파운데이셔널 플로를 다룹니다. 파운데이셔널 플로는 GitLab이 유지 관리하는 AI 기반 워크플로로, 사용자가 소프트웨어 개발 수명 주기 전반의 개발 작업을 자동화하도록 돕습니다.

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

Note

이 가이드는 파운데이셔널 플로를 다룹니다. 파운데이셔널 에이전트는 파운데이셔널 챗 에이전트 가이드를 참고합니다. 에이전트와 플로의 차이는 용어집을 참고합니다.

개요#

파운데이셔널 플로는 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 모델에 플로를 추가할 때는 다음 속성을 제공해야 합니다.

속성 타입 필수 여부 설명
display_name String 예 사용자에게 표시되는 플로 이름(예시: "Fix CI/CD Pipeline")
description String 예 플로가 수행하는 작업에 대한 간단한 설명
foundational_flow_reference String 예 버전이 포함된 고유 식별자(예시: "fix_pipeline/v1")
feature_maturity String 예 성숙도 수준: "experimental", "beta", "ga" 중 하나
ai_feature String 예 연관된 AI 기능 이름(일반적으로 "duo_agent_platform")
agent_privileges Array 예 필요한 권한(에이전트 권한 참고)
pre_approved_agent_privileges Array 아니요 플로가 승인을 요청하지 않고 사용할 수 있는 agent_privileges의 부분집합. 생략하면 agent_privileges의 모든 권한이 사전 승인됩니다. 명시적인 빈 배열은 아무것도 사전 승인하지 않습니다. 에이전트 권한을 참고합니다.
required_agent_privileges Array 아니요 백그라운드 플로가 시작하는 데 필요한 agent_privileges의 부분집합. 생략하면 agent_privileges의 모든 권한이 필요합니다. 명시적인 빈 배열은 플로가 시작할 때 절대 차단되지 않는다는 뜻입니다. 에이전트 권한을 참고합니다.
allow_agent_to_request_user Boolean 아니요 플로가 일시 중지하고 사용자에게 입력이나 승인을 요청할 수 있는지 여부(기본값: false). 에이전트 권한을 참고합니다.
avatar String 아니요 아이콘 파일 이름(GitLab SVGs에 존재해야 함)
environment String 아니요 실행 환경: "web", "ambient", "cli" 중 하나(기본값: "ambient")
triggers Array 아니요 플로를 트리거할 수 있는 이벤트 타입(기본값: 빈 배열)
coding_environment Enum 아니요 실행 전에 필요한 리포지터리 설정: full 또는 none(기본값: full). full은 체크아웃과 도구를 준비합니다. none은 API 전용 플로를 위해 리포지터리 클론과 설정을 건너뜁니다. 체크아웃이 없으면 Duo CLI는 디스크에서 리포지터리의 AGENTS.md나 스킬을 로드하지 않으며 로컬 Orbit 스킬도 설치되지 않습니다. 플로는 GitLab API 도구로 이 파일을 여전히 읽을 수 있습니다. 커스텀 플로 YAML 스키마를 참고합니다.

세션 수명 주기 훅#

위젯이 읽는 자리 표시자 행처럼 세션 밖에 레코드를 유지하는 플로는 폴링하거나 타이머를 설정하는 대신 세션 자체의 수명 주기에 반응할 수 있습니다. 필요한 훅을 선언합니다. 모든 훅은 선택 사항입니다. 훅이 데이터를 쓸 때는 람다 대신 클래스를 사용하여 훅이 자체 테스트와 소유자를 갖도록 합니다.

속성 실행 시점 실행 방식 호출하는 곳
on_session_created GitLab이 세션을 생성할 때. 동기 Ai::DuoWorkflows::CreateWorkflowService, 인라인
on_session_finished 세션이 성공적으로 완료될 때. 비동기 Ai::DuoWorkflows::SessionLifecycleWorker, Ai::DuoWorkflows::WorkflowFinishedCloudEvent에서
on_session_failed 세션이 중단되어 실패했고 결과를 보고하지 않을 때. 비동기 Ai::DuoWorkflows::SessionLifecycleWorker, Ai::DuoWorkflows::WorkflowFailedEvent에서
on_session_stopped 사용자가 세션을 취소할 때. 비동기 Ai::DuoWorkflows::SessionLifecycleWorker, Ai::DuoWorkflows::WorkflowStoppedEvent에서

동기 훅과 비동기 훅#

동기 훅은 인라인으로 실행됩니다. 세션을 생성하는 코드와 같은 프로세스 및 요청에서 그 호출이 반환되기 전에 실행됩니다. 생성된 세션마다 한 번 실행됩니다.

동기 훅은 실행을 중단할 수 있습니다. 훅이 오류를 발생시키면 GitLab은 오류를 추적하고 세션을 중단하며 실패 이벤트와 감사 이벤트를 기록합니다. 호출자는 could_not_prepare_session 사유가 담긴 오류 응답을 받고 세션은 시작되지 않습니다. 훅이 세션 생성을 차단하므로 빠르게 유지합니다.

비동기 훅은 세션 상태가 바뀐 뒤 나중에 Sidekiq 작업에서 실행됩니다. 상태 변경을 차단하거나 되돌릴 수 없습니다. 전달은 최소 한 번이며 순서가 뒤바뀔 수 있으므로 이러한 훅은 멱등하게 작성해야 합니다.

GitLab이 세션을 생성할 때 코드 실행#

플로가 실행되기 전에 갖춰져 있어야 하는 부수 효과에는 on_session_created를 사용합니다. 예를 들면 위젯이 읽는 자리 표시자 레코드입니다. 실행을 거부하려면 대신 start_request_validator를 사용합니다.

훅은 ->(resource:) 람다이거나 call(resource:)에 응답하는 객체입니다.

on_session_created: ->(resource:) do
  ::MergeRequests::RiskAssessment.ensure_for!(resource)
end

훅은 다음 경우에 실행됩니다.

  • GitLab이 세션 레코드를 저장하고 러너 사전 조건 확인을 통과한 뒤.
  • Ai::DuoWorkflows::CreateWorkflowService의 모든 호출자에 대해. 여기에는 REST API(POST /api/v4/ai/duo_workflows/workflows), Ai::DuoWorkflows::CreateAndStartWorkflowService, 자동화가 포함됩니다.
  • GitLab이 세션을 생성할 때. 이후 세션이 CI에서 시작되지 못하더라도 마찬가지입니다. 훅이 만드는 레코드에는 자체 정리 방법을 마련합니다.

훅은 다음 경우에는 실행되지 않습니다.

  • GitLab이 세션 레코드를 저장할 수 없거나 러너 사전 조건 확인에서 세션이 중단될 때.
  • 세션이 클라이언트에서 실행될 때. 예를 들어 IDE나 CLI가 로컬에서 실행하는 세션입니다. GitLab은 이러한 세션을 실행하지 않으며, 호출자는 플로 카탈로그 항목의 소비자로 인가되지 않습니다.
  • 세션이 재개될 때. 재개는 세션을 생성하지 않기 때문입니다. 재시작은 새 세션을 생성하므로 훅이 다시 실행됩니다.
  • 리소스가 없거나 리소스 유형이 플로의 supported_resource_types에 없을 때.

resource 인수는 호출자가 전달한 리소스입니다. 자동화에서는 자동화를 시작한 이벤트의 리소스입니다. 호출자가 리소스를 전달하지 않았다면 세션의 이슈 또는 머지 리퀘스트입니다.

세션이 끝날 때 코드 실행#

on_session_finished, on_session_failed, on_session_stopped 훅은 비동기입니다. 각각 ->(workflow:) 람다이거나 call(workflow:)에 응답하는 클래스입니다. 필요한 훅만 선언합니다. 취소를 실패와 다르게 처리하는 플로는 둘 다 선언합니다. 실패만 신경 쓰는 플로는 하나만 선언합니다.

훅을 선언하는 것이 해야 할 일의 전부입니다. Ai::DuoWorkflows::SessionLifecycleWorker가 세션이 실행한 플로를 찾아 해당 종료에 대한 훅을 호출합니다. 해당 종료에 대한 훅이 없는 플로는 큐에 추가되지 않습니다. 이 확인은 작업이 아니라 이벤트가 게시될 때 이루어집니다.

이러한 훅은 무엇이 시작했든 모든 세션에 대해 실행됩니다. 중단은 Ai::DuoWorkflows::WorkflowFailedEvent를 게시합니다. 취소는 Ai::DuoWorkflows::WorkflowStoppedEvent를 게시합니다. 두 이벤트 모두 플로 식별자를 담고 있으며, 워커가 이를 통해 사용자의 플로를 찾습니다.

Slack이나 GitLab Duo 노트 같은 메시징 화면에서 시작한 세션은 두 종료 모두에 대해 결합된 Ai::DuoWorkflows::WorkflowFailedEvent도 게시합니다. 이 추가 이벤트는 해당 화면에 응답하는 메시징 콜백을 위한 것입니다. 플로 식별자를 담지 않으므로 훅에는 전달되지 않습니다. 향후 릴리스에서 제거됩니다. 이 작업은 작업 항목 630318에서 추적합니다.

on_session_failed: ->(workflow:) do
  DoSomethingWhenFlowFails.call(workflow)
end

비동기 훅은 다음 규약에 맞게 작성합니다.

  • 멱등하게 만듭니다. 같은 이벤트가 두 번 이상 전달될 수 있습니다.
  • 세션이 훅의 이름이 가리키는 상태에 계속 있다고 가정하지 않습니다. 그 사이에 재시도된 세션이 다시 실행 중일 수 있으므로, 상태에 따라 동작하기 전에 workflow.status_name을 읽습니다.
  • 쓰기에 대한 인가는 직접 처리합니다. 호출자가 workflow_definition을 제공하므로, GitLab이 보증하지 않았더라도 세션이 사용자의 플로를 지정할 수 있습니다.
  • 훅이 항상 실행된다고 가정하지 않습니다. 세션이 삭제되거나 종료되지 않은 상태로 남을 수 있으므로 훅의 레코드에는 자체 정리 방법을 마련합니다.
  • 비용이 적게 들도록 유지합니다. 동작하기 전에 기다려야 한다면 훅이 자체 워커를 예약해야 합니다.

비동기 훅에는 현재 세 가지 종료 지점이 있습니다. on_session_started 훅은 없습니다. Ai::DuoWorkflows::WorkflowStartedEvent가 여전히 메시징 세션에 대해서만 게시되기 때문입니다. 이를 추가하려면 먼저 해당 이벤트를 마이그레이션해야 합니다.

세션이 끝났다고 해서 반드시 플로가 요청한 일을 한 것은 아닙니다. 에이전트가 플로가 의존하는 레코드를 쓰지 않고 실행을 완료할 수 있습니다. 따라서 on_session_finished는 레코드가 있다고 가정하지 않고 그 레코드를 확인해야 합니다.

리소스당 세션을 하나로 제한#

기본적으로 같은 플로의 세션이 같은 리소스에서 이미 실행 중이어도 모든 요청이 새 세션을 시작합니다. 리소스마다 작업을 한 번만 해야 하는 플로는 concurrency를 선언합니다. 그러면 Ai::DuoWorkflows::CreateWorkflowService는 세션이 활성 상태인 동안 해당 리소스에서 같은 플로의 두 번째 세션을 거부합니다.

키 유형 필수 설명
live_statuses Array 예 세션이 리소스를 점유하는 세션 상태입니다. 예: %i[created running].
revision_resolver Lambda 아니요 ->(resource:) 람다 또는 call(resource:)에 응답하는 클래스입니다. 세션이 다루는 리소스의 리비전(예: 머지 리퀘스트의 head 커밋)을 반환하며, 리비전을 알 수 없으면 nil을 반환합니다. GitLab은 이를 각 세션에 기록합니다. supersede와 함께 사용할 때만 검사에 영향을 줍니다.
supersede Boolean 아니요 true이면 새 리비전의 세션이 거부되는 대신 활성 세션을 중지시킵니다. revision_resolver가 필요합니다. 기본값: false.
feature_flag String 아니요 프로젝트 또는 그 최상위 그룹에 대해 제한을 켜는 기능 플래그의 이름입니다. 플래그가 꺼져 있으면 플로의 세션이 나란히 실행됩니다.

키에는 심볼을 사용합니다. 검증기는 다른 키를 거부합니다.

concurrency: {
  live_statuses: %i[created running],
  revision_resolver: ->(resource:) { resource.diff_head_sha },
  supersede: true
}

요청이 세션을 생성할 때 GitLab은 다음을 수행합니다.

  1. 플로와 리소스에 대한 리스를 확보하여 병렬 요청 두 개가 모두 세션을 생성하지 못하게 합니다. 리스가 이미 확보된 것을 발견한 요청은 잠시 기다린 뒤 거부됩니다.
  2. live_statuses의 상태에서 해당 리소스에 대한 플로의 활성 세션을 찾습니다.
  3. 활성 세션이 있으면 새 세션을 거부합니다. supersede를 사용하면 활성 세션은 같은 리비전의 세션이거나 어느 한쪽 리비전을 알 수 없을 때만 새 세션을 거부합니다.
  4. supersede를 사용하면 새 세션을 요청한 사용자가 활성 세션 중 하나를 중지시킬 수 없을 때도 새 세션을 거부합니다.
  5. 새 세션을 저장하고 세션의 플로 메타데이터에 리비전을 기록합니다.
  6. supersede를 사용하면 새 세션이 생성되고 생성 검사를 통과한 뒤 다른 리비전의 활성 세션을 중지시킵니다. GitLab은 새 세션을 요청한 사용자로서 각 세션을 중지시킵니다. 중지하면 해당 세션의 파이프라인이 취소되고 플로의 on_session_stopped 훅이 실행됩니다.

GitLab은 새 세션이 CI에서 시작될 때가 아니라 새 세션을 생성할 때 이전 세션을 중지시킵니다. 이후 새 세션이 시작되지 못하면 다음 요청이 올 때까지 리소스에 활성 세션이 없습니다.

거부된 세션에 대해 CreateWorkflowService는 conflict HTTP 상태의 오류 응답을 반환합니다. 페이로드에는 session_in_flight 사유가 있고, 알 수 있는 경우 활성 세션의 ID가 workflow_id로 포함됩니다. Ai::DuoWorkflows::CreateAndStartWorkflowService는 conflict 상태나 workflow_id 없이 메시지와 session_in_flight 사유만 반환합니다. REST API는 400 상태와 함께 메시지를 반환하고, GraphQL은 메시지만 반환합니다.

플로가 실행되는 방식에 맞게 live_statuses를 선택합니다.

  • 사람 없이 실행되는 플로에는 %i[created running]을 사용합니다. 이 상태에서 멈춘 세션은 자동으로 제거되므로 멈춘 세션이 리소스를 영원히 점유하지 않습니다.
  • 사람을 기다리는 세션이 계속 리소스를 점유해야 할 때만 input_required 또는 plan_approval_required를 추가합니다.

검사는 다음에는 적용되지 않습니다.

  • 리소스가 없거나 리소스 유형이 플로의 supported_resource_types에 없는 세션
  • IDE나 CLI가 실행하는 세션처럼 클라이언트에서 실행되는 세션
  • GitLab Duo 멘션에 응답하는 세션 같은 메시징 세션. 이러한 세션도 리소스를 점유하지 않습니다.
  • 플로의 feature_flag가 프로젝트와 그 최상위 그룹에 대해 꺼져 있을 때

검사는 GitLab이 세션을 생성할 때만 실행됩니다. live_statuses에 있는 상태로 재개하거나 재시도하는 세션은 검사하지 않으므로 다른 활성 세션과 나란히 실행될 수 있습니다.

GitLab은 Rails가 세션을 생성할 때 쓰는 플로 메타데이터에 리비전을 기록합니다. 세션에 대해 GitLab이 플로 메타데이터를 기록하지 않으면 리비전을 알 수 없으므로 해당 세션은 모든 리비전을 다루는 것으로 취급됩니다.

중지된 세션도 이미 생성한 결과를 게시할 수 있습니다. 플로가 결과를 게시한다면 게시하기 전에 세션의 상태를 확인합니다.

에이전트 권한#

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

권한 설명
READ_WRITE_FILES 로컬 파일시스템 읽기/쓰기 접근을 허용합니다
READ_ONLY_GITLAB GitLab API에 대한 읽기 전용 접근을 허용합니다
READ_WRITE_GITLAB GitLab API에 대한 쓰기 접근을 허용합니다
RUN_COMMANDS 임의의 명령 실행을 허용합니다
USE_GIT Git 커밋, 푸시 및 기타 Git 명령을 허용합니다
RUN_MCP_TOOLS MCP 도구 실행을 허용합니다

권한 구성 예시입니다.

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
]

agent_privileges는 플로가 사용할 수 있는 상한을 설정하고, pre_approved_agent_privileges는 그 권한 중 플로가 승인을 위해 일시 중지하지 않고 사용할 수 있는 부분집합입니다. 부분집합이므로 pre_approved_agent_privileges는 agent_privileges가 부여하지 않은 권한을 포함해서는 안 됩니다. pre_approved_agent_privileges가 nil이면 agent_privileges로 대체되므로 부여된 모든 권한이 사전 승인되고, 명시적인 빈 배열 []은 아무것도 사전 승인하지 않습니다. 부여되었지만 사전 승인되지 않은 권한은 실행 중인 워크플로를 일시 중지하고 승인 필요 상태로 만들 수 있지만, 이는 실행 화면과 Duo Workflow Service 플로 구성이 승인을 지원할 때만 해당합니다. allow_agent_to_request_user 설정(모델 기본값 false)은 플로가 일시 중지하고 사용자에게 물어볼 수 있음을 선언하므로, 메시징 화면처럼 사용자에게 보이는 이어가기 경로가 있는 플로에만 true로 설정합니다. Duo Workflow Service 플로 구성도 가능한 곳에서 require_tool_approval: true처럼 승인 처리를 켜야 하므로, 이 설정만으로 승인 프롬프트가 켜지지는 않습니다.

예를 들어 다음 플로는 읽기, 쓰기, 플로 시작 권한을 부여하지만 읽기만 사전 승인합니다.

{
  display_name: "Slack Assistant",
  foundational_flow_reference: "slack_assistant/v1",
  agent_privileges: [
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB,
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_GITLAB,
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::START_FLOWS
  ],
  pre_approved_agent_privileges: [
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB
  ],
  allow_agent_to_request_user: true,
  environment: "ambient",
  coding_environment: "none",
  triggers: []
}

읽기 작업은 승인 없이 실행되고, 쓰기 작업과 다른 플로 시작은 부여된 상태로 남지만 승인이 필요합니다. coding_environment: "none" 값은 플로에 준비된 리포지터리 체크아웃이 필요하지 않다는 뜻입니다.

백그라운드 환경에서는 플로가 필요로 하는 권한 그룹의 모든 도구를 관리자가 거부하면 플로가 시작되지 않습니다. required_agent_privileges는 플로가 필요로 하는 권한을 설정하며, agent_privileges가 부여하지 않은 권한을 포함해서는 안 됩니다. required_agent_privileges가 nil이면 agent_privileges로 대체되므로 부여된 모든 권한이 필요합니다. 플로가 자체 툴셋에서 사용하지 않는 권한을 부여할 때 required_agent_privileges를 설정합니다. 예를 들어 Developer 플로는 워크스페이스 서브에이전트에 GitLab 및 Git 권한을 부여하지만 READ_WRITE_FILES와 RUN_COMMANDS만 필요로 합니다.

트리거#

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

  • ::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, GitLab 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 릴리스만으로 플로 수정을 전달할 수 있습니다.

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

Mermaid 다이어그램 (18줄)
소스 코드 보기
%%{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-&gt;&gt;AI Catalog: Create foundational flow
Team-&gt;&gt;DWS Repo: Add flow ID to Dockerfile
DWS Repo-&gt;&gt;CI: Trigger build
CI-&gt;&gt;AI Catalog: Pull flow definitions
AI Catalog-&gt;&gt;CI: Returns all required versions
CI-&gt;&gt;CI: Store definitions in DWS image
CI-&gt;&gt;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 중 무엇을 사용하든 동일합니다.

팁#

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

관련 문서#

파운데이셔널 플로 관리

GitLab v19.6
원문 보기

요약

파운데이셔널 플로는 에이전트 팀을 조율해 액션을 실행하고 작업을 완료하도록 미리 정의된 구조화된 단계 시퀀스입니다. 이 가이드는 파운데이셔널 플로를 다룹니다. 파운데이셔널 플로는 GitLab이 유지 관리하는 AI 기반 워크플로로, 사용자가 소프트웨어 개발 수명 주기 전반의 개발 작업을 자동화하도록 돕습니다.

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

Note

이 가이드는 파운데이셔널 플로를 다룹니다. 파운데이셔널 에이전트는 파운데이셔널 챗 에이전트 가이드를 참고합니다. 에이전트와 플로의 차이는 용어집을 참고합니다.

개요#

파운데이셔널 플로는 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 모델에 플로를 추가할 때는 다음 속성을 제공해야 합니다.

속성 타입 필수 여부 설명
display_name String 예 사용자에게 표시되는 플로 이름(예시: "Fix CI/CD Pipeline")
description String 예 플로가 수행하는 작업에 대한 간단한 설명
foundational_flow_reference String 예 버전이 포함된 고유 식별자(예시: "fix_pipeline/v1")
feature_maturity String 예 성숙도 수준: "experimental", "beta", "ga" 중 하나
ai_feature String 예 연관된 AI 기능 이름(일반적으로 "duo_agent_platform")
agent_privileges Array 예 필요한 권한(에이전트 권한 참고)
pre_approved_agent_privileges Array 아니요 플로가 승인을 요청하지 않고 사용할 수 있는 agent_privileges의 부분집합. 생략하면 agent_privileges의 모든 권한이 사전 승인됩니다. 명시적인 빈 배열은 아무것도 사전 승인하지 않습니다. 에이전트 권한을 참고합니다.
required_agent_privileges Array 아니요 백그라운드 플로가 시작하는 데 필요한 agent_privileges의 부분집합. 생략하면 agent_privileges의 모든 권한이 필요합니다. 명시적인 빈 배열은 플로가 시작할 때 절대 차단되지 않는다는 뜻입니다. 에이전트 권한을 참고합니다.
allow_agent_to_request_user Boolean 아니요 플로가 일시 중지하고 사용자에게 입력이나 승인을 요청할 수 있는지 여부(기본값: false). 에이전트 권한을 참고합니다.
avatar String 아니요 아이콘 파일 이름(GitLab SVGs에 존재해야 함)
environment String 아니요 실행 환경: "web", "ambient", "cli" 중 하나(기본값: "ambient")
triggers Array 아니요 플로를 트리거할 수 있는 이벤트 타입(기본값: 빈 배열)
coding_environment Enum 아니요 실행 전에 필요한 리포지터리 설정: full 또는 none(기본값: full). full은 체크아웃과 도구를 준비합니다. none은 API 전용 플로를 위해 리포지터리 클론과 설정을 건너뜁니다. 체크아웃이 없으면 Duo CLI는 디스크에서 리포지터리의 AGENTS.md나 스킬을 로드하지 않으며 로컬 Orbit 스킬도 설치되지 않습니다. 플로는 GitLab API 도구로 이 파일을 여전히 읽을 수 있습니다. 커스텀 플로 YAML 스키마를 참고합니다.

세션 수명 주기 훅#

위젯이 읽는 자리 표시자 행처럼 세션 밖에 레코드를 유지하는 플로는 폴링하거나 타이머를 설정하는 대신 세션 자체의 수명 주기에 반응할 수 있습니다. 필요한 훅을 선언합니다. 모든 훅은 선택 사항입니다. 훅이 데이터를 쓸 때는 람다 대신 클래스를 사용하여 훅이 자체 테스트와 소유자를 갖도록 합니다.

속성 실행 시점 실행 방식 호출하는 곳
on_session_created GitLab이 세션을 생성할 때. 동기 Ai::DuoWorkflows::CreateWorkflowService, 인라인
on_session_finished 세션이 성공적으로 완료될 때. 비동기 Ai::DuoWorkflows::SessionLifecycleWorker, Ai::DuoWorkflows::WorkflowFinishedCloudEvent에서
on_session_failed 세션이 중단되어 실패했고 결과를 보고하지 않을 때. 비동기 Ai::DuoWorkflows::SessionLifecycleWorker, Ai::DuoWorkflows::WorkflowFailedEvent에서
on_session_stopped 사용자가 세션을 취소할 때. 비동기 Ai::DuoWorkflows::SessionLifecycleWorker, Ai::DuoWorkflows::WorkflowStoppedEvent에서

동기 훅과 비동기 훅#

동기 훅은 인라인으로 실행됩니다. 세션을 생성하는 코드와 같은 프로세스 및 요청에서 그 호출이 반환되기 전에 실행됩니다. 생성된 세션마다 한 번 실행됩니다.

동기 훅은 실행을 중단할 수 있습니다. 훅이 오류를 발생시키면 GitLab은 오류를 추적하고 세션을 중단하며 실패 이벤트와 감사 이벤트를 기록합니다. 호출자는 could_not_prepare_session 사유가 담긴 오류 응답을 받고 세션은 시작되지 않습니다. 훅이 세션 생성을 차단하므로 빠르게 유지합니다.

비동기 훅은 세션 상태가 바뀐 뒤 나중에 Sidekiq 작업에서 실행됩니다. 상태 변경을 차단하거나 되돌릴 수 없습니다. 전달은 최소 한 번이며 순서가 뒤바뀔 수 있으므로 이러한 훅은 멱등하게 작성해야 합니다.

GitLab이 세션을 생성할 때 코드 실행#

플로가 실행되기 전에 갖춰져 있어야 하는 부수 효과에는 on_session_created를 사용합니다. 예를 들면 위젯이 읽는 자리 표시자 레코드입니다. 실행을 거부하려면 대신 start_request_validator를 사용합니다.

훅은 ->(resource:) 람다이거나 call(resource:)에 응답하는 객체입니다.

on_session_created: ->(resource:) do
  ::MergeRequests::RiskAssessment.ensure_for!(resource)
end

훅은 다음 경우에 실행됩니다.

  • GitLab이 세션 레코드를 저장하고 러너 사전 조건 확인을 통과한 뒤.
  • Ai::DuoWorkflows::CreateWorkflowService의 모든 호출자에 대해. 여기에는 REST API(POST /api/v4/ai/duo_workflows/workflows), Ai::DuoWorkflows::CreateAndStartWorkflowService, 자동화가 포함됩니다.
  • GitLab이 세션을 생성할 때. 이후 세션이 CI에서 시작되지 못하더라도 마찬가지입니다. 훅이 만드는 레코드에는 자체 정리 방법을 마련합니다.

훅은 다음 경우에는 실행되지 않습니다.

  • GitLab이 세션 레코드를 저장할 수 없거나 러너 사전 조건 확인에서 세션이 중단될 때.
  • 세션이 클라이언트에서 실행될 때. 예를 들어 IDE나 CLI가 로컬에서 실행하는 세션입니다. GitLab은 이러한 세션을 실행하지 않으며, 호출자는 플로 카탈로그 항목의 소비자로 인가되지 않습니다.
  • 세션이 재개될 때. 재개는 세션을 생성하지 않기 때문입니다. 재시작은 새 세션을 생성하므로 훅이 다시 실행됩니다.
  • 리소스가 없거나 리소스 유형이 플로의 supported_resource_types에 없을 때.

resource 인수는 호출자가 전달한 리소스입니다. 자동화에서는 자동화를 시작한 이벤트의 리소스입니다. 호출자가 리소스를 전달하지 않았다면 세션의 이슈 또는 머지 리퀘스트입니다.

세션이 끝날 때 코드 실행#

on_session_finished, on_session_failed, on_session_stopped 훅은 비동기입니다. 각각 ->(workflow:) 람다이거나 call(workflow:)에 응답하는 클래스입니다. 필요한 훅만 선언합니다. 취소를 실패와 다르게 처리하는 플로는 둘 다 선언합니다. 실패만 신경 쓰는 플로는 하나만 선언합니다.

훅을 선언하는 것이 해야 할 일의 전부입니다. Ai::DuoWorkflows::SessionLifecycleWorker가 세션이 실행한 플로를 찾아 해당 종료에 대한 훅을 호출합니다. 해당 종료에 대한 훅이 없는 플로는 큐에 추가되지 않습니다. 이 확인은 작업이 아니라 이벤트가 게시될 때 이루어집니다.

이러한 훅은 무엇이 시작했든 모든 세션에 대해 실행됩니다. 중단은 Ai::DuoWorkflows::WorkflowFailedEvent를 게시합니다. 취소는 Ai::DuoWorkflows::WorkflowStoppedEvent를 게시합니다. 두 이벤트 모두 플로 식별자를 담고 있으며, 워커가 이를 통해 사용자의 플로를 찾습니다.

Slack이나 GitLab Duo 노트 같은 메시징 화면에서 시작한 세션은 두 종료 모두에 대해 결합된 Ai::DuoWorkflows::WorkflowFailedEvent도 게시합니다. 이 추가 이벤트는 해당 화면에 응답하는 메시징 콜백을 위한 것입니다. 플로 식별자를 담지 않으므로 훅에는 전달되지 않습니다. 향후 릴리스에서 제거됩니다. 이 작업은 작업 항목 630318에서 추적합니다.

on_session_failed: ->(workflow:) do
  DoSomethingWhenFlowFails.call(workflow)
end

비동기 훅은 다음 규약에 맞게 작성합니다.

  • 멱등하게 만듭니다. 같은 이벤트가 두 번 이상 전달될 수 있습니다.
  • 세션이 훅의 이름이 가리키는 상태에 계속 있다고 가정하지 않습니다. 그 사이에 재시도된 세션이 다시 실행 중일 수 있으므로, 상태에 따라 동작하기 전에 workflow.status_name을 읽습니다.
  • 쓰기에 대한 인가는 직접 처리합니다. 호출자가 workflow_definition을 제공하므로, GitLab이 보증하지 않았더라도 세션이 사용자의 플로를 지정할 수 있습니다.
  • 훅이 항상 실행된다고 가정하지 않습니다. 세션이 삭제되거나 종료되지 않은 상태로 남을 수 있으므로 훅의 레코드에는 자체 정리 방법을 마련합니다.
  • 비용이 적게 들도록 유지합니다. 동작하기 전에 기다려야 한다면 훅이 자체 워커를 예약해야 합니다.

비동기 훅에는 현재 세 가지 종료 지점이 있습니다. on_session_started 훅은 없습니다. Ai::DuoWorkflows::WorkflowStartedEvent가 여전히 메시징 세션에 대해서만 게시되기 때문입니다. 이를 추가하려면 먼저 해당 이벤트를 마이그레이션해야 합니다.

세션이 끝났다고 해서 반드시 플로가 요청한 일을 한 것은 아닙니다. 에이전트가 플로가 의존하는 레코드를 쓰지 않고 실행을 완료할 수 있습니다. 따라서 on_session_finished는 레코드가 있다고 가정하지 않고 그 레코드를 확인해야 합니다.

리소스당 세션을 하나로 제한#

기본적으로 같은 플로의 세션이 같은 리소스에서 이미 실행 중이어도 모든 요청이 새 세션을 시작합니다. 리소스마다 작업을 한 번만 해야 하는 플로는 concurrency를 선언합니다. 그러면 Ai::DuoWorkflows::CreateWorkflowService는 세션이 활성 상태인 동안 해당 리소스에서 같은 플로의 두 번째 세션을 거부합니다.

키 유형 필수 설명
live_statuses Array 예 세션이 리소스를 점유하는 세션 상태입니다. 예: %i[created running].
revision_resolver Lambda 아니요 ->(resource:) 람다 또는 call(resource:)에 응답하는 클래스입니다. 세션이 다루는 리소스의 리비전(예: 머지 리퀘스트의 head 커밋)을 반환하며, 리비전을 알 수 없으면 nil을 반환합니다. GitLab은 이를 각 세션에 기록합니다. supersede와 함께 사용할 때만 검사에 영향을 줍니다.
supersede Boolean 아니요 true이면 새 리비전의 세션이 거부되는 대신 활성 세션을 중지시킵니다. revision_resolver가 필요합니다. 기본값: false.
feature_flag String 아니요 프로젝트 또는 그 최상위 그룹에 대해 제한을 켜는 기능 플래그의 이름입니다. 플래그가 꺼져 있으면 플로의 세션이 나란히 실행됩니다.

키에는 심볼을 사용합니다. 검증기는 다른 키를 거부합니다.

concurrency: {
  live_statuses: %i[created running],
  revision_resolver: ->(resource:) { resource.diff_head_sha },
  supersede: true
}

요청이 세션을 생성할 때 GitLab은 다음을 수행합니다.

  1. 플로와 리소스에 대한 리스를 확보하여 병렬 요청 두 개가 모두 세션을 생성하지 못하게 합니다. 리스가 이미 확보된 것을 발견한 요청은 잠시 기다린 뒤 거부됩니다.
  2. live_statuses의 상태에서 해당 리소스에 대한 플로의 활성 세션을 찾습니다.
  3. 활성 세션이 있으면 새 세션을 거부합니다. supersede를 사용하면 활성 세션은 같은 리비전의 세션이거나 어느 한쪽 리비전을 알 수 없을 때만 새 세션을 거부합니다.
  4. supersede를 사용하면 새 세션을 요청한 사용자가 활성 세션 중 하나를 중지시킬 수 없을 때도 새 세션을 거부합니다.
  5. 새 세션을 저장하고 세션의 플로 메타데이터에 리비전을 기록합니다.
  6. supersede를 사용하면 새 세션이 생성되고 생성 검사를 통과한 뒤 다른 리비전의 활성 세션을 중지시킵니다. GitLab은 새 세션을 요청한 사용자로서 각 세션을 중지시킵니다. 중지하면 해당 세션의 파이프라인이 취소되고 플로의 on_session_stopped 훅이 실행됩니다.

GitLab은 새 세션이 CI에서 시작될 때가 아니라 새 세션을 생성할 때 이전 세션을 중지시킵니다. 이후 새 세션이 시작되지 못하면 다음 요청이 올 때까지 리소스에 활성 세션이 없습니다.

거부된 세션에 대해 CreateWorkflowService는 conflict HTTP 상태의 오류 응답을 반환합니다. 페이로드에는 session_in_flight 사유가 있고, 알 수 있는 경우 활성 세션의 ID가 workflow_id로 포함됩니다. Ai::DuoWorkflows::CreateAndStartWorkflowService는 conflict 상태나 workflow_id 없이 메시지와 session_in_flight 사유만 반환합니다. REST API는 400 상태와 함께 메시지를 반환하고, GraphQL은 메시지만 반환합니다.

플로가 실행되는 방식에 맞게 live_statuses를 선택합니다.

  • 사람 없이 실행되는 플로에는 %i[created running]을 사용합니다. 이 상태에서 멈춘 세션은 자동으로 제거되므로 멈춘 세션이 리소스를 영원히 점유하지 않습니다.
  • 사람을 기다리는 세션이 계속 리소스를 점유해야 할 때만 input_required 또는 plan_approval_required를 추가합니다.

검사는 다음에는 적용되지 않습니다.

  • 리소스가 없거나 리소스 유형이 플로의 supported_resource_types에 없는 세션
  • IDE나 CLI가 실행하는 세션처럼 클라이언트에서 실행되는 세션
  • GitLab Duo 멘션에 응답하는 세션 같은 메시징 세션. 이러한 세션도 리소스를 점유하지 않습니다.
  • 플로의 feature_flag가 프로젝트와 그 최상위 그룹에 대해 꺼져 있을 때

검사는 GitLab이 세션을 생성할 때만 실행됩니다. live_statuses에 있는 상태로 재개하거나 재시도하는 세션은 검사하지 않으므로 다른 활성 세션과 나란히 실행될 수 있습니다.

GitLab은 Rails가 세션을 생성할 때 쓰는 플로 메타데이터에 리비전을 기록합니다. 세션에 대해 GitLab이 플로 메타데이터를 기록하지 않으면 리비전을 알 수 없으므로 해당 세션은 모든 리비전을 다루는 것으로 취급됩니다.

중지된 세션도 이미 생성한 결과를 게시할 수 있습니다. 플로가 결과를 게시한다면 게시하기 전에 세션의 상태를 확인합니다.

에이전트 권한#

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

권한 설명
READ_WRITE_FILES 로컬 파일시스템 읽기/쓰기 접근을 허용합니다
READ_ONLY_GITLAB GitLab API에 대한 읽기 전용 접근을 허용합니다
READ_WRITE_GITLAB GitLab API에 대한 쓰기 접근을 허용합니다
RUN_COMMANDS 임의의 명령 실행을 허용합니다
USE_GIT Git 커밋, 푸시 및 기타 Git 명령을 허용합니다
RUN_MCP_TOOLS MCP 도구 실행을 허용합니다

권한 구성 예시입니다.

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
]

agent_privileges는 플로가 사용할 수 있는 상한을 설정하고, pre_approved_agent_privileges는 그 권한 중 플로가 승인을 위해 일시 중지하지 않고 사용할 수 있는 부분집합입니다. 부분집합이므로 pre_approved_agent_privileges는 agent_privileges가 부여하지 않은 권한을 포함해서는 안 됩니다. pre_approved_agent_privileges가 nil이면 agent_privileges로 대체되므로 부여된 모든 권한이 사전 승인되고, 명시적인 빈 배열 []은 아무것도 사전 승인하지 않습니다. 부여되었지만 사전 승인되지 않은 권한은 실행 중인 워크플로를 일시 중지하고 승인 필요 상태로 만들 수 있지만, 이는 실행 화면과 Duo Workflow Service 플로 구성이 승인을 지원할 때만 해당합니다. allow_agent_to_request_user 설정(모델 기본값 false)은 플로가 일시 중지하고 사용자에게 물어볼 수 있음을 선언하므로, 메시징 화면처럼 사용자에게 보이는 이어가기 경로가 있는 플로에만 true로 설정합니다. Duo Workflow Service 플로 구성도 가능한 곳에서 require_tool_approval: true처럼 승인 처리를 켜야 하므로, 이 설정만으로 승인 프롬프트가 켜지지는 않습니다.

예를 들어 다음 플로는 읽기, 쓰기, 플로 시작 권한을 부여하지만 읽기만 사전 승인합니다.

{
  display_name: "Slack Assistant",
  foundational_flow_reference: "slack_assistant/v1",
  agent_privileges: [
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB,
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_WRITE_GITLAB,
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::START_FLOWS
  ],
  pre_approved_agent_privileges: [
    ::Ai::DuoWorkflows::Workflow::AgentPrivileges::READ_ONLY_GITLAB
  ],
  allow_agent_to_request_user: true,
  environment: "ambient",
  coding_environment: "none",
  triggers: []
}

읽기 작업은 승인 없이 실행되고, 쓰기 작업과 다른 플로 시작은 부여된 상태로 남지만 승인이 필요합니다. coding_environment: "none" 값은 플로에 준비된 리포지터리 체크아웃이 필요하지 않다는 뜻입니다.

백그라운드 환경에서는 플로가 필요로 하는 권한 그룹의 모든 도구를 관리자가 거부하면 플로가 시작되지 않습니다. required_agent_privileges는 플로가 필요로 하는 권한을 설정하며, agent_privileges가 부여하지 않은 권한을 포함해서는 안 됩니다. required_agent_privileges가 nil이면 agent_privileges로 대체되므로 부여된 모든 권한이 필요합니다. 플로가 자체 툴셋에서 사용하지 않는 권한을 부여할 때 required_agent_privileges를 설정합니다. 예를 들어 Developer 플로는 워크스페이스 서브에이전트에 GitLab 및 Git 권한을 부여하지만 READ_WRITE_FILES와 RUN_COMMANDS만 필요로 합니다.

트리거#

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

  • ::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, GitLab 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 릴리스만으로 플로 수정을 전달할 수 있습니다.

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

Mermaid 다이어그램 (18줄)
소스 코드 보기
%%{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-&gt;&gt;AI Catalog: Create foundational flow
Team-&gt;&gt;DWS Repo: Add flow ID to Dockerfile
DWS Repo-&gt;&gt;CI: Trigger build
CI-&gt;&gt;AI Catalog: Pull flow definitions
AI Catalog-&gt;&gt;CI: Returns all required versions
CI-&gt;&gt;CI: Store definitions in DWS image
CI-&gt;&gt;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 중 무엇을 사용하든 동일합니다.

팁#

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

관련 문서#