InfoGrab DocsInfoGrab Docs

Flow Registry Framework v1

요약

Flow Registry Framework v1을 사용하면 하나의 YAML 파일에 컴포넌트, 도구, 라우팅 로직을 정의하여 GitLab Duo Agent Platform에서 AI 기반 커스텀 워크플로를 구축할 수 있습니다.

Flow Registry Framework v1을 사용하면 하나의 YAML 파일에 컴포넌트, 도구, 라우팅 로직을 정의하여 GitLab Duo Agent Platform에서 AI 기반 커스텀 워크플로를 구축할 수 있습니다.

YAML 구성 구조#

모든 플로는 하나의 YAML 파일입니다. 최상위 구조는 다음과 같습니다.

version: "v1"
environment: ambient

components:
  # List of components (see Component types)

routers:
  # Routing rules between components (see Routers)

flow:
  entry_point: "component_name"   # First component to run

prompts:                           # Optional - inline prompt definitions
  # Locally defined prompts (see Prompts)

필수 필드#

필드 설명
version 항상 "v1"입니다.
environment 플로의 상호작용 방식입니다. 환경을 참고합니다.
components 플로를 구성하는 컴포넌트 목록입니다. 컴포넌트 유형을 참고합니다.
routers 컴포넌트 간 라우팅 규칙입니다. 라우터를 참고합니다.
flow 진입점과 선택적 컨텍스트 입력입니다. flow 섹션을 참고합니다.

선택 필드#

필드 설명
name 사람이 읽을 수 있는 플로 이름입니다.
description 플로 설명입니다.
product_group 담당 팀입니다(예: agent_foundations).
prompts 인라인 프롬프트 정의입니다. 로컬에서 정의한 프롬프트를 참고합니다.
response_schemas 인라인 응답 스키마 정의입니다. 응답 스키마를 참고합니다.

환경#

environment 필드는 사람과 AI가 상호작용하는 정도를 선언합니다.

값 설명
ambient 사람의 개입 없이 백그라운드에서 실행합니다. 사람이 작업을 위임하면 에이전트가 자율적으로 실행합니다. 사람의 참여를 최소화합니다. 대부분의 커스텀 플로에 이 값을 사용합니다.
chat 채팅과 같은 인터페이스를 통해 주고받는 대화형 상호작용입니다.
chat-partial 단일 에이전트 플로용으로 단순화한 chat 변형입니다. 보일러플레이트를 건너뜁니다. AgentComponent가 정확히 하나 있어야 합니다.

빠른 시작#

플로를 호출하려면 StartWorkflowRequest에 플로 구성을 전달합니다.

flowConfigId: "<your_flow_id>"
flowConfigSchemaVersion: "v1"
flowVersion: "1.0.0"

이 페이지의 나머지 부분은 플로 구성의 YAML 구조를 설명합니다. 코드베이스에 새 기반 플로를 등록하는 방법은 기반 플로 개발자 가이드를 참고합니다.

세션 컨텍스트 변수#

모든 컴포넌트의 inputs 블록은 from: "context:<key>"를 사용해 세션 컨텍스트에서 값을 가져옵니다. 프레임워크는 항상 사용할 수 있는 변수 집합을 자동으로 채웁니다. 이 변수들을 선언할 필요는 없지만, 각 컴포넌트의 inputs 블록에서 명시적으로 참조해야 합니다.

항상 사용할 수 있는 변수#

변수 유형 설명
context:goal string 워크플로를 시작시킨 사용자의 목표 또는 메시지입니다.
context:project_id string GitLab 프로젝트 ID입니다(숫자이며 문자열로 전달됩니다).
context:project_http_url_to_repo string 리포지터리의 전체 HTTPS 클론 URL입니다.
Note

context:project_id는 프롬프트 템플릿에 자동으로 주입되지 않습니다. 에이전트가 GitLab API 도구(예: get_merge_request, list_issues, create_merge_request)를 호출한다면, 이 값을 컴포넌트의 inputs에 추가하고 프롬프트의 user: 블록에 Project ID: {{ project_id }}를 포함해야 합니다. 이를 빠뜨리는 것이 플로 실패의 가장 흔한 원인입니다.

Agent Platform 표준 컨텍스트 변수#

이 변수들은 flow.inputs 항목을 선언한 경우에만 사용할 수 있습니다. CI 러너가 주입하는 브랜치와 세션 메타데이터를 담고 있습니다.

변수 유형 설명
context:inputs.agent_platform_standard_context.primary_branch string 리포지터리의 기본 브랜치입니다(예: main).
context:inputs.agent_platform_standard_context.workload_branch string CI 워크로드 러너가 사용하는 Git ref입니다.
context:inputs.agent_platform_standard_context.session_owner_id string 플로를 실행한 사용자의 GitLab 사용자 ID입니다.

플로가 브랜치를 만들거나, 머지 리퀘스트를 열거나, 기본 브랜치를 알아야 할 때 이 변수들을 선언합니다. 자세한 내용은 flow 섹션을 참고합니다.

flow 섹션#

flow 섹션은 진입점과, 선택적으로 주입할 외부 컨텍스트 카테고리를 정의합니다.

최소 구성#

flow:
  entry_point: "my_first_component"

Agent Platform 표준 컨텍스트 사용#

플로에 primary_branch, workload_branch, session_owner_id가 필요할 때 필수입니다.

flow:
  entry_point: "create_feature_branch"
  inputs:
    - category: agent_platform_standard_context
      input_schema:
        primary_branch:
          type: string
          description: The default/primary branch of the repository (for example, 'main', 'master')
        workload_branch:
          type: string
          description: git ref to workload branch
        session_owner_id:
          type: string
          description: Human user's ID that initiated the flow

컴포넌트 유형#

컴포넌트 용도 AI 사용 사용 시점
AgentComponent 도구를 사용하는 다중 턴 AI 추론 예 반복적인 의사 결정, 대화, 다단계 도구 사용이 필요한 복잡한 작업.
OneOffComponent 단일 라운드 AI 도구 실행 예 내장 재시도 로직과 함께 LLM 호출 한 번으로 완료할 수 있는 한정된 작업.
DeterministicStepComponent 고정된 인수로 단일 도구 실행 아니요 도구 인수를 상태에서 바로 가져오는, 예측 가능하고 반복 가능한 작업.
HumanInputComponent 사용자 입력 요청 및 처리 아니요 승인 게이트, 대화형 채팅 등 사람의 피드백이 필요한 모든 지점.
EndComponent / AbortComponent 워크플로 종료 아니요 모든 플로는 "end"(성공) 또는 "abort"(오류)로 종료해야 합니다.

AgentComponent#

AgentComponent는 AI 기반 플로의 핵심 구성 요소입니다. LLM을 사용해 다음을 수행합니다.

  • 입력을 처리합니다.
  • 프롬프트를 바탕으로 의사 결정을 합니다.
  • 도구를 호출합니다.
  • 대화 기록을 유지합니다.
  • 다운스트림 컴포넌트에 전달할 출력을 생성합니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "AgentComponent"여야 합니다.
prompt_id 프롬프트 템플릿의 ID입니다(로컬 또는 레지스트리 기반).

선택 매개변수#

매개변수 기본값 설명
prompt_version 생략 Semver 제약 조건입니다(예: "^1.0.0"). 로컬에서 정의한 프롬프트를 사용하려면 생략합니다.
inputs ["context:goal"] 입력 데이터 소스 목록입니다.
toolset [] 에이전트가 사용할 수 있는 도구입니다. 사용 가능한 도구를 참고합니다.
description None 감독자 아래의 하위 에이전트로 사용할 때 필수입니다.
subagents None 하위 에이전트 이름 목록 또는 AI Catalog 에이전트용 include 항목입니다(include 참고). 감독자 모드를 활성화합니다.
max_delegations 무제한 감독자 모드에서 delegate_task를 호출할 수 있는 최대 횟수입니다.
response_schema_id None 구조화된 출력 스키마의 ID입니다.
response_schema_version None 레지스트리 기반 스키마의 Semver입니다.
model_size_preference null "small" 또는 "large"입니다.
require_tool_approval false 각 도구를 호출하기 전에 일시 중지하고 사람의 승인을 기다립니다.
pre_approved_tools [] 승인 단계를 건너뛰는 도구입니다.
compaction None 대화 압축 구성입니다.
ui_log_events [] UI에 표시할 이벤트입니다. UI 로그 이벤트를 참고합니다.
ui_role_as "agent" UI에 표시할 역할입니다("agent" 또는 "tool").

출력#

출력 키 설명
context:{name}.final_answer 에이전트의 최종 응답입니다(문자열이며, 커스텀 스키마를 사용하면 dict입니다).
context:{name}.final_answer.{field} 커스텀 응답 스키마를 사용할 때의 개별 필드입니다.
conversation_history:{name} 전체 메시지 기록입니다.

입력#

컴포넌트 입력은 세션 컨텍스트에서 값을 가져와 프롬프트의 템플릿 변수로 사용할 수 있게 합니다. as: 별칭은 프롬프트 템플릿의 {{ variable }} 자리 표시자와 정확히 일치해야 합니다.

# In the component inputs:
inputs:
  - from: "context:goal"
    as: "goal"
  - from: "context:project_id"
    as: "project_id"
  - from: "context:previous_agent.final_answer"
    as: "previous_result"
  - from: "some constant value"
    as: "my_constant"
    literal: true

# In the prompt user block:
user: |
  Project ID: {{ project_id }}
  Goal: {{ goal }}
  Previous result: {{ previous_result }}

프롬프트#

모든 AgentComponent에는 프롬프트가 필요합니다. 플로 YAML에 인라인으로 정의하거나(커스텀 플로에 권장), AI Gateway 프롬프트 레지스트리에 있는 프롬프트를 참조합니다.

로컬에서 정의한 프롬프트#

최상위 prompts 블록에 정의한 인라인 프롬프트를 사용하려면 prompt_version을 생략합니다.

components:
  - name: "my_agent"
    type: AgentComponent
    prompt_id: "my_prompt"
    # prompt_version omitted - uses local prompt

prompts:
  - prompt_id: "my_prompt"
    name: "My Prompt"
    unit_primitives: []           # always include, even if empty
    prompt_template:
      system: |
        You are a helpful assistant.

        When your task is complete, your final answer is a plain text summary
        of what you did. No further steps are needed after that.
      user: |
        Project ID: {{ project_id }}
        Goal: {{ goal }}
      placeholder: history        # include explicitly
    params:
      timeout: 180

레지스트리 프롬프트#

ai_gateway/prompts/definitions/의 AI Gateway 프롬프트 레지스트리에서 불러오려면 prompt_version을 지정합니다.

components:
  - name: "my_agent"
    type: AgentComponent
    prompt_id: "my_flow/my_prompt"
    prompt_version: "^1.0.0"

