Flow Registry Framework v1
GitLab v19.6Offering: 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입니다. |
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를 호출하면 프레임워크는 다음을 수행합니다.
- 지정한 하위 에이전트에 번호가 매겨진 하위 세션을 할당하거나 재개합니다.
- 위임 프롬프트로 하위 에이전트의 대화 기록을 채웁니다.
- 실행을 하위 에이전트의 ReAct 루프로 라우팅합니다.
- 하위 에이전트가 완료되면 결과를 감독자의 기록에 다시 주입하고 제어권을 감독자에게 돌려줍니다.
제약 조건#
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는 이미 실행된 컴포넌트를 가리켜야 함#
HumanInputComponent에서 가장 흔히 오해하는 필드입니다.
프레임워크는 대상 컴포넌트의 기존 대화 기록에 사람의 피드백을 주입합니다.
해당 컴포넌트가 아직 실행되지 않았다면 대화 기록 항목이 없으므로
프레임워크가 KeyError('<component_name>')와 함께 중단됩니다.
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: {}