AI 에이전트 앱은 모델을 잘 고른다고 완성되지 않습니다. 모델 API가 간헐적으로 실패하면 재시도 로직이 필요하고, 파일을 삭제하거나 결제를 처리하는 도구라면 사람의 확인이 있어야 하며, 경쟁사 제품명을 절대 출력하면 안 되는 비즈니스 룰도 있습니다. 이 요구들을 프롬프트나 각 코드에 직접 심으면, 앱이 커질수록 관리가 어려워집니다.

Google이 오픈소스 AI 에이전트 프레임워크 Genkit에 미들웨어 시스템을 추가했습니다. 에이전트의 생성 루프 안에 재사용 가능한 훅(hook)을 끼워 넣어, 공통적인 운영 로직을 앱 코드와 분리해 관리할 수 있게 해주는 기능입니다. TypeScript, Go, Dart에서 사용 가능하며, Python 지원은 곧 추가될 예정입니다.

출처: Announcing Genkit Middleware: Intercept, extend, and harden your agentic apps – Google Developers Blog

에이전트 루프의 3단 후킹 구조

Genkit에서 generate()를 호출하면 내부적으로 tool loop가 작동합니다.

1. 모델이 출력을 생성합니다
2. 필요한 도구(tool)가 실행됩니다
3. 결과가 다시 모델로 입력됩니다
4. 모델이 완료 신호를 낼 때까지 반복합니다

미들웨어는 이 루프의 세 지점에 각각 훅을 붙입니다. Generate 훅은 루프 한 번 돌 때마다 실행되며 컨텍스트 주입이나 메시지 재작성에 씁니다. Model 훅은 모델 API 호출마다 실행되며 재시도나 캐싱에 적합합니다. Tool 훅은 도구 실행 직전마다 끼어들어 사람의 승인이나 샌드박싱을 처리합니다. 어느 층에 로직을 배치하느냐에 따라 동작 범위와 시점을 세밀하게 조절할 수 있습니다.

바로 쓸 수 있는 5가지 프리빌트 미들웨어

Genkit은 자주 쓰이는 패턴을 프리빌트 미들웨어로 제공합니다.

Retry는 모델 API 호출이 일시적 오류로 실패했을 때 재시도 간격을 점진적으로 늘려가며 자동으로 다시 시도합니다. 재시도는 모델 호출에만 적용되며, 이미 실행된 tool loop 전체를 다시 돌리지는 않습니다.

Fallback은 주 모델이 쿼터를 초과하거나 지정된 오류 코드로 실패했을 때 다른 모델로 자동 전환합니다. 예시 코드에서는 Gemini가 실패하면 Claude로 넘어가는 설정이 등장합니다.

Tool Approval은 허용 목록에 없는 도구가 실행될 때 멈추고 사람의 확인을 기다립니다. “임시 파일 삭제”처럼 되돌리기 어려운 동작을 에이전트가 자동으로 수행하기 전에 사람이 개입할 수 있게 합니다.

Skills는 지정된 디렉터리의 SKILL.md 파일들을 시스템 프롬프트에 자동으로 주입합니다. 모델이 특정 스킬을 필요로 할 때 동적으로 로드하는 use_skill 도구도 함께 제공됩니다.

Filesystem은 지정된 루트 디렉터리 안으로 파일 접근을 제한하는 도구들을 모델에게 부여합니다. 경로 탈출(path escape)을 원천적으로 막아, 모델이 허용 범위 밖의 파일에 접근하지 못하도록 강제합니다.

커스텀 미들웨어와 조합의 힘

프리빌트가 다루지 못하는 요구는 직접 만들 수 있습니다. 예를 들어, 경쟁사 브랜드명이나 내부 가격 정보가 모델 출력에 포함되지 않도록 걸러내는 콘텐츠 필터를 약 20줄로 작성할 수 있습니다. 이 규칙을 매 프롬프트에 넣는 대신 미들웨어로 분리하면, 앱의 어느 generate() 호출에도 일관되게 적용됩니다.

미들웨어는 여러 개를 선언 순서대로 쌓을 수 있습니다. Retry를 바깥에, ContentFilter를 안쪽에 배치하면 필터를 통과한 응답에만 재시도가 작동하는 식으로 조합합니다. 순서가 동작에 영향을 주고, Genkit은 그 순서를 코드에서 명시적으로 드러냅니다.

에이전트 앱 개발에 갖는 의미

에이전트 앱의 운영 요구사항(신뢰성, 안전성, 관찰 가능성)은 모델 선택과는 별개의 문제입니다. 지금까지는 이 요구들을 각 앱 코드 안에 흩어 구현하거나, 프롬프트에 의존하는 방식으로 처리해왔습니다. Genkit의 미들웨어 시스템은 이 로직을 레이어로 분리하고, 재사용 가능한 단위로 조합하는 방식을 제안합니다.

커스텀 미들웨어를 패키지로 공개해 다른 개발자가 가져다 쓸 수 있다는 점도 눈에 띕니다. 에이전트 앱 개발의 공통 패턴이 오픈소스 미들웨어 생태계로 축적될 가능성이 있습니다.

참고자료:

• Genkit 미들웨어 공식 문서