【신규 기능】 Kiro Workflow 입문: 정의 파일로 멀티 에이전트 연동 구동하기

Kiro의 신기능
Workflow는 멀티 에이전트의 오케스트레이션(orchestration)을 JSON 정의 파일로 선언적으로 작성할 수 있는 메커니즘입니다. 본 기사에서는 실제로 구동한 FizzBuzz의 2개 에이전트 연동(구현 → 리뷰) 로그를 바탕으로, 4개의 JSON 파일 내용을 하나씩 해설합니다.

나아가 단순히 입문에서 끝나는 것이 아니라, '애전트를 분리해야 하는지 여부'를 판단하는 3가지 기준 축 (책임의 충돌 / 프롬프트 단순화와 과정 기록 / 사람에 의한 승인 게이트)을 제시합니다.

Kiro 업데이트로 Workflow라는 기능이 추가되었습니다. 여러 에이전트를 '어떤 순서로', '어떻게 연동시킬지'를 **정의 파일(definition file)**로 기술하고, 오케스트레이터(통괄 역할)가 이를 실행하는 구조입니다.

멀티 에이전트 입문 기사는 '일단 작동시키는 것'에서 끝나는 경우가 많습니다. 하지만 실무에서 효과적인 것은 동작 방식 자체보다 **'언제 애전트를 분리해야 하고, 언제 분리하면 안 되는지'**에 대한 판단력입니다.

따라서 이 기사는 다음의 2부 구성으로 진행됩니다.

• 구현편: 실제로 구동한 최소 데모(FizzBuzz를 만들고, 다른 에이전트가 리뷰하는 것)의 로그를 정의 파일과 실행 상태 파일로부터 해석합니다.
• 설계편: 멀티 에이전트화를 검토할 때 필요한 3가지 판단 기준 축을 제시합니다.

본 기사는 필자가 실제로 Kiro의 Workflow를 구동한 작업 로그(생성된 JSON 파일군)를 기반으로 작성되었습니다. 설계편의 '판단 기준 축'은 필자의 분석 및 의견이며, 그 점을 명시하고 있습니다.

각 단계에는 '어떤 에이전트가', '무엇을 할지(프롬프트)'가 할당됩니다. 한 단계의 결과물을 다음 단계로 전달할 수도 있습니다.

여기서 가장 먼저 파악해야 할 점은 이것입니다. 이 정의 파일을 사용자가 직접 손으로 작성할 필요는 없습니다.

이번 데모에서 필자가 내린 지시는 단 하나의 자연어 문장뿐이었습니다.

코드 생성과 리뷰의 2개 에이전트 워크플로우를 작성해줘

이 지시를 받고, Kiro 측에서 workflow-definition.json을 생성했습니다. 사용자가 준비하는 것은 '하고 싶은 일에 대한 설명'이지, JSON 그 자체가 아닙니다.

후술할 workflow-definition.json

안의 내용(steps나 prompt)은 모두 Kiro가 자연어 지시로부터 조립한 것입니다. 본 기사에서는 '생성된 정의 파일을 해석한다'는 입장에서 해설합니다. 손으로 작성하는 것도 가능하지만, 우선은 자연어로 맡기는 것이 진입점입니다.

워크플로우를 실행하면, 정의 파일과 실행 기록은 실행한 세션의 작업 폴더 아래에 놓이게 됩니다.

<세션 폴더>/workflows/<워크플로우 ID>/
├── workflow-definition.json
├── workflow-state.json
...

이번 데모의 <워크플로우 ID>는 wf_b6a5f05169609022였습니다. 사용자가 이 경로를 지정하는 것이 아니라, 실행 시 Kiro가 결정하여 작성합니다.

Kiro에서는 이전에도 채팅 속에서 '이 파일을 조사해줘', '다음은 이걸 구현해줘'와 같이, 1개의 에이전트에게 순차적으로 지시를 내릴 수 있었습니다. 이를 본 기사에서는 **대화 기반의 수동 위임(manual delegation)**이라고 부릅니다.