프롬프트 작성 모범 사례#

  • 에이전트에게 작업이 끝나는 시점을 항상 알려 줍니다. 명시적인 종료 지시가 없으면 에이전트가 반복 실행됩니다. 모든 system: 프롬프트를 다음과 같은 문장으로 끝냅니다. "When [condition], your final answer is [what to say]. No further steps are needed after that."
  • GitLab API 도구를 호출하는 에이전트에는 항상 user: 블록에 project_id를 전달합니다. 에이전트는 이 값을 스스로 알아낼 수 없습니다.
  • 변수 이름을 정확히 일치시킵니다. inputs의 as: 별칭은 프롬프트 템플릿의 {{ variable }} 자리 표시자와 일치해야 합니다.
  • 인라인 프롬프트에는 비어 있더라도 항상 unit_primitives: []를 포함합니다.
  • 인라인 프롬프트 템플릿에는 항상 placeholder: history를 포함합니다.

사용 가능한 도구#

toolset에 snake_case 이름을 전달해 도구를 구성합니다. 전체 목록은 duo_workflow_service/components/tools_registry.py에 있습니다. 일반적인 예는 다음과 같습니다.

  • 파일 작업: read_file, create_file_with_contents, edit_file, list_dir, find_files, grep
  • Git 작업: run_command, create_merge_request, create_branch
  • GitLab API: get_issue, list_issues, get_merge_request, gitlab_merge_request_search, get_work_item, get_repository_file, list_repository_tree, create_issue_note, create_merge_request_note, create_commit, gitlab_api_get, get_project

도구 옵션#

LLM이 변경할 수 없도록 컴포넌트 수준에서 도구의 매개변수를 재정의합니다.

toolset:
  - "get_merge_request"                    # simple string - no overrides
  - "create_merge_request_note":           # object form - override a parameter
      "internal": true

옵션은 초기화 시점에 도구의 Pydantic 입력 스키마와 대조해 검증합니다. 옵션 키가 유효한 매개변수와 일치하지 않으면 ValueError가 발생합니다. 실행 시점에는 도구 옵션이 LLM이 제공한 값보다 우선합니다.

AgentComponent UI 로그 이벤트#

이벤트 설명
on_agent_final_answer 에이전트가 최종 응답을 호출합니다. 세션 UI와 CI 로그에서 최종 응답 전체를 볼 수 있습니다. 출력에 민감한 데이터가 포함된 경우 비활성화합니다.
on_tool_execution_success 도구 호출이 성공적으로 완료되었습니다.
on_tool_execution_failed 도구 호출이 실패했습니다.
on_tool_approval_request 도구 승인이 사용자의 결정을 기다리고 있습니다. UI에 승인 요청을 표시하려면 반드시 포함해야 합니다.

도구 승인#

require_tool_approval: true이면 에이전트가 도구 호출을 생성한 뒤 워크플로가 일시 중지되고, 사용자의 결정을 기다린 다음 진행합니다.

다음 결정 유형을 지원합니다.

결정 동작
APPROVE 도구가 정상적으로 실행됩니다.
REJECT 거부 메시지가 기록에 추가되고, 에이전트가 다른 접근 방식을 시도합니다.
MODIFY 거부와 사용자 피드백이 기록에 추가되고, 에이전트가 이에 맞게 조정합니다.

다음 중 하나에 해당하면 도구가 사전 승인되어 승인 단계를 건너뜁니다.

  • 컴포넌트 수준: 컴포넌트의 pre_approved_tools 매개변수에 나열된 경우입니다. YAML에서 플로 작성자가 제어합니다.
  • 워크플로 수준: 워크플로 startRequest의 pre_approved_agent_privileges로 지정한 경우입니다. 호출 시점에 워크플로 호출자가 제어합니다.

두 경로 중 어느 쪽에서든 모든 도구 호출이 사전 승인되면 승인 흐름을 완전히 건너뛰고 도구가 즉시 실행됩니다.

components:
  - name: "code_editor"
    type: AgentComponent
    prompt_id: "code_assistant"
    prompt_version: "^1.0.0"
    require_tool_approval: true
    pre_approved_tools: ["read_file", "list_dir", "find_files"]
    toolset: ["read_file", "list_dir", "find_files", "edit_file", "run_command"]
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
      - "on_tool_approval_request"
    inputs: ["context:goal"]

사용 모드#

모드 시점 description 필수 여부
Standalone 플로의 일반 컴포넌트입니다. 아니요
Managed 감독자가 위임하는 하위 에이전트입니다. 예
Supervisor delegate_task를 통해 하위 에이전트를 조율합니다. 아니요(감독자 자체에는 필요 없음)

감독자 모드#

subagents를 제공하면 에이전트가 감독자가 되어 delegate_task와 final_response_tool을 자동으로 사용할 수 있습니다. LLM이 delegate_task를 호출하면 프레임워크는 다음을 수행합니다.

  1. 지정한 하위 에이전트에 번호가 매겨진 하위 세션을 할당하거나 재개합니다.
  2. 위임 프롬프트로 하위 에이전트의 대화 기록을 채웁니다.
  3. 실행을 하위 에이전트의 ReAct 루프로 라우팅합니다.
  4. 하위 에이전트가 완료되면 결과를 감독자의 기록에 다시 주입하고 제어권을 감독자에게 돌려줍니다.

제약 조건#

  • subagents에는 항목이 하나 이상 있어야 합니다.
  • 나열된 모든 하위 에이전트에는 description 필드가 있어야 합니다.
  • AgentComponent는 최대 한 명의 감독자만 소유할 수 있습니다.
  • 감독자 프롬프트는 delegate_task와 final_response_tool을 언제 사용할지 LLM에 지시해야 합니다.

감독자 출력#

출력 키 설명
context:{supervisor_name}.final_answer 감독자의 최종 응답입니다.
conversation_history:{supervisor_name} 감독자 자신의 메시지 기록입니다.

응답 스키마#

응답 스키마는 AgentComponent의 출력을 구조화된 형식으로 제한합니다. 스키마가 없으면 에이전트는 final_answer에 일반 문자열을 반환합니다. 스키마가 있으면 final_answer는 dict이며, 각 필드는 context:{name}.final_answer.{field}로도 접근할 수 있습니다.

인라인 스키마(커스텀 플로에 권장)#

components:
  - name: "code_reviewer"
    type: AgentComponent
    prompt_id: "code_review_prompt"
    response_schema_id: "code_review"   # no response_schema_version = inline lookup
    toolset: ["read_file"]

response_schemas:
  - schema_id: "code_review"
    definition:
      "$schema": "http://json-schema.org/draft-07/schema#"
      title: "code_review_response"
      type: object
      properties:
        summary:
          type: string
          description: "Brief summary of findings"
        overall_score:
          type: integer
          minimum: 1
          maximum: 10
      required: [summary, overall_score]

레지스트리 스키마#

response_schema_id와 response_schema_version을 모두 지정하면 ai_gateway/response_schemas/definitions/의 서버 측 레지스트리에서 불러옵니다.

components:
  - name: "code_reviewer"
    type: AgentComponent
    prompt_id: "code_review/detailed_analysis"
    prompt_version: "^1.0.0"
    response_schema_id: "analysis/code_review"
    response_schema_version: "^1.0.0"

다운스트림 컴포넌트는 개별 스키마 필드를 참조할 수 있습니다.

inputs:
  - from: "context:code_reviewer.final_answer.overall_score"
    as: "score"

스키마 정의 참조#

응답 스키마는 JSON Schema 형식을 사용합니다. 중요한 최상위 필드는 다음과 같습니다.

필드 설명
$schema 스키마 방언입니다. 지정하지 않으면 기본값은 draft-07입니다.
title 에이전트가 최종 응답을 위해 호출하는 도구 이름에 대응합니다. 기존 도구 이름과 일치하면 안 되며, 충돌하면 ValueError가 발생합니다.
type 반드시 "object"여야 합니다.
properties 스키마 필드를 정의하는 중첩 JSON 객체입니다. 중첩 구조를 위해 "object" 유형을 지원합니다.
required 출력에 반드시 있어야 하는 필드 이름 목록입니다.

AgentComponent 응답 스키마는 다음 JSON Schema 검증 제약 조건을 지원합니다.

숫자 제약 조건(integer/number)#
JSON Schema 제약 조건 Pydantic 필드 매개변수 설명
minimum ge= 최솟값(포함)입니다. 이상입니다.
maximum le= 최댓값(포함)입니다. 이하입니다.
exclusiveMinimum gt= 최솟값(미포함)입니다. 초과입니다.
exclusiveMaximum lt= 최댓값(미포함)입니다. 미만입니다.
multipleOf multiple_of= 값이 이 숫자의 배수여야 합니다.
문자열 제약 조건#
JSON Schema 제약 조건 Pydantic 필드 매개변수 설명
minLength min_length= 문자열의 최소 길이(문자 수)입니다.
maxLength max_length= 문자열의 최대 길이(문자 수)입니다.
pattern pattern= 문자열이 일치해야 하는 정규 표현식 패턴입니다.
배열 제약 조건#
JSON Schema 제약 조건 Pydantic 필드 매개변수 설명
minItems min_length= 배열의 최소 항목 수입니다.
maxItems max_length= 배열의 최대 항목 수입니다.
열거형과 상수#
JSON Schema 제약 조건 Python 유형 설명
enum Literal[val1, val2, ...] 필드가 지정한 값 중 하나여야 합니다.
const Literal[value] 필드가 정확히 이 값이어야 합니다.
메타데이터#
JSON Schema 필드 Pydantic 필드 매개변수 설명
default default= 선택 필드의 기본값입니다.
examples examples= 에이전트에 지침으로 보여 주는 예시 값입니다.
전체 스키마 예시#
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "code_review_response_tool",
    "type": "object",
    "properties": {
        "summary": {
            "type": "string",
            "description": "Brief summary of the code review findings"
        },
        "issues_found": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "severity": {
                        "type": "string",
                        "enum": ["low", "medium", "high", "critical"]
                    },
                    "description": { "type": "string" },
                    "file_path": { "type": "string" },
                    "line_number": { "type": "integer" }
                },
                "required": ["severity", "description"]
            }
        },
        "recommendations": {
            "type": "array",
            "items": { "type": "string" }
        },
        "overall_score": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10
        }
    },
    "required": ["summary", "issues_found", "overall_score"]
}

AgentComponent 예시#

components:
  - name: "code_assistant"
    type: AgentComponent
    prompt_id: "code_review_helper"
    prompt_version: "^1.0.0"
    inputs: ["context:goal"]
    require_tool_approval: true
    pre_approved_tools: ["read_file", "list_dir", "find_files"]
    toolset:
      - "read_file"
      - "list_dir"
      - "find_files"
      - "create_file_with_contents"
      - "create_merge_request_note":
          "internal": true
      - "edit_file"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
    ui_role_as: "agent"

HumanInputComponent#

