InfoGrab DocsInfoGrab Docs

커스텀 플로 YAML 스키마

요약

커스텀 플로는 flow registry v1 사양 구문을 사용합니다. GitLab은 커스텀 플로 정의를 AI 카탈로그 flow_v2.json 스키마에 대해 검증합니다. v1 사양의 일부 필드는 커스텀 플로에서 제한됩니다.

히스토리

커스텀 플로는 flow registry v1 사양 구문을 사용합니다. v1 사양은 version, environment, components, prompts, routers, flow 등의 필드를 포함한 전체 YAML 구조를 정의합니다.

GitLab은 커스텀 플로 정의를 AI 카탈로그 flow_v2.json 스키마에 대해 검증합니다. flow registry v1 사양의 필드 중 flow_v2.json에 정의되지 않은 필드는 사용할 수 없습니다. 이러한 필드를 사용하면 GitLab은 해당 필드를 허용되지 않는 추가 속성으로 거부합니다. 지원되지 않는 필드 목록은 AgentComponent 필드를 참고합니다.

v1 사양의 일부 필드는 커스텀 플로에서 제한됩니다. 자세한 내용은 제한된 필드를 참고합니다.

YAML 구성에는 최대 크기도 있습니다. 자세한 내용은 구성 크기 제한을 참고합니다.

이벤트 유형별 goal 값#

커스텀 플로를 설계할 때 goal 값은 플로를 시작하는 이벤트 유형에 따라 달라집니다. 플로에는 여러 이벤트 유형을 설정할 수 있으며, 각 이벤트 유형은 context:goal로 서로 다른 값을 전달합니다. 플로는 설정한 각 이벤트 유형에 맞는 goal 형식을 처리해야 합니다.

자세한 내용은 이벤트 유형을 참고합니다.

컴포넌트는 inputs 필드를 통해 goal에 접근합니다.

components:
  - name: "my_agent"
    type: AgentComponent
    prompt_id: "my_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - "context:goal"

Mention 이벤트#

사용자가 코멘트에서 플로 서비스 계정을 언급하면, 코멘트 전체 텍스트와 리소스 컨텍스트가 goal로 전달됩니다.

goal은 다음 형식을 사용합니다.

Input: <comment_text>
Context: {<resource_type> IID: <iid>}

예를 들어 사용자가 이슈 #2에 @ai-my-flow Can you work on this?라고 작성하면 goal은 다음과 같습니다.

Input: @ai-my-flow Can you work on this?
Context: {Issue IID: 2}

Assign 및 Assign reviewer 이벤트#

히스토리
  • 유형이 지정된 리소스 참조가 GitLab 19.6에서 ai_flow_trigger_typed_resource_goal이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

플로 서비스 계정이 이슈 또는 머지 리퀘스트의 담당자 또는 검토자로 추가되면 리소스 유형과 URL이 goal로 전달됩니다.

Context:
<resource_type>: <resource_web_url>

리소스 유형은 Issue 또는 MergeRequest입니다.

예를 들어 플로 서비스 계정이 머지 리퀘스트 !10의 검토자로 추가되면 goal은 다음과 같습니다.

Context:
MergeRequest: https://gitlab.example.com/my-group/my-project/-/merge_requests/10

URL로 리소스를 식별합니다. 같은 이슈가 이벤트에 따라 Issue 또는 WorkItem으로 표시될 수 있으므로 리소스 유형은 사용하지 않습니다.

Warning

기능 플래그가 활성화되면 context:goal에 IID 대신 리소스 유형과 URL이 들어갑니다. 커스텀 플로가 계속 작동하도록 context:goal을 IID로 읽는 플로는 모두 업데이트합니다.

머지 리퀘스트 및 작업 항목 이벤트#

히스토리
  • 유형이 지정된 리소스 참조가 GitLab 19.6에서 ai_flow_trigger_typed_resource_goal이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

머지 리퀘스트 또는 작업 항목 이벤트가 플로를 트리거하면 리소스 유형, URL, 액션이 goal로 전달됩니다.

Context:
<resource_type>: <resource_web_url>
Action: <action>

리소스 유형은 MergeRequest 또는 WorkItem입니다.

액션은 이벤트와 Run when 선택에 따라 달라집니다.

