에이전트를 처음 연결할 때 가장 먼저 결정해야 하는 것들

에이전트를 만드는 건 생각보다 금방 되는 편이에요. API를 연결하고 프롬프트를 짜면 "조사해줘"에 뭔가를 돌려주는 것까지는 하루 이틀이면 나오거든요. 그런데 그 다음이 문제예요. "이걸 어떻게 실제로 쓰지?" 조사 결과를 어디에 넣어야 하지? 작성 에이전트는 언제 실행해야 하지? 검수가 통과되면 그다음은 뭐가 일어나야 하지?

이 질문들을 정리하는 과정이 바로 워크플로우 설계예요. 코드가 아니라, 생각을 문서로 만드는 작업이에요.

워크플로우 설계를 시작하기 전에 스스로에게 던져야 할 질문들은 무엇인가요?

가장 먼저 물어야 할 건 "트리거가 뭔가요?"예요. 에이전트는 혼자서 깨어나지 않아요. 누군가 "시작해"라고 말해줘야 하는데, 그 신호가 트리거예요. 트리거를 정의하지 않으면 파이프라인은 그냥 실행 안 되는 코드 뭉치로 남아요.

트리거의 종류는 크게 세 가지로 나눌 수 있어요.

트리거 다음엔 "누가 무엇을 하는가"를 물어야 해요. 워크플로우 안에 에이전트가 여러 명이라면, 각자 하는 일이 겹치지 않아야 해요. "조사도 하고 글도 써줘"를 한 에이전트에 맡기면 결과가 들쑥날쑥해요. arxiv.org에서 발표된 프로덕션 에이전트 설계 연구에서도 에이전트 하나에 역할을 둘 이상 주면 환각과 오류가 눈에 띄게 늘었다고 나와요. 단일 책임 원칙이 에이전트에도 그대로 적용되는 거예요.

마지막으로 "결과가 어디로 가는가"를 정해야 해요. 각 에이전트가 뭔가를 만들어냈다면, 그게 다음 에이전트에게 전달돼야 해요. 그 연결 방식을 미리 정의해두지 않으면 "에이전트는 돌아갔는데 결과가 어디 갔는지 모르겠다"는 상황이 생겨요.

워크플로우를 정의한다는 게 실제로는 무엇을 문서화하는 건가요?

한 줄 요약하면, 에이전트당 한 장의 명세서를 쓰는 거예요. 그 명세서에 들어가는 항목은 네 가지예요.

1. 입력(Input): 이 에이전트가 받아야 하는 것. 데이터 형식, 어디서 오는지.
2. 출력(Output): 이 에이전트가 내보내야 하는 것. 형식이 구체적일수록 좋아요.
3. 조건(Condition): 언제 다음 단계로 넘어가고, 언제 멈추는지.
4. 목적지(Destination): 출력이 어디로 전달되는지. 다음 에이전트인지, DB인지, 슬랙인지.

막연하게 "조사 에이전트가 조사를 하면 작성 에이전트가 글을 쓴다"고 적는 것과, "조사 에이전트의 출력은 JSON 형식의 {title, url, summary} 배열이고, 이것이 작성 에이전트의 context 파라미터로 전달된다"고 적는 것은 완전히 달라요. 전자는 아이디어고, 후자는 설계예요.

출력 형식을 고정하는 게 처음에는 귀찮아 보여도, 나중에 에이전트를 교체하거나 추가할 때 이게 없으면 파이프라인 전체를 다시 뜯어야 해요. n8n.io 같은 툴을 써봐도 결국 같은 문제에 부딪혀요. 노드 간 데이터 포맷을 미리 맞춰두지 않으면 중간에 에러가 터지는 지점이 생겨요.

워크플로우 명세서의 핵심: 에이전트가 뭘 하는지보다, 무엇을 받아서 무엇을 내보내는지를 먼저 써라.

콘텐츠 파이프라인을 어떻게 설계했나요?

콘텐츠 자동화 파이프라인을 예시로 살펴볼게요. 조사 에이전트 → 작성 에이전트 → 검수 에이전트로 이어지는 세 단계 구조예요. 완성된 그림보다, 각 단계에서 어떤 설계 결정이 필요한지가 핵심이에요.