HumanInputComponent는 다음을 수행합니다.

  • 워크플로 실행을 일시 중지합니다.
  • 사람에게 프롬프트를 표시합니다.
  • 사람이 응답하면 재개합니다.

검토 게이트, 승인, 피드백 루프에 사용합니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "HumanInputComponent"여야 합니다.
sends_response_to 사람의 응답을 대화 기록에서 받는 AgentComponent의 이름입니다. 이미 실행된 컴포넌트여야 합니다.
message_template 사람에게 표시하는 Jinja2 템플릿입니다. inputs를 통해 변수를 참조할 수 있습니다.

선택 매개변수#

매개변수 기본값 설명
interaction_type "approval" "approval"은 Approve/Reject/Modify 버튼을 표시합니다. "input"은 텍스트 입력란을 표시합니다. 기본값에 의존하지 말고 항상 명시적으로 설정합니다.
inputs [] message_template에 렌더링할 변수입니다.
ui_log_events [] UI 로그 이벤트를 항상 둘 다 포함해야 합니다.

핵심 제약 조건: sends_response_to는 이미 실행된 컴포넌트를 가리켜야 함#

Note

HumanInputComponent에서 가장 흔히 오해하는 필드입니다.

프레임워크는 대상 컴포넌트의 기존 대화 기록에 사람의 피드백을 주입합니다. 해당 컴포넌트가 아직 실행되지 않았다면 대화 기록 항목이 없으므로 프레임워크가 KeyError('<component_name>')와 함께 중단됩니다.

Note

sends_response_to는 게이트가 동작하기 전에 이미 실행을 마친 컴포넌트의 이름이어야 합니다.

실제로는 거의 항상 게이트 바로 앞에서 실행된 에이전트를 다시 가리키게 됩니다.

modify 라우트의 대상이 아직 실행되지 않았다면, 대신 해당 대상의 inputs를 통해 피드백을 전달합니다.

# Correct pattern - sends_response_to points to the already-run agent
- name: "review_gate"
  type: HumanInputComponent
  sends_response_to: "suggester_agent"    # suggester already ran ✅
  interaction_type: "approval"
  ...

# The modify handler gets feedback through inputs instead:
- name: "modify_handler"
  type: AgentComponent
  inputs:
    - from: "context:review_gate.approval"
      as: "human_feedback"               # feedback passed explicitly ✅
# Wrong pattern - crashes with KeyError
- name: "review_gate"
  sends_response_to: "modify_handler"    # has not run yet → KeyError ❌

UI 로그 이벤트#

두 이벤트를 모두 포함해야 합니다. 포함하지 않으면 세션 UI에서 게이트가 보이지 않습니다.

이벤트 설명
on_user_input_prompt 프롬프트를 표시하고 올바른 입력 컨트롤(버튼 또는 텍스트 상자)을 렌더링합니다.
on_user_response 사람의 응답을 UI 채팅 로그에 기록합니다.

출력#

출력 키 설명
context:{name}.approval 사람의 결정입니다: "approve", "reject", "modify" 중 하나입니다.
conversation_history:{sends_response_to} 대상 에이전트의 기록에 주입된 사람의 메시지입니다.

승인 라우터: 값은 두 개가 아니라 세 개#

interaction_type: "approval"이면 사람이 세 가지 값으로 응답할 수 있습니다. 라우터가 세 값을 모두 처리해야 하며, 그렇지 않으면 modify 경로가 조용히 default_route로 넘어갑니다.

값 의미
"approve" 사람이 수락했습니다. 다음 단계로 진행합니다.
"reject" 사람이 거부했습니다. 종료 또는 오류 처리로 라우팅합니다.
"modify" 사람이 피드백을 제공했습니다. 수정을 위해 이전 에이전트로 되돌려 라우팅합니다.
routers:
  - from: "review_gate"
    condition:
      input: "context:review_gate.approval"
      routes:
        "approve": "next_step"
        "modify": "prior_agent"      # loop back - feedback available in history or inputs
        "reject": "end"
        "default_route": "end"       # always include a fallback

HumanInputComponent 체크리스트#

YAML을 저장하기 전에 다음을 확인합니다.

  • interaction_type이 명시적으로 설정되어 있습니다("approval" 또는 "input").
  • ui_log_events에 "on_user_input_prompt"와 "on_user_response"가 모두 포함되어 있습니다.
  • 다운스트림 라우터가 to:가 아니라 condition:을 사용합니다.
  • 라우터가 "approve", "modify", "reject"를 명시적으로 처리합니다.
  • 라우터에 "default_route"가 있습니다.
  • sends_response_to가 게이트가 동작하기 전에 이미 실행된 컴포넌트를 가리킵니다.
  • modify 대상이 아직 실행되지 않았다면, 해당 대상의 inputs에 from: "context:{gate_name}.approval" as: "human_feedback"가 포함되어 있습니다.

사용 패턴#

승인 워크플로#

components:
  - name: "user_approval"
    type: HumanInputComponent
    sends_response_to: "proposal_agent"   # proposal_agent already ran
    interaction_type: "approval"
    message_template: |
      Please review the proposed changes and choose an action:
      - ✅ Approve: Proceed
      - ✏️ Modify: Provide feedback for revision
      - ❌ Reject: Discard
    ui_log_events:
      - "on_user_input_prompt"
      - "on_user_response"

routers:
  - from: "user_approval"
    condition:
      input: "context:user_approval.approval"
      routes:
        "approve": "executor"
        "modify": "proposal_agent"
        "reject": "end"
        "default_route": "end"

대화형 채팅#

components:
  - name: "user_input"
    type: HumanInputComponent
    sends_response_to: "chat_agent"
    interaction_type: "input"
    message_template: "How can I help you today?"
    ui_log_events:
      - "on_user_input_prompt"
      - "on_user_response"

routers:
  - from: "user_input"
    to: "chat_agent"
  - from: "chat_agent"
    to: "user_input"  # loop back for continued interaction

DeterministicStepComponent#

LLM 개입 없이 단일 도구를 직접 실행합니다. 매개변수는 플로 상태에서 추출합니다. 여러 인스턴스를 연결해 순차적인 도구 작업을 실행할 수 있습니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "DeterministicStepComponent"여야 합니다.
tool_name 실행할 단일 도구의 이름입니다.

선택 매개변수#

매개변수 기본값 설명
toolset 자동 도구가 들어 있는 툴셋입니다(생략하면 자동으로 생성됩니다).
inputs [] 도구 매개변수에 매핑되는 입력 소스입니다.
ui_log_events [] UI에 표시할 이벤트입니다.
ui_role_as "tool" UI에 표시할 역할입니다.

출력#

출력 키 설명
context:{name}.tool_responses 도구 실행 결과입니다.
context:{name}.error 발생한 오류입니다.
context:{name}.execution_result "success" 또는 "failed"입니다.

검증#

컴포넌트는 초기화 시점에 도구 인수를 검증합니다.

  • 지정한 도구가 툴셋에 있는지 확인합니다.
  • 필요한 모든 도구 매개변수가 inputs에 구성되어 있는지 확인합니다.
  • 매개변수가 도구의 예상 스키마와 일치하는지 확인합니다.

오류는 런타임이 아니라 구성 시점에 포착됩니다.

예시: 여러 도구 연결#

components:
  - name: "read_config"
    type: DeterministicStepComponent
    inputs:
      - from: "context:goal"
        as: "config_path"
    tool_name: "read_file"
    ui_log_events:
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

  - name: "backup_config"
    type: DeterministicStepComponent
    inputs:
      - from: "context:read_config.tool_responses"
        as: "contents"
      - from: "config_backup.txt"
        as: "file_path"
        literal: true
    tool_name: "create_file_with_contents"

OneOffComponent#

AgentComponent와 DeterministicStepComponent의 중간에 위치합니다. LLM을 사용해 한 번의 라운드로 도구 호출을 생성한 다음 성공하면 종료합니다. 실패한 실행에 대한 내장 재시도 로직을 포함합니다.

LLM 호출 한 번으로 작업을 끝낼 수 있지만, 도구 매개변수를 정하는 데 LLM의 추론이 도움이 될 때 사용합니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "OneOffComponent"여야 합니다.
prompt_id 도구 호출을 지시하는 프롬프트입니다.
toolset 단일 라운드에서 사용할 수 있는 도구입니다.

선택 매개변수#

매개변수 기본값 설명
prompt_version 생략 로컬에서 정의한 프롬프트를 사용하려면 생략합니다.
inputs ["context:goal"] 입력 데이터 소스입니다.
max_correction_attempts 3 실패한 도구 실행의 재시도 한도입니다.
model_size_preference null "small" 또는 "large"입니다.
compaction None 대화 압축 구성입니다.
ui_log_events [] UI에 표시할 이벤트입니다.

출력#

출력 키 설명
context:{name}.tool_responses 도구 실행 결과입니다.
context:{name}.tool_calls 수행한 도구 호출 기록입니다.
context:{name}.execution_result "success" 또는 "failed"입니다.

UI 로그 이벤트#

이벤트 설명
on_tool_call_input 도구가 인수와 함께 호출되려는 시점입니다.
on_tool_execution_success 도구가 성공적으로 완료되었습니다.
on_tool_execution_failed 도구 실행이 실패했습니다.
on_agent_reasoning 제한 때문에 에이전트가 도구 호출을 생성하지 못했습니다.

내부 아키텍처#