Workflow가 가져오는 것은 이 절차를 정의 파일에 고정한다는 발상입니다. 두 방식의 차이점을 정리합니다.

| 관점 | 대화 기반의 수동 위임 | Workflow (정의 파일) |
|---|---|
| 절차 기술 | 그 자리의 대화로 순차 지시 | 정의 파일에 사전 선언(Kiro가 생성) |
| ... | {{artifacts.xxx}}로 명시적 참조 |
| 실행 기록 | 채팅 히스토리만 존재 | 상태 파일에 구조화되어 남음 |

중요한 점은 단계별로 별도의 세션에서 움직이고, 역할별로 프롬프트가 분리된다는 것입니다. 구현(implementation)은 구현 지시만, 리뷰는 리뷰 관점만 받습니다. 이 '역할을 하나로 좁힐 수 있는' 구조가 나중에 설명할 판단 기준의 전제가 됩니다.

이번에 구동한 것은 다음 두 단계의 워크플로우입니다.

• implement (담당: wf-coder):
  FizzBuzz(1~100을 출력하고, 3의 배수일 때 Fizz, 5의 배수일 때 Buzz, 15의 배수일 때 FizzBuzz) Python 스크립트를 작성 -
• review (담당: semantic_reviewer):
  완성된 스크립트를 다른 에이전트가 리뷰하고, 판정을 Markdown에 기록합니다.

wf-coder와 semantic_reviewer는 단계에 할당된 에이전트 이름입니다. 각각 다른 역할(구현 담당/리뷰 담당)로서 움직입니다.

일부러 단순한 소재를 택한 이유는 '2개의 에이전트가 연계하여 작동한다'는 메커니즘 자체를 관찰하기 위함입니다.

먼저, 완성된 결과물을 보겠습니다. 구현 에이전트가 생성한 fizzbuzz.py는 다음과 같습니다.

def fizzbuzz(n):
if n % 15 == 0:
return "FizzBuzz"
...

fizzbuzz(n)은 15의 배수를 먼저 판정하여, Fizz/Buzz에 의해 선점되는 오류를 피하고 있습니다. if __name__ == "__main__": 가드를 추가함으로써, import 시에 100줄의 출력이 발생하지 않게 했습니다.

실행해보니, 앞의 15줄은 기대했던 대로였습니다.

1
2
Fizz
...

다음으로, 리뷰 담당 에이전트가 출력한 review.md의 시작 부분입니다.

# 코드 리뷰: fizzbuzz.py
**종합 판정: APPROVED**
FizzBuzz 구현은 정확하며, 함수 분할・`__main__` 가드・가독성 모두 양호합니다.

구현 에이전트와 다른 리뷰 에이전트가 15의 배수 판정 순서나 __main__ 가드의 유무를 체크하여, APPROVED를 내렸습니다. 2개 에이전트의 연계가 성립했습니다.

앞서 말씀드린 workflows/<워크플로우 ID>/에는 4개의 JSON 파일이 놓입니다. 이들 모두 사용자가 손으로 작성한 것이 아니며, definition은 자연어 지시로부터 Kiro가 생성하고, 나머지는 실행 시점에 Kiro가 작성합니다.

역할과, 실행 전후로 어떻게 변하는지를 목록으로 보여드립니다.

핵심은, '무엇을 할지(definition)'는 실행해도 불변이고, '어떻게 작동했는지(state 등)'만 나중에 채워진다는 분리입니다. 이것이 동일한 정의를 여러 번 재실행할 수 있는 기반이 됩니다. 이하 4가지를 순서대로 보겠습니다.

워크플로우의 '설계도'입니다. 어떤 에이전트가, 어떤 순서로, 무엇을 할지가 선언되어 있습니다. 이는 Kiro가 자연어 지시로부터 생성한 것으로, 아래가 이번 데모의 정의입니다.