이벤트 Run when 액션
Merge request Approved approved
Merge request Created created
Merge request Merged merged
Work item Created created
Work item Status changed status_changed

Marked ready 및 Merge conflict 액션은 goal에 액션을 포함하지 않습니다.

예를 들어 머지 리퀘스트 !10이 승인되면 goal은 다음과 같습니다.

Context:
MergeRequest: https://gitlab.example.com/my-group/my-project/-/merge_requests/10
Action: approved

URL로 리소스를 식별합니다. 같은 이슈가 이벤트에 따라 Issue 또는 WorkItem으로 표시될 수 있으므로 리소스 유형은 사용하지 않습니다.

Warning

기능 플래그가 활성화되면 context:goal에 IID 대신 리소스 유형과 URL이 들어갑니다. 커스텀 플로가 계속 작동하도록 context:goal을 IID로 읽는 플로는 모두 업데이트합니다.

Pipeline 이벤트#

파이프라인 이벤트가 플로를 트리거하면, 전체 파이프라인 이벤트 웹훅 페이로드가 goal로 전달됩니다.

선택적 최상위 속성#

coding_environment#

히스토리
  • GitLab 19.3에서 도입되었습니다.

선택 사항인 coding_environment 속성은 워크로드가 시작될 때 플로에 필요한 코딩 환경의 종류를 선언합니다.

값 설명
full 제공하지 않으면 기본값입니다. 리포지터리 클론, 설정 스크립트, Git 훅, 의존성 캐시를 포함합니다. 리포지터리 파일을 읽거나 쓰는 플로에 사용합니다.
none 리포지터리 클론이 없습니다. 설정 스크립트와 의존성 캐시는 건너뜁니다. 플로는 여전히 프로젝트에 구성된 image에서 실행되므로 해당 이미지에 curl 또는 duo가 포함되어 있어야 합니다. Duo 세션 Git 훅은 여전히 설치되므로, 리포지터리를 직접 클론하는 플로도 커밋이 Duo가 작성한 것으로 유지됩니다. GitLab API하고만 상호작용하며 로컬 리포지터리가 필요 없는 API 전용 플로에 사용합니다. 리포지터리 파일을 읽거나 쓰는 에이전트 도구는 작업할 대상이 없습니다. none 값은 리포지터리 접근을 막지 않습니다. run_command 도구가 있는 플로는 여전히 리포지터리를 직접 클론할 수 있습니다. 이 속성은 플로가 시작되기 전에 GitLab이 준비하는 항목만 제어합니다.

플로에 체크아웃이 필요하면 full 값을 사용합니다. 그러면 클론이 실행 중이 아니라 시작 시점에 한 번만 수행됩니다.

full 또는 none이 아닌 값을 추가하면 스키마 검증이 실패하며 플로가 실행되지 않습니다.

coding_environment 속성을 추가하지 않으면 플로는 전체 환경을 받으며 리포지터리에 계속 접근할 수 있습니다.

예시:

version: v1
environment: ambient
coding_environment: none
components:
  - name: "api_agent"
    type: AgentComponent
    prompt_id: "my_api_prompt"
    inputs:
      - "context:goal"
routers:
  - from: "api_agent"
    to: end
flow:
  entry_point: "api_agent"

include#

히스토리
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다. 이 기능은 테스트용으로 제공되며 프로덕션 환경에서 사용할 준비가 되지 않았습니다.

선택 사항인 include 속성은 플로가 서브에이전트로 사용하는 AI 카탈로그 에이전트를 나열합니다. 각 항목은 에이전트 하나를 항목 ID와 정확한 버전으로 지정합니다. 컴포넌트는 subagents 목록에 항목을 반복해서 적어 해당 항목을 가져갑니다. 컴포넌트는 그 에이전트의 감독자가 되어 에이전트에 작업을 위임할 수 있습니다.

자체 호스팅 AI Gateway를 사용하는 GitLab Self-Managed에서 include에는 AI Gateway 19.6 이상이 필요합니다.

  • AI Gateway 19.5에서는 플로를 저장할 수 있지만, 플로가 서브에이전트 없이 실행되며 오류가 표시되지 않습니다.
  • AI Gateway 19.4 이하에서는 저장이 다음 메시지와 함께 실패합니다. include.0.item_type: Input should be 'agent_template' or 'flow'