OneOffComponent는 내부 노드 세 개로 구성됩니다.

  • LLM 노드({name}#llm): AgentNode를 사용해 도구 호출을 하나 이상 생성합니다.
  • 도구 노드({name}#tools): ToolNodeWithErrorCorrection을 통해 오류 수정과 함께 도구 호출을 실행합니다.
  • 종료 노드({name}#exit): 완료 처리와 상태 로깅을 담당합니다.

예시#

components:
  - name: "file_reader"
    type: OneOffComponent
    prompt_id: "read_specific_file"
    prompt_version: "^1.0.0"
    inputs:
      - from: "context:goal"
        as: "target_file"
    toolset:
      - "read_file"
    max_correction_attempts: 2
    ui_log_events:
      - "on_tool_call_input"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

EndComponent와 AbortComponent#

둘 다 모든 플로에서 자동으로 사용할 수 있습니다. 별도로 정의할 필요가 없습니다.

이름 라우터 키 설정되는 상태 사용 시점
EndComponent "end" COMPLETED 워크플로가 성공적으로 완료되었습니다.
AbortComponent "abort" ERROR 복구할 수 없는 오류가 발생했거나 재시도를 모두 소진했습니다.
routers:
  - from: "my_component"
    to: "end"    # successful completion

  - from: "my_component"
    to: "abort"  # error termination

라우터#

라우터는 각 컴포넌트가 완료된 후 실행이 컴포넌트 사이를 어떻게 이동할지 정의합니다.

단순 라우터#

조건 없이 다음 컴포넌트로 라우팅합니다.

routers:
  - from: "component_a"
    to: "component_b"

조건부 라우터#

컨텍스트 변수의 값에 따라 라우팅합니다.

routers:
  - from: "component_a"
    condition:
      input: "context:component_a.final_answer"
      routes:
        "approved": "component_b"
        "rejected": "end"
        "default_route": "end"   # fallback if value matches nothing

조용히 막다른 길에 빠지는 일을 막으려면 항상 "default_route"를 포함합니다.

흔한 함정#

증상 근본 원인 해결 방법
에이전트가 프로젝트를 찾을 수 없다고 하거나 프로젝트 컨텍스트가 없다고 합니다 컴포넌트 inputs에 project_id가 없습니다 GitLab API 도구를 호출하는 모든 컴포넌트에 - from: "context:project_id" as: "project_id"를 추가하고, user: 블록에 Project ID: {{ project_id }}를 포함합니다.
primary_branch가 정의되지 않았습니다 flow.inputs 항목이 없습니다 agent_platform_standard_context 스키마를 포함한 flow.inputs 블록 전체를 추가합니다.
HITL 게이트가 UI에 아무것도 표시하지 않습니다 HumanInputComponent에 ui_log_events가 없습니다 ui_log_events에 on_user_input_prompt와 on_user_response를 추가합니다.
modify 시 KeyError('<component_name>')가 발생합니다 sends_response_to가 아직 실행되지 않은 컴포넌트를 가리킵니다. sends_response_to를 가장 최근에 완료된 에이전트로 지정하고, modify 대상에는 inputs를 통해 피드백을 전달합니다.
modify 응답이 예기치 않게 default_route로 라우팅됩니다 라우터에 "modify" 라우트가 없습니다 HumanInputComponent 뒤의 모든 조건부 라우터에 "modify": "<target_component>"를 추가합니다.
에이전트가 끝없이 반복합니다 프롬프트에 종료 지시가 없습니다 모든 system: 프롬프트를 명시적인 완료 지시로 끝냅니다.
세션 시작 시 NoneType: None 오류로 중단됩니다 에이전트 시스템 프롬프트에 {{ }} Jinja2 구문이 있습니다 플랫폼은 시스템 프롬프트를 모델에 전달하기 전에 Jinja2로 렌더링합니다. 프롬프트 텍스트의 {{ variable }}은 모두 템플릿 변수로 처리됩니다. 문서에서는 <<variable>> 표기를 사용하거나 {{ }}로 이스케이프합니다.
로드 시 YAML 구문 분석 오류가 발생합니다 인라인 프롬프트에 unit_primitives: []가 없습니다 비어 있더라도 항상 unit_primitives: []를 포함합니다.
에이전트가 빈 변수를 받습니다 as: 별칭이 {{ }} 자리 표시자와 일치하지 않습니다 inputs의 as: 값이 자리 표시자 이름과 정확히 일치하는지 확인합니다.

플로 예시#

로컬 프롬프트를 사용하는 단순 ambient 플로#

version: "v1"
environment: ambient

components:
  - name: "code_analyzer"
    type: AgentComponent
    prompt_id: "code_review_prompt"
    inputs:
      - from: "context:goal"
        as: "mr_link"
    toolset: ["read_file", "list_dir"]
    ui_log_events:
      - "on_agent_final_answer"

prompts:
  - prompt_id: "code_review_prompt"
    name: "Code Review"
    unit_primitives: []
    prompt_template:
      system: |
        You are an experienced software developer. Conduct a thorough code review
        and provide actionable feedback. When complete, your final answer is a
        summary of your findings. No further steps are needed after that.
      user: |
        Please conduct a code review for the merge request at: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

routers:
  - from: "code_analyzer"
    to: "end"

flow:
  entry_point: "code_analyzer"

도구 동작을 제어하는 도구 옵션을 사용하는 ambient 플로#

version: "v1"
environment: ambient

components:
  - name: "security_agent"
    type: AgentComponent
    prompt_id: "security_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - from: "context:goal"
        as: "mr_link"
    toolset:
      - "create_merge_request_note":
          "internal": true
      - "get_merge_request"
    ui_log_events:
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
      - "on_agent_final_answer"

  - name: "general_agent"
    type: AgentComponent
    prompt_id: "general_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - from: "context:goal"
        as: "mr_link"
    toolset:
      - "create_merge_request_note"
    ui_log_events:
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
      - "on_agent_final_answer"

prompts:
  - prompt_id: "security_prompt"
    name: "Security Analysis Prompt"
    unit_primitives: []
    prompt_template:
      system: |
        You are a security analyst. Review the MR and leave an internal note
        summarizing any security concerns. When complete, your final answer is
        a confirmation that the note was posted. No further steps are needed.
      user: |
        Project ID: {{ project_id }}
        Merge Request: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

  - prompt_id: "general_prompt"
    name: "General Summary Prompt"
    unit_primitives: []
    prompt_template:
      system: |
        You are a helpful assistant. Leave a public note on the MR summarizing
        the changes. When complete, your final answer is a confirmation that
        the note was posted. No further steps are needed.
      user: |
        Project ID: {{ project_id }}
        Merge Request: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

routers:
  - from: "security_agent"
    to: "general_agent"
  - from: "general_agent"
    to: "end"

flow:
  entry_point: "security_agent"

HITL 승인 플로#

이 플로는 작업을 제안하고, 사람이 검토하도록 제시한 뒤, 승인되면 실행합니다. 올바른 sends_response_to 패턴과 세 가지 라우터 라우트를 모두 보여 줍니다.

version: "v1"
environment: ambient

components:
  - name: "proposal_agent"
    type: AgentComponent
    prompt_id: "proposal_prompt"
    inputs:
      - from: "context:goal"
        as: "goal"
      - from: "context:project_id"
        as: "project_id"
    toolset:
      - "get_issue"
      - "list_issues"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

  - name: "review_gate"
    type: HumanInputComponent
    sends_response_to: "proposal_agent"     # proposal_agent has already run ✅
    interaction_type: "approval"
    message_template: |
      The agent has proposed an action. Please review and choose:
      - ✅ Approve: Proceed with the proposed action
      - ✏️ Modify: Provide feedback - the agent will revise
      - ❌ Reject: Discard
    ui_log_events:
      - "on_user_input_prompt"
      - "on_user_response"

  - name: "executor_agent"
    type: AgentComponent
    prompt_id: "executor_prompt"
    inputs:
      - from: "context:goal"
        as: "goal"
      - from: "context:project_id"
        as: "project_id"
      - from: "context:proposal_agent.final_answer"
        as: "approved_proposal"
    toolset:
      - "update_issue"
      - "create_issue_note"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

prompts:
  - prompt_id: "proposal_prompt"
    name: "Proposal Agent"
    unit_primitives: []
    prompt_template:
      system: |
        Review the goal and propose a concrete action. Do not execute anything yet.
        When you have formed your proposal, your final answer is a clear description
        of the proposed action. No further steps are needed after that.
      user: |
        Project ID: {{ project_id }}
        Goal: {{ goal }}
      placeholder: history
    params:
      timeout: 180

  - prompt_id: "executor_prompt"
    name: "Executor Agent"
    unit_primitives: []
    prompt_template:
      system: |
        Execute the approved proposal. If the human provided modification feedback,
        it is in your conversation history - incorporate it before executing.
        When execution is complete, your final answer is a confirmation of what
        was done. No further steps are needed after that.
      user: |
        Project ID: {{ project_id }}
        Goal: {{ goal }}
        Approved proposal: {{ approved_proposal }}
      placeholder: history
    params:
      timeout: 180

routers:
  - from: "proposal_agent"
    to: "review_gate"
  - from: "review_gate"
    condition:
      input: "context:review_gate.approval"
      routes:
        "approve": "executor_agent"
        "modify": "proposal_agent"    # loops back - feedback in proposal_agent history
        "reject": "end"
        "default_route": "end"
  - from: "executor_agent"
    to: "end"

flow:
  entry_point: "proposal_agent"

모델 크기 선호도를 사용하는 플로#

가벼운 작업은 더 작은 모델로, 복잡한 작업은 더 큰 모델로 라우팅합니다.

version: "v1"
environment: ambient

components:
  - name: "explorer"
    type: AgentComponent
    prompt_id: "explorer_agent"
    prompt_version: "^1.0.0"
    model_size_preference: "small"
    inputs: ["context:goal"]
    toolset:
      - "read_file"
      - "list_dir"
      - "find_files"
    ui_log_events:
      - "on_tool_execution_success"

  - name: "implementer"
    type: AgentComponent
    prompt_id: "implementer_agent"
    prompt_version: "^1.0.0"
    model_size_preference: "large"
    inputs:
      - from: "context:goal"
        as: "goal"
      - from: "context:explorer.final_answer"
        as: "codebase_context"
    toolset:
      - "read_file"
      - "edit_file"
      - "create_file_with_contents"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

routers:
  - from: "explorer"
    to: "implementer"
  - from: "implementer"
    to: "end"

flow:
  entry_point: "explorer"

다중 에이전트 감독자 플로#

version: "v1"
environment: ambient

components:
  - name: "developer"
    type: AgentComponent
    description: "Implements code changes, creates and edits files based on requirements."
    prompt_id: "developer_agent"
    prompt_version: "^1.0.0"
    toolset:
      - "read_file"
      - "edit_file"
      - "create_file_with_contents"
      - "list_dir"
      - "find_files"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"

  - name: "tester"
    type: AgentComponent
    description: "Writes and runs automated tests to verify code correctness."
    prompt_id: "tester_agent"
    prompt_version: "^1.0.0"
    toolset:
      - "read_file"
      - "create_file_with_contents"
      - "run_command"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"

  - name: "supervisor"
    type: AgentComponent
    prompt_id: "supervisor_agent"
    prompt_version: "^1.0.0"
    inputs: ["context:goal"]
    subagents:
      - name: "developer"
      - name: "tester"
    max_delegations: 20
    toolset:
      - "get_issue"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

routers:
  - from: "supervisor"
    to: "end"

flow:
  entry_point: "supervisor"

대화형 코드 리뷰를 위한 chat-partial 플로#

version: "v1"
environment: chat-partial

components:  # exactly one AgentComponent when using chat-partial
  - name: "code_analyzer"
    type: AgentComponent
    prompt_id: "code_review_prompt"
    ui_log_events: ["on_agent_final_answer"]
    inputs:
      - from: "context:goal"
        as: "mr_link"
    toolset: ["read_file", "list_dir"]

prompts:
  - prompt_id: "code_review_prompt"
    name: "Code Review Prompt"
    unit_primitives: []
    prompt_template:
      system: |
        You are an experienced software developer. Conduct a thorough code review
        and mentor engineers on best practices.
      user: |
        Please conduct a code review for the merge request at: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

routers: []
flow: {}

Flow Registry Framework v1

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 Framework v1을 사용하면 하나의 YAML 파일에 컴포넌트, 도구, 라우팅 로직을 정의하여 GitLab Duo Agent Platform에서 AI 기반 커스텀 워크플로를 구축할 수 있습니다.

Flow Registry Framework v1을 사용하면 하나의 YAML 파일에 컴포넌트, 도구, 라우팅 로직을 정의하여 GitLab Duo Agent Platform에서 AI 기반 커스텀 워크플로를 구축할 수 있습니다.

YAML 구성 구조#

모든 플로는 하나의 YAML 파일입니다. 최상위 구조는 다음과 같습니다.

version: "v1"
environment: ambient

components:
  # List of components (see Component types)

routers:
  # Routing rules between components (see Routers)

flow:
  entry_point: "component_name"   # First component to run

prompts:                           # Optional - inline prompt definitions
  # Locally defined prompts (see Prompts)

필수 필드#

필드 설명
version 항상 "v1"입니다.
environment 플로의 상호작용 방식입니다. 환경을 참고합니다.
components 플로를 구성하는 컴포넌트 목록입니다. 컴포넌트 유형을 참고합니다.
routers 컴포넌트 간 라우팅 규칙입니다. 라우터를 참고합니다.
flow 진입점과 선택적 컨텍스트 입력입니다. flow 섹션을 참고합니다.

선택 필드#

필드 설명
name 사람이 읽을 수 있는 플로 이름입니다.
description 플로 설명입니다.
product_group 담당 팀입니다(예: agent_foundations).
prompts 인라인 프롬프트 정의입니다. 로컬에서 정의한 프롬프트를 참고합니다.
response_schemas 인라인 응답 스키마 정의입니다. 응답 스키마를 참고합니다.

환경#

environment 필드는 사람과 AI가 상호작용하는 정도를 선언합니다.

값 설명
ambient 사람의 개입 없이 백그라운드에서 실행합니다. 사람이 작업을 위임하면 에이전트가 자율적으로 실행합니다. 사람의 참여를 최소화합니다. 대부분의 커스텀 플로에 이 값을 사용합니다.
chat 채팅과 같은 인터페이스를 통해 주고받는 대화형 상호작용입니다.
chat-partial 단일 에이전트 플로용으로 단순화한 chat 변형입니다. 보일러플레이트를 건너뜁니다. AgentComponent가 정확히 하나 있어야 합니다.

빠른 시작#

플로를 호출하려면 StartWorkflowRequest에 플로 구성을 전달합니다.

flowConfigId: "<your_flow_id>"
flowConfigSchemaVersion: "v1"
flowVersion: "1.0.0"

이 페이지의 나머지 부분은 플로 구성의 YAML 구조를 설명합니다. 코드베이스에 새 기반 플로를 등록하는 방법은 기반 플로 개발자 가이드를 참고합니다.

세션 컨텍스트 변수#

모든 컴포넌트의 inputs 블록은 from: "context:<key>"를 사용해 세션 컨텍스트에서 값을 가져옵니다. 프레임워크는 항상 사용할 수 있는 변수 집합을 자동으로 채웁니다. 이 변수들을 선언할 필요는 없지만, 각 컴포넌트의 inputs 블록에서 명시적으로 참조해야 합니다.

항상 사용할 수 있는 변수#

변수 유형 설명
context:goal string 워크플로를 시작시킨 사용자의 목표 또는 메시지입니다.
context:project_id string GitLab 프로젝트 ID입니다(숫자이며 문자열로 전달됩니다).
context:project_http_url_to_repo string 리포지터리의 전체 HTTPS 클론 URL입니다.
Note

context:project_id는 프롬프트 템플릿에 자동으로 주입되지 않습니다. 에이전트가 GitLab API 도구(예: get_merge_request, list_issues, create_merge_request)를 호출한다면, 이 값을 컴포넌트의 inputs에 추가하고 프롬프트의 user: 블록에 Project ID: {{ project_id }}를 포함해야 합니다. 이를 빠뜨리는 것이 플로 실패의 가장 흔한 원인입니다.

Agent Platform 표준 컨텍스트 변수#

이 변수들은 flow.inputs 항목을 선언한 경우에만 사용할 수 있습니다. CI 러너가 주입하는 브랜치와 세션 메타데이터를 담고 있습니다.

변수 유형 설명
context:inputs.agent_platform_standard_context.primary_branch string 리포지터리의 기본 브랜치입니다(예: main).
context:inputs.agent_platform_standard_context.workload_branch string CI 워크로드 러너가 사용하는 Git ref입니다.
context:inputs.agent_platform_standard_context.session_owner_id string 플로를 실행한 사용자의 GitLab 사용자 ID입니다.

플로가 브랜치를 만들거나, 머지 리퀘스트를 열거나, 기본 브랜치를 알아야 할 때 이 변수들을 선언합니다. 자세한 내용은 flow 섹션을 참고합니다.

flow 섹션#

flow 섹션은 진입점과, 선택적으로 주입할 외부 컨텍스트 카테고리를 정의합니다.

최소 구성#

flow:
  entry_point: "my_first_component"

Agent Platform 표준 컨텍스트 사용#

플로에 primary_branch, workload_branch, session_owner_id가 필요할 때 필수입니다.

flow:
  entry_point: "create_feature_branch"
  inputs:
    - category: agent_platform_standard_context
      input_schema:
        primary_branch:
          type: string
          description: The default/primary branch of the repository (for example, 'main', 'master')
        workload_branch:
          type: string
          description: git ref to workload branch
        session_owner_id:
          type: string
          description: Human user's ID that initiated the flow

컴포넌트 유형#

컴포넌트 용도 AI 사용 사용 시점
AgentComponent 도구를 사용하는 다중 턴 AI 추론 예 반복적인 의사 결정, 대화, 다단계 도구 사용이 필요한 복잡한 작업.
OneOffComponent 단일 라운드 AI 도구 실행 예 내장 재시도 로직과 함께 LLM 호출 한 번으로 완료할 수 있는 한정된 작업.
DeterministicStepComponent 고정된 인수로 단일 도구 실행 아니요 도구 인수를 상태에서 바로 가져오는, 예측 가능하고 반복 가능한 작업.
HumanInputComponent 사용자 입력 요청 및 처리 아니요 승인 게이트, 대화형 채팅 등 사람의 피드백이 필요한 모든 지점.
EndComponent / AbortComponent 워크플로 종료 아니요 모든 플로는 "end"(성공) 또는 "abort"(오류)로 종료해야 합니다.

AgentComponent#

AgentComponent는 AI 기반 플로의 핵심 구성 요소입니다. LLM을 사용해 다음을 수행합니다.

  • 입력을 처리합니다.
  • 프롬프트를 바탕으로 의사 결정을 합니다.
  • 도구를 호출합니다.
  • 대화 기록을 유지합니다.
  • 다운스트림 컴포넌트에 전달할 출력을 생성합니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "AgentComponent"여야 합니다.
prompt_id 프롬프트 템플릿의 ID입니다(로컬 또는 레지스트리 기반).

선택 매개변수#

매개변수 기본값 설명
prompt_version 생략 Semver 제약 조건입니다(예: "^1.0.0"). 로컬에서 정의한 프롬프트를 사용하려면 생략합니다.
inputs ["context:goal"] 입력 데이터 소스 목록입니다.
toolset [] 에이전트가 사용할 수 있는 도구입니다. 사용 가능한 도구를 참고합니다.
description None 감독자 아래의 하위 에이전트로 사용할 때 필수입니다.
subagents None 하위 에이전트 이름 목록 또는 AI Catalog 에이전트용 include 항목입니다(include 참고). 감독자 모드를 활성화합니다.
max_delegations 무제한 감독자 모드에서 delegate_task를 호출할 수 있는 최대 횟수입니다.
response_schema_id None 구조화된 출력 스키마의 ID입니다.
response_schema_version None 레지스트리 기반 스키마의 Semver입니다.
model_size_preference null "small" 또는 "large"입니다.
require_tool_approval false 각 도구를 호출하기 전에 일시 중지하고 사람의 승인을 기다립니다.
pre_approved_tools [] 승인 단계를 건너뛰는 도구입니다.
compaction None 대화 압축 구성입니다.
ui_log_events [] UI에 표시할 이벤트입니다. UI 로그 이벤트를 참고합니다.
ui_role_as "agent" UI에 표시할 역할입니다("agent" 또는 "tool").

출력#

출력 키 설명
context:{name}.final_answer 에이전트의 최종 응답입니다(문자열이며, 커스텀 스키마를 사용하면 dict입니다).
context:{name}.final_answer.{field} 커스텀 응답 스키마를 사용할 때의 개별 필드입니다.
conversation_history:{name} 전체 메시지 기록입니다.

입력#

컴포넌트 입력은 세션 컨텍스트에서 값을 가져와 프롬프트의 템플릿 변수로 사용할 수 있게 합니다. as: 별칭은 프롬프트 템플릿의 {{ variable }} 자리 표시자와 정확히 일치해야 합니다.

# In the component inputs:
inputs:
  - from: "context:goal"
    as: "goal"
  - from: "context:project_id"
    as: "project_id"
  - from: "context:previous_agent.final_answer"
    as: "previous_result"
  - from: "some constant value"
    as: "my_constant"
    literal: true

# In the prompt user block:
user: |
  Project ID: {{ project_id }}
  Goal: {{ goal }}
  Previous result: {{ previous_result }}

프롬프트#

모든 AgentComponent에는 프롬프트가 필요합니다. 플로 YAML에 인라인으로 정의하거나(커스텀 플로에 권장), AI Gateway 프롬프트 레지스트리에 있는 프롬프트를 참조합니다.

로컬에서 정의한 프롬프트#

최상위 prompts 블록에 정의한 인라인 프롬프트를 사용하려면 prompt_version을 생략합니다.

components:
  - name: "my_agent"
    type: AgentComponent
    prompt_id: "my_prompt"
    # prompt_version omitted - uses local prompt

prompts:
  - prompt_id: "my_prompt"
    name: "My Prompt"
    unit_primitives: []           # always include, even if empty
    prompt_template:
      system: |
        You are a helpful assistant.

        When your task is complete, your final answer is a plain text summary
        of what you did. No further steps are needed after that.
      user: |
        Project ID: {{ project_id }}
        Goal: {{ goal }}
      placeholder: history        # include explicitly
    params:
      timeout: 180

레지스트리 프롬프트#

ai_gateway/prompts/definitions/의 AI Gateway 프롬프트 레지스트리에서 불러오려면 prompt_version을 지정합니다.

components:
  - name: "my_agent"
    type: AgentComponent
    prompt_id: "my_flow/my_prompt"
    prompt_version: "^1.0.0"

프롬프트 작성 모범 사례#

  • 에이전트에게 작업이 끝나는 시점을 항상 알려 줍니다. 명시적인 종료 지시가 없으면 에이전트가 반복 실행됩니다. 모든 system: 프롬프트를 다음과 같은 문장으로 끝냅니다. "When [condition], your final answer is [what to say]. No further steps are needed after that."
  • GitLab API 도구를 호출하는 에이전트에는 항상 user: 블록에 project_id를 전달합니다. 에이전트는 이 값을 스스로 알아낼 수 없습니다.
  • 변수 이름을 정확히 일치시킵니다. inputs의 as: 별칭은 프롬프트 템플릿의 {{ variable }} 자리 표시자와 일치해야 합니다.
  • 인라인 프롬프트에는 비어 있더라도 항상 unit_primitives: []를 포함합니다.
  • 인라인 프롬프트 템플릿에는 항상 placeholder: history를 포함합니다.

사용 가능한 도구#

toolset에 snake_case 이름을 전달해 도구를 구성합니다. 전체 목록은 duo_workflow_service/components/tools_registry.py에 있습니다. 일반적인 예는 다음과 같습니다.

  • 파일 작업: read_file, create_file_with_contents, edit_file, list_dir, find_files, grep
  • Git 작업: run_command, create_merge_request, create_branch
  • GitLab API: get_issue, list_issues, get_merge_request, gitlab_merge_request_search, get_work_item, get_repository_file, list_repository_tree, create_issue_note, create_merge_request_note, create_commit, gitlab_api_get, get_project

도구 옵션#

LLM이 변경할 수 없도록 컴포넌트 수준에서 도구의 매개변수를 재정의합니다.

toolset:
  - "get_merge_request"                    # simple string - no overrides
  - "create_merge_request_note":           # object form - override a parameter
      "internal": true

옵션은 초기화 시점에 도구의 Pydantic 입력 스키마와 대조해 검증합니다. 옵션 키가 유효한 매개변수와 일치하지 않으면 ValueError가 발생합니다. 실행 시점에는 도구 옵션이 LLM이 제공한 값보다 우선합니다.

AgentComponent UI 로그 이벤트#

이벤트 설명
on_agent_final_answer 에이전트가 최종 응답을 호출합니다. 세션 UI와 CI 로그에서 최종 응답 전체를 볼 수 있습니다. 출력에 민감한 데이터가 포함된 경우 비활성화합니다.
on_tool_execution_success 도구 호출이 성공적으로 완료되었습니다.
on_tool_execution_failed 도구 호출이 실패했습니다.
on_tool_approval_request 도구 승인이 사용자의 결정을 기다리고 있습니다. UI에 승인 요청을 표시하려면 반드시 포함해야 합니다.

도구 승인#

require_tool_approval: true이면 에이전트가 도구 호출을 생성한 뒤 워크플로가 일시 중지되고, 사용자의 결정을 기다린 다음 진행합니다.

다음 결정 유형을 지원합니다.

결정 동작
APPROVE 도구가 정상적으로 실행됩니다.
REJECT 거부 메시지가 기록에 추가되고, 에이전트가 다른 접근 방식을 시도합니다.
MODIFY 거부와 사용자 피드백이 기록에 추가되고, 에이전트가 이에 맞게 조정합니다.

다음 중 하나에 해당하면 도구가 사전 승인되어 승인 단계를 건너뜁니다.

  • 컴포넌트 수준: 컴포넌트의 pre_approved_tools 매개변수에 나열된 경우입니다. YAML에서 플로 작성자가 제어합니다.
  • 워크플로 수준: 워크플로 startRequest의 pre_approved_agent_privileges로 지정한 경우입니다. 호출 시점에 워크플로 호출자가 제어합니다.

두 경로 중 어느 쪽에서든 모든 도구 호출이 사전 승인되면 승인 흐름을 완전히 건너뛰고 도구가 즉시 실행됩니다.

components:
  - name: "code_editor"
    type: AgentComponent
    prompt_id: "code_assistant"
    prompt_version: "^1.0.0"
    require_tool_approval: true
    pre_approved_tools: ["read_file", "list_dir", "find_files"]
    toolset: ["read_file", "list_dir", "find_files", "edit_file", "run_command"]
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
      - "on_tool_approval_request"
    inputs: ["context:goal"]

사용 모드#

모드 시점 description 필수 여부
Standalone 플로의 일반 컴포넌트입니다. 아니요
Managed 감독자가 위임하는 하위 에이전트입니다. 예
Supervisor delegate_task를 통해 하위 에이전트를 조율합니다. 아니요(감독자 자체에는 필요 없음)

감독자 모드#

subagents를 제공하면 에이전트가 감독자가 되어 delegate_task와 final_response_tool을 자동으로 사용할 수 있습니다. LLM이 delegate_task를 호출하면 프레임워크는 다음을 수행합니다.

  1. 지정한 하위 에이전트에 번호가 매겨진 하위 세션을 할당하거나 재개합니다.
  2. 위임 프롬프트로 하위 에이전트의 대화 기록을 채웁니다.
  3. 실행을 하위 에이전트의 ReAct 루프로 라우팅합니다.
  4. 하위 에이전트가 완료되면 결과를 감독자의 기록에 다시 주입하고 제어권을 감독자에게 돌려줍니다.

제약 조건#

  • subagents에는 항목이 하나 이상 있어야 합니다.
  • 나열된 모든 하위 에이전트에는 description 필드가 있어야 합니다.
  • AgentComponent는 최대 한 명의 감독자만 소유할 수 있습니다.
  • 감독자 프롬프트는 delegate_task와 final_response_tool을 언제 사용할지 LLM에 지시해야 합니다.

감독자 출력#

출력 키 설명
context:{supervisor_name}.final_answer 감독자의 최종 응답입니다.
conversation_history:{supervisor_name} 감독자 자신의 메시지 기록입니다.

응답 스키마#

응답 스키마는 AgentComponent의 출력을 구조화된 형식으로 제한합니다. 스키마가 없으면 에이전트는 final_answer에 일반 문자열을 반환합니다. 스키마가 있으면 final_answer는 dict이며, 각 필드는 context:{name}.final_answer.{field}로도 접근할 수 있습니다.

인라인 스키마(커스텀 플로에 권장)#

components:
  - name: "code_reviewer"
    type: AgentComponent
    prompt_id: "code_review_prompt"
    response_schema_id: "code_review"   # no response_schema_version = inline lookup
    toolset: ["read_file"]

response_schemas:
  - schema_id: "code_review"
    definition:
      "$schema": "http://json-schema.org/draft-07/schema#"
      title: "code_review_response"
      type: object
      properties:
        summary:
          type: string
          description: "Brief summary of findings"
        overall_score:
          type: integer
          minimum: 1
          maximum: 10
      required: [summary, overall_score]

레지스트리 스키마#

response_schema_id와 response_schema_version을 모두 지정하면 ai_gateway/response_schemas/definitions/의 서버 측 레지스트리에서 불러옵니다.

components:
  - name: "code_reviewer"
    type: AgentComponent
    prompt_id: "code_review/detailed_analysis"
    prompt_version: "^1.0.0"
    response_schema_id: "analysis/code_review"
    response_schema_version: "^1.0.0"

다운스트림 컴포넌트는 개별 스키마 필드를 참조할 수 있습니다.

inputs:
  - from: "context:code_reviewer.final_answer.overall_score"
    as: "score"

스키마 정의 참조#

응답 스키마는 JSON Schema 형식을 사용합니다. 중요한 최상위 필드는 다음과 같습니다.

필드 설명
$schema 스키마 방언입니다. 지정하지 않으면 기본값은 draft-07입니다.
title 에이전트가 최종 응답을 위해 호출하는 도구 이름에 대응합니다. 기존 도구 이름과 일치하면 안 되며, 충돌하면 ValueError가 발생합니다.
type 반드시 "object"여야 합니다.
properties 스키마 필드를 정의하는 중첩 JSON 객체입니다. 중첩 구조를 위해 "object" 유형을 지원합니다.
required 출력에 반드시 있어야 하는 필드 이름 목록입니다.

AgentComponent 응답 스키마는 다음 JSON Schema 검증 제약 조건을 지원합니다.

숫자 제약 조건(integer/number)#
JSON Schema 제약 조건 Pydantic 필드 매개변수 설명
minimum ge= 최솟값(포함)입니다. 이상입니다.
maximum le= 최댓값(포함)입니다. 이하입니다.
exclusiveMinimum gt= 최솟값(미포함)입니다. 초과입니다.
exclusiveMaximum lt= 최댓값(미포함)입니다. 미만입니다.
multipleOf multiple_of= 값이 이 숫자의 배수여야 합니다.
문자열 제약 조건#
JSON Schema 제약 조건 Pydantic 필드 매개변수 설명
minLength min_length= 문자열의 최소 길이(문자 수)입니다.
maxLength max_length= 문자열의 최대 길이(문자 수)입니다.
pattern pattern= 문자열이 일치해야 하는 정규 표현식 패턴입니다.
배열 제약 조건#
JSON Schema 제약 조건 Pydantic 필드 매개변수 설명
minItems min_length= 배열의 최소 항목 수입니다.
maxItems max_length= 배열의 최대 항목 수입니다.
열거형과 상수#
JSON Schema 제약 조건 Python 유형 설명
enum Literal[val1, val2, ...] 필드가 지정한 값 중 하나여야 합니다.
const Literal[value] 필드가 정확히 이 값이어야 합니다.
메타데이터#
JSON Schema 필드 Pydantic 필드 매개변수 설명
default default= 선택 필드의 기본값입니다.
examples examples= 에이전트에 지침으로 보여 주는 예시 값입니다.
전체 스키마 예시#
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "code_review_response_tool",
    "type": "object",
    "properties": {
        "summary": {
            "type": "string",
            "description": "Brief summary of the code review findings"
        },
        "issues_found": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "severity": {
                        "type": "string",
                        "enum": ["low", "medium", "high", "critical"]
                    },
                    "description": { "type": "string" },
                    "file_path": { "type": "string" },
                    "line_number": { "type": "integer" }
                },
                "required": ["severity", "description"]
            }
        },
        "recommendations": {
            "type": "array",
            "items": { "type": "string" }
        },
        "overall_score": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10
        }
    },
    "required": ["summary", "issues_found", "overall_score"]
}