1단계 — 조사 에이전트

• 입력: 주제 키워드 (문자열)
• 출력: 기사 URL 목록 + 각 URL의 한 줄 요약 (JSON 배열)
• 트리거: 수동 호출 (슬랙 커맨드 /research [키워드])
• 목적지: 공유 스토리지 (Notion 데이터베이스 또는 파일)

여기서 첫 번째 설계 결정 포인트는 트리거를 수동으로 고정하는 거예요. "매일 자동으로 조사가 돌아가면 좋겠다"고 생각하기 쉬운데, 주제를 누군가 직접 고르지 않으면 에이전트가 멋대로 방향을 잡아버려요. 콘텐츠 파이프라인에서 주제 선택은 사람이 해야 하는 마지막 관문이에요.

2단계 — 작성 에이전트

• 입력: 조사 에이전트의 출력 JSON + 작성 스타일 가이드
• 출력: 마크다운 형식의 초안 (제목, 본문, 출처 포함)
• 트리거: 조사 에이전트 출력 완료 이벤트
• 목적지: 검수 에이전트 입력 큐

여기서의 설계 결정 포인트는 스타일 가이드를 입력에 포함하는 거예요. 프롬프트 안에 스타일 지침을 다 넣으면 스타일을 바꿀 때마다 프롬프트 코드를 수정해야 해요. 스타일 가이드를 외부 파일로 빼서 입력으로 주입하면, 에이전트 코드는 건드리지 않고 가이드만 업데이트하면 돼요. arxiv.org 연구에서도 "프롬프트를 외부화하면 비기술자도 에이전트 동작을 수정할 수 있다"고 같은 결론을 냈어요.

3단계 — 검수 에이전트

• 입력: 작성 에이전트의 마크다운 초안
• 출력: APPROVED 또는 REJECTED + 사유 (고정 형식)
• 트리거: 작성 에이전트 출력 완료 이벤트
• 목적지: APPROVED → 발행 큐 / REJECTED → 수정 큐 (작성 에이전트로 재진입)

출력을 APPROVED/REJECTED로 고정하는 이유가 있어요. 검수 에이전트 출력을 자유 형식으로 두면 어떤 때는 "괜찮아 보여요", 어떤 때는 "수정이 필요합니다"처럼 들쑥날쑥하게 나와요. 이걸 파싱해서 다음 단계로 분기하는 코드가 점점 복잡해져요. 출력을 두 가지 상태 중 하나로 고정하면, 분기 로직이 if result == "APPROVED" 한 줄로 끝나요. 다운스트림이 단순해질수록 파이프라인 전체가 안정적으로 돌아가요.

파이프라인 전체를 그리면 이렇게 돼요.

[슬랙 커맨드] → 조사 에이전트 → [JSON 저장] 　　　　　　　　　　　　　　↓ 　　　　　　　작성 에이전트 ← [스타일 가이드] 　　　　　　　　　　　　　　↓ 　　　　　　　검수 에이전트 　　　　　　　↓　　　　　↓ 　　　　　APPROVED　　REJECTED 　　　　　　　↓　　　　　↓ 　　　　　발행 큐　　수정 큐 → 작성 에이전트 재실행

설계를 문서로 먼저 써야 하는 이유가 있나요?

코드보다 문서가 먼저여야 하는 이유는, 에러가 났을 때 어디서 난 건지 알 수 있어야 하기 때문이에요. 파이프라인이 돌다가 멈췄을 때, 설계 명세가 없으면 에이전트 코드를 하나하나 다 뜯어봐야 해요. 명세가 있으면 "조사 에이전트 출력을 받아야 하는 작성 에이전트 입력 형식이 맞나?"를 먼저 확인하고 좁혀나갈 수 있어요.

1인 빌더에게 이게 특히 중요한 이유가 또 있어요. 에이전트를 만들고 한 달 뒤에 다시 코드를 열면 왜 이렇게 짰는지 기억이 안 나는 경우가 많아요. 명세서는 미래의 자신을 위한 편지예요.

명세서에 넣으면 좋은 항목 예시예요.