{
"name": "workflow-demo-fizzbuzz",
"description": "Demo: implement a FizzBuzz Python script, then semantically review it.",
...
}

요소별 의미를 보겠습니다.

키 의미
|---|---
name / description 워크플로우의 이름과 설명
inputs 실행 시 외부에서 전달하는 값(이번에는 비어 있음)
steps 실행할 스텝 배열. 이 순서대로 실행됨
|steps[].id 스텝의 식별자(implement / review )
steps[].agent 담당 에이전트 이름(wf-coder / semantic_reviewer )
steps[].prompt 그 에이전트에게 전달할 실제 프롬프트(구체적인 지시)
steps[].artifacts 해당 스텝이 생성하는 결과물의 논리명과 경로

주목해야 할 부분은 두 번째 스텝의 프롬프트에 있는 {{artifacts.script}} 입니다.

"prompt": "... 검토 대상의 절대 경로: {{artifacts.script}} ..."

이는 첫 번째 스텝이 선언한 결과물 script (즉, fizzbuzz.py의 경로)을 두 번째 스텝이 변수로 받아들이는 방식입니다. 스텝 간 데이터 전달이 구두가 아닌 정의 파일 상에서 명시되고 있습니다. 이것이야말로 '선언적 오케스트레이션(declarative orchestration)'의 진가라고 할 수 있습니다.

각 스텝의 prompt는 그대로 담당 에이전트에게 전달되는 지시문입니다. 이번 데모의 implement 프롬프트에는 사양(15의 배수를 먼저 판별) 및 검증 절차(첫 15줄이 기대값과 일치하는지), 최종 메시지의 형식까지 작성되어 있었습니다. 여기가 부실하면 스텝은 기대대로 작동하지 않습니다. 정의 파일에서 가장 공을 들여야 할 부분은 바로 이 prompt입니다.

'설계도'가 definition이라면, 여기는 실제로 어떻게 움직였는지에 대한 기록입니다. 발췌합니다.

{
"workflowId": "wf_b6a5f05169609022",
"workflowName": "workflow-demo-fizzbuzz",
...
}

여기서 읽어낼 수 있는 것들을 정리합니다.

: 두 스텝이 '순차 실행(sequence)'으로 관리되고 있습니다. root.type가 sequence입니다.

각 노드가 별개: sessionId implement와 review는 별개의 서브 세션에서 작동하고 있습니다. 문맥이 분리되어 있다는 증거입니다. -
시간의 연속성: implement가 13:47:35.954에 끝나고, review가 13:47:35.956에 시작했습니다. 전 단계의 완료를 기다려 후 단계를 작동시킨다는 순서가 지켜졌습니다. -
: 각 스텝은 completionSignal: success / completionSignalSource: send_message send_message로 완료를 통지하며, 그것이 성공 시그널이 됩니다.

상태 파일에는 capturedOutputs도 기록되어, 각 스텝의 최종 메시지(구현 에이전트의 '첫 15줄 출력' 등)가 온전히 남아 있습니다. 나중에 '무슨 일이 일어났는지'를 재구성할 수 있다는 것이 이 상태 파일의 가치입니다.

어떤 스텝을, 어떤 서브 세션이 실행했는지에 대한 대응표입니다.