AgentComponent 예시#

components:
  - name: "code_assistant"
    type: AgentComponent
    prompt_id: "code_review_helper"
    prompt_version: "^1.0.0"
    inputs: ["context:goal"]
    require_tool_approval: true
    pre_approved_tools: ["read_file", "list_dir", "find_files"]
    toolset:
      - "read_file"
      - "list_dir"
      - "find_files"
      - "create_file_with_contents"
      - "create_merge_request_note":
          "internal": true
      - "edit_file"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
    ui_role_as: "agent"

HumanInputComponent#

HumanInputComponent는 다음을 수행합니다.

  • 워크플로 실행을 일시 중지합니다.
  • 사람에게 프롬프트를 표시합니다.
  • 사람이 응답하면 재개합니다.

검토 게이트, 승인, 피드백 루프에 사용합니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "HumanInputComponent"여야 합니다.
sends_response_to 사람의 응답을 대화 기록에서 받는 AgentComponent의 이름입니다. 이미 실행된 컴포넌트여야 합니다.
message_template 사람에게 표시하는 Jinja2 템플릿입니다. inputs를 통해 변수를 참조할 수 있습니다.

선택 매개변수#

매개변수 기본값 설명
interaction_type "approval" "approval"은 Approve/Reject/Modify 버튼을 표시합니다. "input"은 텍스트 입력란을 표시합니다. 기본값에 의존하지 말고 항상 명시적으로 설정합니다.
inputs [] message_template에 렌더링할 변수입니다.
ui_log_events [] UI 로그 이벤트를 항상 둘 다 포함해야 합니다.