이 표를 채우다 보면 "잠깐, 오류 시 동작을 정해본 적이 없었네"라는 걸 발견하게 돼요. 그게 설계의 진짜 목적이에요. 코드 짜기 전에 모르는 걸 미리 발견하는 것.

이 설계 방식이 툴 선택에도 영향을 주나요?

설계가 먼저 나오면 툴이 훨씬 쉽게 골라져요. 반대로 툴을 먼저 고르면 설계가 툴에 맞게 구부러지기 시작해요.

예를 들어 n8n과 Make.com 중 뭘 써야 하는지 고민한다면, 설계 명세를 먼저 보면 돼요. aimultiple.com에 따르면 두 툴은 청구 방식과 통합 수에서 차이가 나요. n8n은 워크플로우 실행 단위로 과금되고 자체 호스팅이 가능한 반면, Make.com은 작업(모듈 실행) 단위로 과금돼요. 조건 분기가 복잡하고 직접 서버에서 돌리고 싶다면 n8n이, 빠르게 시작하는 SaaS 형태라면 Make.com이 출발점이 되는 식이에요. 워크플로우를 먼저 그려두면 이 비교가 구체적이 돼요.

API를 직접 짠다면, 출력 형식을 고정해둔 게 얼마나 도움이 되는지 바로 느껴져요. 에이전트 간 데이터가 약속된 형식으로 오가면 중간 파싱 레이어가 필요 없어지거든요.

반대로 설계 없이 툴부터 잡으면 생기는 일이 있어요. n8n 노드를 연결하다 보면 "이 노드가 뭘 내보내야 하더라?"를 계속 되묻게 돼요. 툴을 익히는 시간보다 "내가 뭘 만들려고 했더라"를 복기하는 시간이 더 길어져요.

에이전트를 연결하다 막히는 순간의 대부분은 코드 문제가 아니라 설계 문제예요. "이 에이전트가 뭘 받아서 뭘 내보내야 하는지"가 머릿속에서 흐릿할 때 파이프라인은 멈춰요. 표 하나, 항목 네 개짜리 명세서로 시작해보세요. 코드보다 설계가 먼저예요.

한 번 더, 빠르게 짚고 갈게요

Q. 에이전트가 하나뿐인데도 워크플로우 설계가 필요한가요? A. 에이전트가 하나여도 트리거·입력·출력·오류 동작을 미리 정의해두면 나중에 두 번째 에이전트를 연결할 때 훨씬 쉬워요. 처음부터 명세서를 쓰는 습관이 파이프라인을 확장 가능하게 만들어요.

Q. 출력 형식을 APPROVED/REJECTED처럼 고정하면 너무 단순한 게 아닌가요? A. 오히려 반대예요. 출력 형식이 단순할수록 다운스트림 로직이 예측 가능해지고, 예상치 못한 분기 오류가 줄어들어요. 사유(reason)는 별도 필드로 붙이되, 판단 결과 자체는 두 가지로 고정하는 게 안정적이에요.

Q. 트리거를 수동으로 하면 자동화가 아닌 건 아닌가요? A. 트리거만 수동이고 이후 단계는 전부 자동이에요. 1인 빌더 콘텐츠 파이프라인에서 주제 선택은 사람이 해야 하는 마지막 판단이에요. "완전 자동화"보다 "사람이 1단계만 하는 반자동화"가 훨씬 실용적이에요.

Q. 설계 명세서를 어디에 관리하는 게 좋나요? A. Notion, GitHub 리포지토리의 /docs 폴더, 또는 마크다운 파일 어디든 괜찮아요. 중요한 건 에이전트 코드와 같은 레포에 두는 것. 명세와 코드가 한 곳에 있어야 둘이 따로 노는 걸 방지할 수 있어요.

Q. 에이전트 파이프라인 설계를 도와주는 툴이 있나요? A. 특별한 툴보다 종이나 텍스트 파일로 흐름도부터 그려보는 게 먼저예요. n8n의 캔버스 인터페이스를 설계 도구처럼 쓰는 사람도 많아요. 박스와 화살표로 에이전트를 연결해보면, 어디서 끊겨 있는지가 시각적으로 보여요.