감독자는 각 서브에이전트의 이름과 설명을 사용해 어느 서브에이전트에 작업을 맡길지 결정합니다. 세션에도 작업을 받은 에이전트로 이 이름이 표시됩니다. 설명을 작성하는 방법은 커스텀 플로에서 에이전트 사용을 참고합니다.

필드 값
source ai-catalog
item_type agent
item_id 에이전트의 항목 ID이며 문자열입니다.
version 에이전트의 정확한 릴리스 버전이며 문자열입니다. 예: "1.2.0".

예시:

version: v1
environment: ambient
include:
  - source: ai-catalog
    item_type: agent
    item_id: "123"
    version: "1.2.0"
components:
  - name: "coordinator"
    type: AgentComponent
    prompt_id: "coordinator"
    subagents:
      - source: ai-catalog
        item_type: agent
        item_id: "123"
        version: "1.2.0"
routers:
  - from: "coordinator"
    to: end
flow:
  entry_point: "coordinator"

에이전트의 항목 ID와 버전을 찾으려면 AI 카탈로그에서 에이전트를 열거나 관리 프로젝트의 AI > Agents에서 엽니다. 항목 ID는 페이지 URL 끝에 있는 숫자입니다.

다음 규칙이 적용됩니다.

  • 각 항목에는 정확한 버전이 필요합니다. latest와 1.2.* 같은 범위는 허용되지 않습니다.
  • 플로는 에이전트를 최대 20개까지 참조할 수 있으며, 각 에이전트는 한 번만 참조할 수 있습니다.
  • subagents 항목은 include 항목과 필드마다 일치해야 합니다.
  • 플로에서 include 항목을 가져갈 수 있는 컴포넌트는 하나뿐입니다.
  • 에이전트는 플로가 있는 프로젝트에서 사용하도록 설정되어 있지 않아도 됩니다. 플로를 사용하도록 설정하는 사람이 그 시점에 해당 에이전트를 검토합니다.
  • 에이전트는 플로와 최소한 같은 수준으로 공개되어 있어야 합니다. 비공개 에이전트는 같은 관리 프로젝트의 플로에서만 참조할 수 있습니다. 제한된 에이전트는 같은 최상위 그룹의 플로에서만 참조할 수 있습니다. 자세한 내용은 항목 공개 범위를 참고합니다.

플로를 저장하면 GitLab이 모든 항목을 확인합니다. 에이전트가 없거나, 에이전트가 숨겨져 있거나, 에이전트를 볼 수 없거나, 버전이 없거나, 공개 범위 규칙을 충족하지 않으면 저장이 실패합니다. 에이전트가 없거나, 숨겨져 있거나, 볼 수 없는 경우 오류에는 항목 ID와 버전이 표시됩니다. 그 밖의 경우 오류에는 에이전트의 이름이 표시됩니다.

기능 플래그가 비활성화되어 있으면 include가 있는 플로를 만들거나, 그러한 플로의 정의를 변경하거나, 공개 범위를 넓힐 수 없습니다. 이러한 변경을 저장하려면 include 속성과 컴포넌트의 subagents 목록을 제거합니다.

플로가 실행될 때#

플로를 저장한 뒤 에이전트가 바뀔 수 있으므로, GitLab은 플로가 실행될 때 모든 항목을 다시 확인합니다.

  • GitLab Duo 실험 및 베타 기능 설정이 GitLab.com에서는 플로 프로젝트의 최상위 그룹에, GitLab Self-Managed에서는 인스턴스에 켜져 있어야 합니다. 이 설정이 꺼져 있으면 플로는 AI 카탈로그 에이전트 없이 실행됩니다. 항목을 가져간 컴포넌트는 서브에이전트가 없는 에이전트로 실행됩니다.
  • 기능 플래그가 활성화되어 있어야 합니다. 플래그가 비활성화되어 있으면 플로는 이 경우에도 AI 카탈로그 에이전트 없이 실행됩니다.
  • 에이전트를 사용할 수 없으면 세션이 중지됩니다. 에이전트 또는 버전이 더 이상 없거나, 에이전트가 숨겨져 있거나, 에이전트를 볼 수 없거나, 플로 프로젝트의 최상위 그룹에 대해 커스텀 에이전트가 꺼져 있으면 에이전트를 사용할 수 없습니다. 세션에는 다음 메시지가 표시됩니다. This flow stopped because it uses an AI Catalog agent that cannot be used. Check that the agent is published and that you have access to it.
  • 에이전트의 이름이 플로에 있는 컴포넌트의 이름과 일치하면 세션이 중지됩니다. 각 에이전트에는 플로의 어떤 컴포넌트도 사용하지 않는 이름을 지정합니다.
  • 서브에이전트는 정의에 있는 기본 제공 도구만 사용합니다. AI 카탈로그에서 에이전트에 선택한 Model Context Protocol(MCP) 도구는 에이전트가 서브에이전트일 때 사용할 수 없습니다.