핵심 제약 조건: sends_response_to는 이미 실행된 컴포넌트를 가리켜야 함#

Note

HumanInputComponent에서 가장 흔히 오해하는 필드입니다.

프레임워크는 대상 컴포넌트의 기존 대화 기록에 사람의 피드백을 주입합니다. 해당 컴포넌트가 아직 실행되지 않았다면 대화 기록 항목이 없으므로 프레임워크가 KeyError('<component_name>')와 함께 중단됩니다.

Note

sends_response_to는 게이트가 동작하기 전에 이미 실행을 마친 컴포넌트의 이름이어야 합니다.

실제로는 거의 항상 게이트 바로 앞에서 실행된 에이전트를 다시 가리키게 됩니다.

modify 라우트의 대상이 아직 실행되지 않았다면, 대신 해당 대상의 inputs를 통해 피드백을 전달합니다.

# Correct pattern - sends_response_to points to the already-run agent
- name: "review_gate"
  type: HumanInputComponent
  sends_response_to: "suggester_agent"    # suggester already ran ✅
  interaction_type: "approval"
  ...

# The modify handler gets feedback through inputs instead:
- name: "modify_handler"
  type: AgentComponent
  inputs:
    - from: "context:review_gate.approval"
      as: "human_feedback"               # feedback passed explicitly ✅