{
"workflowId": "wf_b6a5f05169609022",
"sessions": [
...
}

짧은 파일이지만, 스텝 = 독립적인 서브 세션이라는 설계가 여기에 나타나 있습니다. 각 서브 세션은 자신의 일만 알고 있고, 다른 스텝의 문맥을 가지지 않습니다.

실행 중단/재개 및 클린업을 위한 관리 파일입니다.

{
"version": 1,
"workflowId": "wf_b6a5f05169609022",
...
}

phase: settled는 뒷정리가 완료된 상태를 나타내며, stateDigest는 상태의 해시입니다. 일상적으로 내용을 신경 쓸 파일은 아니지만, 실행이 트랜잭션적으로 관리되고 있다는 것을 짐작할 수 있습니다.

여기부터는 필자의 분석/의견이며, 사양이 아닙니다.

Workflow를 사용하면 쉽게 에이전트를 분리할 수 있습니다. 그렇기에, 분리해야 할지 여부를 먼저 생각하고 싶습니다. 필자는 다음 3가지 축으로 판단하고 있습니다.

하나의 에이전트에게 '구현'과 '리뷰'를 동시에 수행하게 하면, 자신이 작성한 코드를 스스로 관대하게 평가하는 이해 상충(Conflict of Interest)이 발생하기 쉽습니다.

이번 데모에서 구현과 리뷰를 분리한 것은 이 충돌을 피하기 위함입니다. 리뷰 담당에게는 '15의 배수 판별 순서', '함수 분할', '__main__ 가드', '가독성'이라는 관점만을 전달했을 뿐, 구현 세션의 내용은 전달하지 않았습니다. 그 결과 APPROVED를 내리면서도 "타입 힌트를 추가하는 것이 좋겠다", "docstring이 있으면 좋을 것 같다"와 같이 사양에 명시되지 않은 개선점까지 지적했습니다. 이는 만드는 사람과는 다른 시각으로 본 지적이었습니다.

판단 기준: 하나의 에이전트에게 맡기는 역할들이 서로 이해 상충(예: 제작하는 측과 검증하는 측)을 일으킨다면, 분리할 가치가 있습니다.

하나의 에이전트가 구현과 리뷰를 모두 수행하게 할 경우, 해당 에이전트의 프롬프트에는 '제작 지시'와 '리뷰 관점'을 모두 작성해야 합니다. 프롬프트가 길고 복잡해질수록 에이전트의 출력은 매번 흔들리기 쉽습니다. 흔들림이 좋은 방향으로 나오면 좋겠지만, 나쁜 방향으로 기울어지는 경우도 있습니다. 구현과 리뷰로 단계를 분리하면, 각각의 프롬프트는 하나의 역할에 집중되어 동작을 제어하기가 쉬워집니다.

또 다른 큰 요소는 과정 기록입니다. 하나의 에이전트에서 구현과 리뷰를 동시에 진행할 경우, 처음 출력된 코드에 어떤 리뷰가 들어갔고 어떻게 수정되어 최종 형태가 되었는지 과정 전체가 에이전트 내부에서만 완료됩니다. 인간의 관점에서는 그 과정 자체가 블랙박스인 셈입니다.

멀티 에이전트 시스템으로 구성하면 이 부분이 분해됩니다. 구현 에이전트는 코드를 출력하고, 리뷰 에이전트는 그 코드에 대한 리뷰 결과를 Markdown 파일로 남깁니다. 이번 데모에서도 리뷰 결과는 review.md에 작성되었습니다.

# 코드 리뷰: fizzbuzz.py
**종합 판정: APPROVED**
...
...

이 파일이 있으면, 나중에 사람이 "어떤 관점에서 리뷰했고, 어디를 문제로 봤으며, 어떻게 판단했는지"의 과정을 추적할 수 있습니다. 리뷰 과정 자체가 사라지지 않고 기록으로 남게 됩니다.

판단 기준: 하나의 에이전트에게 역할을 너무 많이 몰아주어 동작이 불안정해지는 것이 곤란하거나, 혹은 리뷰나 수정 과정을 나중에 추적할 수 있는 기록으로 남기고 싶다면, 단계를 분리할 가치가 있습니다.

일련의 작업 도중에 "여기서 사람이 내용을 확인하고 승인한 후에 다음 단계로 넘어가고 싶다"는 지점이 있다면, 그곳에서 단계를 구분하는 의미가 있습니다.

예를 들어 '구현 → 사람이 확인 및 승인 → 공개'처럼, 사람의 판단을 절차 안에 포함시키고 싶은 경우입니다. 대화 기반 방식에서는 승인 확인 과정을 건너뛰기 쉽지만, 단계로 분리해 놓으면 그 지점에서 반드시 멈출 수 있습니다.

이번 데모는 구현 → 리뷰의 2단계로 진행되어 사람이 개입하는 승인 게이트(Approval Gate)는 포함하지 않았습니다. 하지만 리뷰 결과(APPROVED / CHANGES_REQUESTED)를 사람이 받아 공개 가능 여부를 판단하는 등의 운영 방식에 자연스럽게 확장할 수 있습니다.

판단 기준: 공개나 실제 반영 등, 사람의 승인 없이 다음 단계로 진행하고 싶지 않은 공정이 있다면, 그곳을 단계의 경계로 삼는 가치가 있습니다.

위 세 가지 축 중 어느 것에도 해당하지 않는다면, 분리하지 않는 것이 빠르고 확실합니다.

• 역할이 하나이고 이해 상충이 없다.
• 프롬프트가 단순하고, 과정을 기록으로 남길 필요도 없다.
• 도중에 끼워 넣고 싶은 사람의 승인 게이트가 없다.

이러한 단순 작업은 하나의 에이전트 대화만으로 충분합니다. 에이전트를 분리하는 것 자체에 비용(정의 파일 설계, 세션 간 전달 설계)이 들기 때문에, 분리할 이유가 없다면 분리하지 않는 것이 필자의 기본 방침입니다.

마지막으로, 정의 파일(Definition File)화 그 자체의 손익을 정리합니다. 이 역시 필자의 견해입니다.

장점 (Merits)

• 재현성: 동일한 definition을 재실행하면 동일한 절차가 실행됩니다. state만 새로 생성될 뿐입니다.
• 가독성: 절차가 JSON 형태로 남기 때문에, "이 워크플로우가 무엇을 하는지"를 나중에 읽어볼 수 있습니다.
• 공정 강제: 리뷰나 승인 단계를 건너뛸 수 없습니다.

단점 (Demerits)

• 설계 오버헤드: 단계 분할, 프롬프트, 결과물 전달을 사전에 설계해야 합니다.
• 변경의 무거움: 절차를 바꾸려면 정의 파일을 편집해야 하므로, 대화의 그 자리에서의 유연성은 사라집니다.

즉, 반복적으로 수행하는 정형 작업이나 리뷰/승인 단계를 건너뛰고 싶지 않은 작업에는 정의 파일화가 효과적이며, 일회성 탐색적인 작업에는 대화 기반 방식이 더 적합합니다.

• Kiro Workflow는 멀티 에이전트의 절차를 JSON 정의 파일로 선언하고, 단계별로 별도의 세션에서 실행하는 메커니즘입니다. - 실행 후에는 definition / state / sessions / checkpoint-cleanup 네 개의 파일이 남으며, '설계'와 '실행 기록'이 분리됩니다. - 멀티 에이전트화는 책임의 충돌 여부・프롬프트 단순화 및 과정 기록 필요성・사람에 의한 승인 게이트 필요 여부라는 세 축으로 판단하는 것이 좋습니다. 어느 것에도 해당하지 않는다면, 나누지 않는 것이 빠르고 확실합니다.

'나눌 수 있으니 나눈다'가 아니라, '나눌 이유가 있기 때문에 나눈다'. Workflow를 사용할 때도 이 순서는 변하지 않습니다.

본문에서 다루지 않은 내용을 보충 설명합니다. 근거는 공식 블로그 'Introducing Kiro workflows'에서 확인할 수 있습니다. 해당 페이지는 한 장짜리 긴 글이므로, 관련 부분을 함께 제시합니다(브라우저의 페이지 내 검색으로 인용 구문을 찾을 수 있습니다).

늘릴 수 있습니다. 공식 블로그 중간쯤에 팀 사용법을 설명한 단락에 '전형적인 워크플로우는 5~10단계로 작동한다'는 내용이 있습니다(원문