제한된 필드#

v1 사양의 일부 필드와 기능은 커스텀 플로가 GitLab에서 일관되게 동작하도록 제한되어 있습니다.

environment#

environment 필드는 커스텀 플로에서 ambient 값만 지원합니다.

chat 및 chat-partial 값은 지원되지 않습니다.

prompts의 model#

prompts 항목 내부의 model 필드는 지원되지 않습니다.

모델은 그룹 또는 인스턴스 설정에서 구성된 모델 공급자에 의해 결정됩니다.

AgentComponent 필드#

v1 사양의 다음 AgentComponent 필드는 지원되지 않습니다.

  • response_schema_id
  • response_schema_version
  • max_cycles
  • max_wrap_up_retries
  • identical_tool_call_limit
  • compaction
  • enable_web_search

이러한 필드를 하나라도 포함하면 플로를 저장할 때 해당 속성이 추가 속성이며 허용되지 않는다는 검증 오류와 함께 저장이 실패합니다. 예를 들면 다음과 같습니다.

Latest version definition object property at `/components/0/max_cycles` is a disallowed additional property
Versions is invalid

OneOffComponent 필드#

ui_role_as 필드는 지원되지 않습니다.

prompt 매개변수의 stop#

params 항목 내부의 stop 필드는 지원되지 않습니다.

최상위 필드#

v1 사양의 name, description, product_group 필드는 지원되지 않습니다. 커스텀 플로는 이 필드들을 거부합니다.

커스텀 플로 YAML 스키마