# Wrong pattern - crashes with KeyError
- name: "review_gate"
  sends_response_to: "modify_handler"    # has not run yet → KeyError ❌

UI 로그 이벤트#

두 이벤트를 모두 포함해야 합니다. 포함하지 않으면 세션 UI에서 게이트가 보이지 않습니다.

이벤트 설명
on_user_input_prompt 프롬프트를 표시하고 올바른 입력 컨트롤(버튼 또는 텍스트 상자)을 렌더링합니다.
on_user_response 사람의 응답을 UI 채팅 로그에 기록합니다.

출력#

출력 키 설명
context:{name}.approval 사람의 결정입니다: "approve", "reject", "modify" 중 하나입니다.
conversation_history:{sends_response_to} 대상 에이전트의 기록에 주입된 사람의 메시지입니다.

승인 라우터: 값은 두 개가 아니라 세 개#

interaction_type: "approval"이면 사람이 세 가지 값으로 응답할 수 있습니다. 라우터가 세 값을 모두 처리해야 하며, 그렇지 않으면 modify 경로가 조용히 default_route로 넘어갑니다.

값 의미
"approve" 사람이 수락했습니다. 다음 단계로 진행합니다.
"reject" 사람이 거부했습니다. 종료 또는 오류 처리로 라우팅합니다.
"modify" 사람이 피드백을 제공했습니다. 수정을 위해 이전 에이전트로 되돌려 라우팅합니다.
routers:
  - from: "review_gate"
    condition:
      input: "context:review_gate.approval"
      routes:
        "approve": "next_step"
        "modify": "prior_agent"      # loop back - feedback available in history or inputs
        "reject": "end"
        "default_route": "end"       # always include a fallback

HumanInputComponent 체크리스트#

YAML을 저장하기 전에 다음을 확인합니다.

  • interaction_type이 명시적으로 설정되어 있습니다("approval" 또는 "input").
  • ui_log_events에 "on_user_input_prompt"와 "on_user_response"가 모두 포함되어 있습니다.
  • 다운스트림 라우터가 to:가 아니라 condition:을 사용합니다.
  • 라우터가 "approve", "modify", "reject"를 명시적으로 처리합니다.
  • 라우터에 "default_route"가 있습니다.
  • sends_response_to가 게이트가 동작하기 전에 이미 실행된 컴포넌트를 가리킵니다.
  • modify 대상이 아직 실행되지 않았다면, 해당 대상의 inputs에 from: "context:{gate_name}.approval" as: "human_feedback"가 포함되어 있습니다.

사용 패턴#

승인 워크플로#

components:
  - name: "user_approval"
    type: HumanInputComponent
    sends_response_to: "proposal_agent"   # proposal_agent already ran
    interaction_type: "approval"
    message_template: |
      Please review the proposed changes and choose an action:
      - ✅ Approve: Proceed
      - ✏️ Modify: Provide feedback for revision
      - ❌ Reject: Discard
    ui_log_events:
      - "on_user_input_prompt"
      - "on_user_response"

routers:
  - from: "user_approval"
    condition:
      input: "context:user_approval.approval"
      routes:
        "approve": "executor"
        "modify": "proposal_agent"
        "reject": "end"
        "default_route": "end"

대화형 채팅#

components:
  - name: "user_input"
    type: HumanInputComponent
    sends_response_to: "chat_agent"
    interaction_type: "input"
    message_template: "How can I help you today?"
    ui_log_events:
      - "on_user_input_prompt"
      - "on_user_response"

routers:
  - from: "user_input"
    to: "chat_agent"
  - from: "chat_agent"
    to: "user_input"  # loop back for continued interaction

DeterministicStepComponent#

LLM 개입 없이 단일 도구를 직접 실행합니다. 매개변수는 플로 상태에서 추출합니다. 여러 인스턴스를 연결해 순차적인 도구 작업을 실행할 수 있습니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "DeterministicStepComponent"여야 합니다.
tool_name 실행할 단일 도구의 이름입니다.

선택 매개변수#

매개변수 기본값 설명
toolset 자동 도구가 들어 있는 툴셋입니다(생략하면 자동으로 생성됩니다).
inputs [] 도구 매개변수에 매핑되는 입력 소스입니다.
ui_log_events [] UI에 표시할 이벤트입니다.
ui_role_as "tool" UI에 표시할 역할입니다.

출력#

출력 키 설명
context:{name}.tool_responses 도구 실행 결과입니다.
context:{name}.error 발생한 오류입니다.
context:{name}.execution_result "success" 또는 "failed"입니다.

검증#

컴포넌트는 초기화 시점에 도구 인수를 검증합니다.

  • 지정한 도구가 툴셋에 있는지 확인합니다.
  • 필요한 모든 도구 매개변수가 inputs에 구성되어 있는지 확인합니다.
  • 매개변수가 도구의 예상 스키마와 일치하는지 확인합니다.

오류는 런타임이 아니라 구성 시점에 포착됩니다.

예시: 여러 도구 연결#

components:
  - name: "read_config"
    type: DeterministicStepComponent
    inputs:
      - from: "context:goal"
        as: "config_path"
    tool_name: "read_file"
    ui_log_events:
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

  - name: "backup_config"
    type: DeterministicStepComponent
    inputs:
      - from: "context:read_config.tool_responses"
        as: "contents"
      - from: "config_backup.txt"
        as: "file_path"
        literal: true
    tool_name: "create_file_with_contents"

OneOffComponent#

AgentComponent와 DeterministicStepComponent의 중간에 위치합니다. LLM을 사용해 한 번의 라운드로 도구 호출을 생성한 다음 성공하면 종료합니다. 실패한 실행에 대한 내장 재시도 로직을 포함합니다.

LLM 호출 한 번으로 작업을 끝낼 수 있지만, 도구 매개변수를 정하는 데 LLM의 추론이 도움이 될 때 사용합니다.

필수 매개변수#

매개변수 설명
name 고유 식별자입니다. : 또는 . 문자를 포함할 수 없습니다.
type 반드시 "OneOffComponent"여야 합니다.
prompt_id 도구 호출을 지시하는 프롬프트입니다.
toolset 단일 라운드에서 사용할 수 있는 도구입니다.

선택 매개변수#

매개변수 기본값 설명
prompt_version 생략 로컬에서 정의한 프롬프트를 사용하려면 생략합니다.
inputs ["context:goal"] 입력 데이터 소스입니다.
max_correction_attempts 3 실패한 도구 실행의 재시도 한도입니다.
model_size_preference null "small" 또는 "large"입니다.
compaction None 대화 압축 구성입니다.
ui_log_events [] UI에 표시할 이벤트입니다.

출력#

출력 키 설명
context:{name}.tool_responses 도구 실행 결과입니다.
context:{name}.tool_calls 수행한 도구 호출 기록입니다.
context:{name}.execution_result "success" 또는 "failed"입니다.

UI 로그 이벤트#

이벤트 설명
on_tool_call_input 도구가 인수와 함께 호출되려는 시점입니다.
on_tool_execution_success 도구가 성공적으로 완료되었습니다.
on_tool_execution_failed 도구 실행이 실패했습니다.
on_agent_reasoning 제한 때문에 에이전트가 도구 호출을 생성하지 못했습니다.

내부 아키텍처#