GitLab v19.6
Tier: [Free](../../../subscriptions/gitlab_credits.md#for-the-free-tier), Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기

요약

커스텀 플로는 flow registry v1 사양 구문을 사용합니다. GitLab은 커스텀 플로 정의를 AI 카탈로그 flow_v2.json 스키마에 대해 검증합니다. v1 사양의 일부 필드는 커스텀 플로에서 제한됩니다.

히스토리

커스텀 플로는 flow registry v1 사양 구문을 사용합니다. v1 사양은 version, environment, components, prompts, routers, flow 등의 필드를 포함한 전체 YAML 구조를 정의합니다.

GitLab은 커스텀 플로 정의를 AI 카탈로그 flow_v2.json 스키마에 대해 검증합니다. flow registry v1 사양의 필드 중 flow_v2.json에 정의되지 않은 필드는 사용할 수 없습니다. 이러한 필드를 사용하면 GitLab은 해당 필드를 허용되지 않는 추가 속성으로 거부합니다. 지원되지 않는 필드 목록은 AgentComponent 필드를 참고합니다.

v1 사양의 일부 필드는 커스텀 플로에서 제한됩니다. 자세한 내용은 제한된 필드를 참고합니다.

YAML 구성에는 최대 크기도 있습니다. 자세한 내용은 구성 크기 제한을 참고합니다.

이벤트 유형별 goal 값#

커스텀 플로를 설계할 때 goal 값은 플로를 시작하는 이벤트 유형에 따라 달라집니다. 플로에는 여러 이벤트 유형을 설정할 수 있으며, 각 이벤트 유형은 context:goal로 서로 다른 값을 전달합니다. 플로는 설정한 각 이벤트 유형에 맞는 goal 형식을 처리해야 합니다.

자세한 내용은 이벤트 유형을 참고합니다.

컴포넌트는 inputs 필드를 통해 goal에 접근합니다.

components:
  - name: "my_agent"
    type: AgentComponent
    prompt_id: "my_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - "context:goal"

Mention 이벤트#

사용자가 코멘트에서 플로 서비스 계정을 언급하면, 코멘트 전체 텍스트와 리소스 컨텍스트가 goal로 전달됩니다.

goal은 다음 형식을 사용합니다.

Input: <comment_text>
Context: {<resource_type> IID: <iid>}

예를 들어 사용자가 이슈 #2에 @ai-my-flow Can you work on this?라고 작성하면 goal은 다음과 같습니다.

Input: @ai-my-flow Can you work on this?
Context: {Issue IID: 2}

Assign 및 Assign reviewer 이벤트#

히스토리
  • 유형이 지정된 리소스 참조가 GitLab 19.6에서 ai_flow_trigger_typed_resource_goal이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

플로 서비스 계정이 이슈 또는 머지 리퀘스트의 담당자 또는 검토자로 추가되면 리소스 유형과 URL이 goal로 전달됩니다.

Context:
<resource_type>: <resource_web_url>

리소스 유형은 Issue 또는 MergeRequest입니다.

예를 들어 플로 서비스 계정이 머지 리퀘스트 !10의 검토자로 추가되면 goal은 다음과 같습니다.

Context:
MergeRequest: https://gitlab.example.com/my-group/my-project/-/merge_requests/10

URL로 리소스를 식별합니다. 같은 이슈가 이벤트에 따라 Issue 또는 WorkItem으로 표시될 수 있으므로 리소스 유형은 사용하지 않습니다.

Warning

기능 플래그가 활성화되면 context:goal에 IID 대신 리소스 유형과 URL이 들어갑니다. 커스텀 플로가 계속 작동하도록 context:goal을 IID로 읽는 플로는 모두 업데이트합니다.

머지 리퀘스트 및 작업 항목 이벤트#

히스토리
  • 유형이 지정된 리소스 참조가 GitLab 19.6에서 ai_flow_trigger_typed_resource_goal이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

머지 리퀘스트 또는 작업 항목 이벤트가 플로를 트리거하면 리소스 유형, URL, 액션이 goal로 전달됩니다.

Context:
<resource_type>: <resource_web_url>
Action: <action>

리소스 유형은 MergeRequest 또는 WorkItem입니다.

액션은 이벤트와 Run when 선택에 따라 달라집니다.

이벤트 Run when 액션
Merge request Approved approved
Merge request Created created
Merge request Merged merged
Work item Created created
Work item Status changed status_changed

Marked ready 및 Merge conflict 액션은 goal에 액션을 포함하지 않습니다.

예를 들어 머지 리퀘스트 !10이 승인되면 goal은 다음과 같습니다.

Context:
MergeRequest: https://gitlab.example.com/my-group/my-project/-/merge_requests/10
Action: approved

URL로 리소스를 식별합니다. 같은 이슈가 이벤트에 따라 Issue 또는 WorkItem으로 표시될 수 있으므로 리소스 유형은 사용하지 않습니다.

Warning

기능 플래그가 활성화되면 context:goal에 IID 대신 리소스 유형과 URL이 들어갑니다. 커스텀 플로가 계속 작동하도록 context:goal을 IID로 읽는 플로는 모두 업데이트합니다.

Pipeline 이벤트#

파이프라인 이벤트가 플로를 트리거하면, 전체 파이프라인 이벤트 웹훅 페이로드가 goal로 전달됩니다.

선택적 최상위 속성#

coding_environment#

히스토리
  • GitLab 19.3에서 도입되었습니다.

선택 사항인 coding_environment 속성은 워크로드가 시작될 때 플로에 필요한 코딩 환경의 종류를 선언합니다.

값 설명
full 제공하지 않으면 기본값입니다. 리포지터리 클론, 설정 스크립트, Git 훅, 의존성 캐시를 포함합니다. 리포지터리 파일을 읽거나 쓰는 플로에 사용합니다.
none 리포지터리 클론이 없습니다. 설정 스크립트와 의존성 캐시는 건너뜁니다. 플로는 여전히 프로젝트에 구성된 image에서 실행되므로 해당 이미지에 curl 또는 duo가 포함되어 있어야 합니다. Duo 세션 Git 훅은 여전히 설치되므로, 리포지터리를 직접 클론하는 플로도 커밋이 Duo가 작성한 것으로 유지됩니다. GitLab API하고만 상호작용하며 로컬 리포지터리가 필요 없는 API 전용 플로에 사용합니다. 리포지터리 파일을 읽거나 쓰는 에이전트 도구는 작업할 대상이 없습니다. none 값은 리포지터리 접근을 막지 않습니다. run_command 도구가 있는 플로는 여전히 리포지터리를 직접 클론할 수 있습니다. 이 속성은 플로가 시작되기 전에 GitLab이 준비하는 항목만 제어합니다.

플로에 체크아웃이 필요하면 full 값을 사용합니다. 그러면 클론이 실행 중이 아니라 시작 시점에 한 번만 수행됩니다.

full 또는 none이 아닌 값을 추가하면 스키마 검증이 실패하며 플로가 실행되지 않습니다.

coding_environment 속성을 추가하지 않으면 플로는 전체 환경을 받으며 리포지터리에 계속 접근할 수 있습니다.

예시:

version: v1
environment: ambient
coding_environment: none
components:
  - name: "api_agent"
    type: AgentComponent
    prompt_id: "my_api_prompt"
    inputs:
      - "context:goal"
routers:
  - from: "api_agent"
    to: end
flow:
  entry_point: "api_agent"

include#

히스토리
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다. 이 기능은 테스트용으로 제공되며 프로덕션 환경에서 사용할 준비가 되지 않았습니다.

선택 사항인 include 속성은 플로가 서브에이전트로 사용하는 AI 카탈로그 에이전트를 나열합니다. 각 항목은 에이전트 하나를 항목 ID와 정확한 버전으로 지정합니다. 컴포넌트는 subagents 목록에 항목을 반복해서 적어 해당 항목을 가져갑니다. 컴포넌트는 그 에이전트의 감독자가 되어 에이전트에 작업을 위임할 수 있습니다.

자체 호스팅 AI Gateway를 사용하는 GitLab Self-Managed에서 include에는 AI Gateway 19.6 이상이 필요합니다.

  • AI Gateway 19.5에서는 플로를 저장할 수 있지만, 플로가 서브에이전트 없이 실행되며 오류가 표시되지 않습니다.
  • AI Gateway 19.4 이하에서는 저장이 다음 메시지와 함께 실패합니다. include.0.item_type: Input should be 'agent_template' or 'flow'

감독자는 각 서브에이전트의 이름과 설명을 사용해 어느 서브에이전트에 작업을 맡길지 결정합니다. 세션에도 작업을 받은 에이전트로 이 이름이 표시됩니다. 설명을 작성하는 방법은 커스텀 플로에서 에이전트 사용을 참고합니다.

필드 값
source ai-catalog
item_type agent
item_id 에이전트의 항목 ID이며 문자열입니다.
version 에이전트의 정확한 릴리스 버전이며 문자열입니다. 예: "1.2.0".

예시:

version: v1
environment: ambient
include:
  - source: ai-catalog
    item_type: agent
    item_id: "123"
    version: "1.2.0"
components:
  - name: "coordinator"
    type: AgentComponent
    prompt_id: "coordinator"
    subagents:
      - source: ai-catalog
        item_type: agent
        item_id: "123"
        version: "1.2.0"
routers:
  - from: "coordinator"
    to: end
flow:
  entry_point: "coordinator"

에이전트의 항목 ID와 버전을 찾으려면 AI 카탈로그에서 에이전트를 열거나 관리 프로젝트의 AI > Agents에서 엽니다. 항목 ID는 페이지 URL 끝에 있는 숫자입니다.

다음 규칙이 적용됩니다.

  • 각 항목에는 정확한 버전이 필요합니다. latest와 1.2.* 같은 범위는 허용되지 않습니다.
  • 플로는 에이전트를 최대 20개까지 참조할 수 있으며, 각 에이전트는 한 번만 참조할 수 있습니다.
  • subagents 항목은 include 항목과 필드마다 일치해야 합니다.
  • 플로에서 include 항목을 가져갈 수 있는 컴포넌트는 하나뿐입니다.
  • 에이전트는 플로가 있는 프로젝트에서 사용하도록 설정되어 있지 않아도 됩니다. 플로를 사용하도록 설정하는 사람이 그 시점에 해당 에이전트를 검토합니다.
  • 에이전트는 플로와 최소한 같은 수준으로 공개되어 있어야 합니다. 비공개 에이전트는 같은 관리 프로젝트의 플로에서만 참조할 수 있습니다. 제한된 에이전트는 같은 최상위 그룹의 플로에서만 참조할 수 있습니다. 자세한 내용은 항목 공개 범위를 참고합니다.

플로를 저장하면 GitLab이 모든 항목을 확인합니다. 에이전트가 없거나, 에이전트가 숨겨져 있거나, 에이전트를 볼 수 없거나, 버전이 없거나, 공개 범위 규칙을 충족하지 않으면 저장이 실패합니다. 에이전트가 없거나, 숨겨져 있거나, 볼 수 없는 경우 오류에는 항목 ID와 버전이 표시됩니다. 그 밖의 경우 오류에는 에이전트의 이름이 표시됩니다.

기능 플래그가 비활성화되어 있으면 include가 있는 플로를 만들거나, 그러한 플로의 정의를 변경하거나, 공개 범위를 넓힐 수 없습니다. 이러한 변경을 저장하려면 include 속성과 컴포넌트의 subagents 목록을 제거합니다.

플로가 실행될 때#

플로를 저장한 뒤 에이전트가 바뀔 수 있으므로, GitLab은 플로가 실행될 때 모든 항목을 다시 확인합니다.

  • GitLab Duo 실험 및 베타 기능 설정이 GitLab.com에서는 플로 프로젝트의 최상위 그룹에, GitLab Self-Managed에서는 인스턴스에 켜져 있어야 합니다. 이 설정이 꺼져 있으면 플로는 AI 카탈로그 에이전트 없이 실행됩니다. 항목을 가져간 컴포넌트는 서브에이전트가 없는 에이전트로 실행됩니다.
  • 기능 플래그가 활성화되어 있어야 합니다. 플래그가 비활성화되어 있으면 플로는 이 경우에도 AI 카탈로그 에이전트 없이 실행됩니다.
  • 에이전트를 사용할 수 없으면 세션이 중지됩니다. 에이전트 또는 버전이 더 이상 없거나, 에이전트가 숨겨져 있거나, 에이전트를 볼 수 없거나, 플로 프로젝트의 최상위 그룹에 대해 커스텀 에이전트가 꺼져 있으면 에이전트를 사용할 수 없습니다. 세션에는 다음 메시지가 표시됩니다. This flow stopped because it uses an AI Catalog agent that cannot be used. Check that the agent is published and that you have access to it.
  • 에이전트의 이름이 플로에 있는 컴포넌트의 이름과 일치하면 세션이 중지됩니다. 각 에이전트에는 플로의 어떤 컴포넌트도 사용하지 않는 이름을 지정합니다.
  • 서브에이전트는 정의에 있는 기본 제공 도구만 사용합니다. AI 카탈로그에서 에이전트에 선택한 Model Context Protocol(MCP) 도구는 에이전트가 서브에이전트일 때 사용할 수 없습니다.

제한된 필드#

v1 사양의 일부 필드와 기능은 커스텀 플로가 GitLab에서 일관되게 동작하도록 제한되어 있습니다.

environment#

environment 필드는 커스텀 플로에서 ambient 값만 지원합니다.

chat 및 chat-partial 값은 지원되지 않습니다.

prompts의 model#

prompts 항목 내부의 model 필드는 지원되지 않습니다.

모델은 그룹 또는 인스턴스 설정에서 구성된 모델 공급자에 의해 결정됩니다.

AgentComponent 필드#

v1 사양의 다음 AgentComponent 필드는 지원되지 않습니다.

  • response_schema_id
  • response_schema_version
  • max_cycles
  • max_wrap_up_retries
  • identical_tool_call_limit
  • compaction
  • enable_web_search

이러한 필드를 하나라도 포함하면 플로를 저장할 때 해당 속성이 추가 속성이며 허용되지 않는다는 검증 오류와 함께 저장이 실패합니다. 예를 들면 다음과 같습니다.

Latest version definition object property at `/components/0/max_cycles` is a disallowed additional property
Versions is invalid

OneOffComponent 필드#

ui_role_as 필드는 지원되지 않습니다.

prompt 매개변수의 stop#

params 항목 내부의 stop 필드는 지원되지 않습니다.

최상위 필드#

v1 사양의 name, description, product_group 필드는 지원되지 않습니다. 커스텀 플로는 이 필드들을 거부합니다.