OneOffComponent는 내부 노드 세 개로 구성됩니다.

  • LLM 노드({name}#llm): AgentNode를 사용해 도구 호출을 하나 이상 생성합니다.
  • 도구 노드({name}#tools): ToolNodeWithErrorCorrection을 통해 오류 수정과 함께 도구 호출을 실행합니다.
  • 종료 노드({name}#exit): 완료 처리와 상태 로깅을 담당합니다.

예시#

components:
  - name: "file_reader"
    type: OneOffComponent
    prompt_id: "read_specific_file"
    prompt_version: "^1.0.0"
    inputs:
      - from: "context:goal"
        as: "target_file"
    toolset:
      - "read_file"
    max_correction_attempts: 2
    ui_log_events:
      - "on_tool_call_input"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

EndComponent와 AbortComponent#

둘 다 모든 플로에서 자동으로 사용할 수 있습니다. 별도로 정의할 필요가 없습니다.

이름 라우터 키 설정되는 상태 사용 시점
EndComponent "end" COMPLETED 워크플로가 성공적으로 완료되었습니다.
AbortComponent "abort" ERROR 복구할 수 없는 오류가 발생했거나 재시도를 모두 소진했습니다.
routers:
  - from: "my_component"
    to: "end"    # successful completion

  - from: "my_component"
    to: "abort"  # error termination

라우터#

라우터는 각 컴포넌트가 완료된 후 실행이 컴포넌트 사이를 어떻게 이동할지 정의합니다.

단순 라우터#

조건 없이 다음 컴포넌트로 라우팅합니다.

routers:
  - from: "component_a"
    to: "component_b"

조건부 라우터#

컨텍스트 변수의 값에 따라 라우팅합니다.

routers:
  - from: "component_a"
    condition:
      input: "context:component_a.final_answer"
      routes:
        "approved": "component_b"
        "rejected": "end"
        "default_route": "end"   # fallback if value matches nothing

조용히 막다른 길에 빠지는 일을 막으려면 항상 "default_route"를 포함합니다.

흔한 함정#

증상 근본 원인 해결 방법
에이전트가 프로젝트를 찾을 수 없다고 하거나 프로젝트 컨텍스트가 없다고 합니다 컴포넌트 inputs에 project_id가 없습니다 GitLab API 도구를 호출하는 모든 컴포넌트에 - from: "context:project_id" as: "project_id"를 추가하고, user: 블록에 Project ID: {{ project_id }}를 포함합니다.
primary_branch가 정의되지 않았습니다 flow.inputs 항목이 없습니다 agent_platform_standard_context 스키마를 포함한 flow.inputs 블록 전체를 추가합니다.
HITL 게이트가 UI에 아무것도 표시하지 않습니다 HumanInputComponent에 ui_log_events가 없습니다 ui_log_events에 on_user_input_prompt와 on_user_response를 추가합니다.
modify 시 KeyError('<component_name>')가 발생합니다 sends_response_to가 아직 실행되지 않은 컴포넌트를 가리킵니다. sends_response_to를 가장 최근에 완료된 에이전트로 지정하고, modify 대상에는 inputs를 통해 피드백을 전달합니다.
modify 응답이 예기치 않게 default_route로 라우팅됩니다 라우터에 "modify" 라우트가 없습니다 HumanInputComponent 뒤의 모든 조건부 라우터에 "modify": "<target_component>"를 추가합니다.
에이전트가 끝없이 반복합니다 프롬프트에 종료 지시가 없습니다 모든 system: 프롬프트를 명시적인 완료 지시로 끝냅니다.
세션 시작 시 NoneType: None 오류로 중단됩니다 에이전트 시스템 프롬프트에 {{ }} Jinja2 구문이 있습니다 플랫폼은 시스템 프롬프트를 모델에 전달하기 전에 Jinja2로 렌더링합니다. 프롬프트 텍스트의 {{ variable }}은 모두 템플릿 변수로 처리됩니다. 문서에서는 <<variable>> 표기를 사용하거나 {{ }}로 이스케이프합니다.
로드 시 YAML 구문 분석 오류가 발생합니다 인라인 프롬프트에 unit_primitives: []가 없습니다 비어 있더라도 항상 unit_primitives: []를 포함합니다.
에이전트가 빈 변수를 받습니다 as: 별칭이 {{ }} 자리 표시자와 일치하지 않습니다 inputs의 as: 값이 자리 표시자 이름과 정확히 일치하는지 확인합니다.

플로 예시#

로컬 프롬프트를 사용하는 단순 ambient 플로#

version: "v1"
environment: ambient

components:
  - name: "code_analyzer"
    type: AgentComponent
    prompt_id: "code_review_prompt"
    inputs:
      - from: "context:goal"
        as: "mr_link"
    toolset: ["read_file", "list_dir"]
    ui_log_events:
      - "on_agent_final_answer"

prompts:
  - prompt_id: "code_review_prompt"
    name: "Code Review"
    unit_primitives: []
    prompt_template:
      system: |
        You are an experienced software developer. Conduct a thorough code review
        and provide actionable feedback. When complete, your final answer is a
        summary of your findings. No further steps are needed after that.
      user: |
        Please conduct a code review for the merge request at: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

routers:
  - from: "code_analyzer"
    to: "end"

flow:
  entry_point: "code_analyzer"

도구 동작을 제어하는 도구 옵션을 사용하는 ambient 플로#

version: "v1"
environment: ambient

components:
  - name: "security_agent"
    type: AgentComponent
    prompt_id: "security_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - from: "context:goal"
        as: "mr_link"
    toolset:
      - "create_merge_request_note":
          "internal": true
      - "get_merge_request"
    ui_log_events:
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
      - "on_agent_final_answer"

  - name: "general_agent"
    type: AgentComponent
    prompt_id: "general_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - from: "context:goal"
        as: "mr_link"
    toolset:
      - "create_merge_request_note"
    ui_log_events:
      - "on_tool_execution_success"
      - "on_tool_execution_failed"
      - "on_agent_final_answer"

prompts:
  - prompt_id: "security_prompt"
    name: "Security Analysis Prompt"
    unit_primitives: []
    prompt_template:
      system: |
        You are a security analyst. Review the MR and leave an internal note
        summarizing any security concerns. When complete, your final answer is
        a confirmation that the note was posted. No further steps are needed.
      user: |
        Project ID: {{ project_id }}
        Merge Request: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

  - prompt_id: "general_prompt"
    name: "General Summary Prompt"
    unit_primitives: []
    prompt_template:
      system: |
        You are a helpful assistant. Leave a public note on the MR summarizing
        the changes. When complete, your final answer is a confirmation that
        the note was posted. No further steps are needed.
      user: |
        Project ID: {{ project_id }}
        Merge Request: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

routers:
  - from: "security_agent"
    to: "general_agent"
  - from: "general_agent"
    to: "end"

flow:
  entry_point: "security_agent"

HITL 승인 플로#

이 플로는 작업을 제안하고, 사람이 검토하도록 제시한 뒤, 승인되면 실행합니다. 올바른 sends_response_to 패턴과 세 가지 라우터 라우트를 모두 보여 줍니다.

version: "v1"
environment: ambient

components:
  - name: "proposal_agent"
    type: AgentComponent
    prompt_id: "proposal_prompt"
    inputs:
      - from: "context:goal"
        as: "goal"
      - from: "context:project_id"
        as: "project_id"
    toolset:
      - "get_issue"
      - "list_issues"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

  - name: "review_gate"
    type: HumanInputComponent
    sends_response_to: "proposal_agent"     # proposal_agent has already run ✅
    interaction_type: "approval"
    message_template: |
      The agent has proposed an action. Please review and choose:
      - ✅ Approve: Proceed with the proposed action
      - ✏️ Modify: Provide feedback - the agent will revise
      - ❌ Reject: Discard
    ui_log_events:
      - "on_user_input_prompt"
      - "on_user_response"

  - name: "executor_agent"
    type: AgentComponent
    prompt_id: "executor_prompt"
    inputs:
      - from: "context:goal"
        as: "goal"
      - from: "context:project_id"
        as: "project_id"
      - from: "context:proposal_agent.final_answer"
        as: "approved_proposal"
    toolset:
      - "update_issue"
      - "create_issue_note"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

prompts:
  - prompt_id: "proposal_prompt"
    name: "Proposal Agent"
    unit_primitives: []
    prompt_template:
      system: |
        Review the goal and propose a concrete action. Do not execute anything yet.
        When you have formed your proposal, your final answer is a clear description
        of the proposed action. No further steps are needed after that.
      user: |
        Project ID: {{ project_id }}
        Goal: {{ goal }}
      placeholder: history
    params:
      timeout: 180

  - prompt_id: "executor_prompt"
    name: "Executor Agent"
    unit_primitives: []
    prompt_template:
      system: |
        Execute the approved proposal. If the human provided modification feedback,
        it is in your conversation history - incorporate it before executing.
        When execution is complete, your final answer is a confirmation of what
        was done. No further steps are needed after that.
      user: |
        Project ID: {{ project_id }}
        Goal: {{ goal }}
        Approved proposal: {{ approved_proposal }}
      placeholder: history
    params:
      timeout: 180

routers:
  - from: "proposal_agent"
    to: "review_gate"
  - from: "review_gate"
    condition:
      input: "context:review_gate.approval"
      routes:
        "approve": "executor_agent"
        "modify": "proposal_agent"    # loops back - feedback in proposal_agent history
        "reject": "end"
        "default_route": "end"
  - from: "executor_agent"
    to: "end"

flow:
  entry_point: "proposal_agent"

모델 크기 선호도를 사용하는 플로#

가벼운 작업은 더 작은 모델로, 복잡한 작업은 더 큰 모델로 라우팅합니다.

version: "v1"
environment: ambient

components:
  - name: "explorer"
    type: AgentComponent
    prompt_id: "explorer_agent"
    prompt_version: "^1.0.0"
    model_size_preference: "small"
    inputs: ["context:goal"]
    toolset:
      - "read_file"
      - "list_dir"
      - "find_files"
    ui_log_events:
      - "on_tool_execution_success"

  - name: "implementer"
    type: AgentComponent
    prompt_id: "implementer_agent"
    prompt_version: "^1.0.0"
    model_size_preference: "large"
    inputs:
      - from: "context:goal"
        as: "goal"
      - from: "context:explorer.final_answer"
        as: "codebase_context"
    toolset:
      - "read_file"
      - "edit_file"
      - "create_file_with_contents"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

routers:
  - from: "explorer"
    to: "implementer"
  - from: "implementer"
    to: "end"

flow:
  entry_point: "explorer"

다중 에이전트 감독자 플로#

version: "v1"
environment: ambient

components:
  - name: "developer"
    type: AgentComponent
    description: "Implements code changes, creates and edits files based on requirements."
    prompt_id: "developer_agent"
    prompt_version: "^1.0.0"
    toolset:
      - "read_file"
      - "edit_file"
      - "create_file_with_contents"
      - "list_dir"
      - "find_files"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"

  - name: "tester"
    type: AgentComponent
    description: "Writes and runs automated tests to verify code correctness."
    prompt_id: "tester_agent"
    prompt_version: "^1.0.0"
    toolset:
      - "read_file"
      - "create_file_with_contents"
      - "run_command"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"

  - name: "supervisor"
    type: AgentComponent
    prompt_id: "supervisor_agent"
    prompt_version: "^1.0.0"
    inputs: ["context:goal"]
    subagents:
      - name: "developer"
      - name: "tester"
    max_delegations: 20
    toolset:
      - "get_issue"
    ui_log_events:
      - "on_agent_final_answer"
      - "on_tool_execution_success"
      - "on_tool_execution_failed"

routers:
  - from: "supervisor"
    to: "end"

flow:
  entry_point: "supervisor"

대화형 코드 리뷰를 위한 chat-partial 플로#

version: "v1"
environment: chat-partial

components:  # exactly one AgentComponent when using chat-partial
  - name: "code_analyzer"
    type: AgentComponent
    prompt_id: "code_review_prompt"
    ui_log_events: ["on_agent_final_answer"]
    inputs:
      - from: "context:goal"
        as: "mr_link"
    toolset: ["read_file", "list_dir"]

prompts:
  - prompt_id: "code_review_prompt"
    name: "Code Review Prompt"
    unit_primitives: []
    prompt_template:
      system: |
        You are an experienced software developer. Conduct a thorough code review
        and mentor engineers on best practices.
      user: |
        Please conduct a code review for the merge request at: {{ mr_link }}
      placeholder: history
    params:
      timeout: 180

routers: []
flow: {}