Google Genkit Middleware 발표: 에이전트 앱에 재시도·Fallback·도구 승인 붙이는 법

 

Google Genkit Middleware 발표: 에이전트 앱 운영 규칙을 코드로 붙이는 법

Gemini 기반 에이전트 앱에 retry, fallback, human-in-the-loop, 파일 접근 제한을 넣는 실무 관점 정리

 

Google Genkit Middleware 발표, 무엇이 달라졌나

 

Google은 2026년 5월 14일 Genkit Middleware를 공식 발표했습니다. Google Genkit Middleware 에이전트 앱에서 중요한 변화는 generation 호출과 도구 실행 루프 사이에 retry, fallback, 승인, 파일 접근 제한 같은 운영 규칙을 조합해 넣을 수 있다는 점입니다.

이 소식은 새 패키지 하나가 추가됐다는 정도로만 보면 조금 밋밋합니다. 제가 보기에는 Genkit이 프롬프트 작성 보조 도구를 넘어, 에이전트 앱을 운영 대상 서비스로 다루기 위한 제어 지점을 공개한 쪽에 가깝습니다.

에이전트 앱은 모델을 한 번 호출하고 끝나는 구조가 아닙니다. 모델이 도구를 부르고, 도구 결과를 다시 모델에 넣고, 그 사이에서 실패·비용·권한·로그 문제가 생깁니다. Google Genkit Middleware 에이전트 앱 발표는 이 반복 흐름 중간에 개발자가 직접 정책을 끼워 넣는 방법을 다룹니다.

> 프롬프트로 부탁하는 규칙이 아니라, 코드 레벨에서 호출 흐름을 감싸는 규칙이라는 점이 포인트입니다.

한국 사용자 입장에서는 Gemini 기반 사내 자동화, 파일 작업 에이전트, 고객지원 보조 도구를 만들 때 먼저 살펴볼 만합니다. 다만 이 글은 보안이 자동으로 해결된다는 이야기가 아니라, 어디에 어떤 멈춤 장치와 관측 지점을 둘지 확인하는 글입니다.

 

 

2026년 5월 Genkit Middleware 타임라인

 

2026년 5월 12일 Genkit JS v1.34.0 릴리스 흐름과 2026년 5월 14일 공식 발표를 같이 보면 맥락이 선명해집니다. 문서 기준 확인일인 2026년 5월 16일에는 JavaScript 패키지와 Dart 패키지 경로도 확인됩니다.

날짜를 정리하면 오해가 줄어듭니다. 특히 Python 사용자는 지금 쓸 수 있는 범위와 기다려야 하는 범위를 나눠 봐야 합니다.

날짜	확인한 내용	의미
2026-05-12	Genkit JS v1.34.0 릴리스 태그 공개	Middleware 발표 직전의 Genkit 릴리스 흐름
2026-05-14	Google Developers Blog 공식 발표	Generate, Model, Tool hook과 내장 middleware 소개
2026-05-14	TypeScript, Go, Dart 사용 가능 안내	Python Middleware는 coming soon으로 분리
2026-05-16	`@genkit-ai/middleware`, `genkit_middleware` 문서 확인	TypeScript와 Dart 시험 경로 확인 가능

Google Genkit Middleware 에이전트 앱을 지금 시험한다면 TypeScript 쪽 문서가 가장 직접적입니다. Dart도 pub.dev의 `genkit_middleware` 패키지로 경로가 잡혀 있습니다. Go는 공식 발표에서 지원 언어로 언급되지만, 처음 확인하는 개인 개발자라면 JavaScript 문서의 예시가 가장 빠른 진입점입니다.

 

기존 tool calling과 무엇이 다른가

 

tool calling이 모델이 어떤 도구를 부를지 정하는 기능이라면, Middleware는 그 호출 전후에 정책을 적용하는 계층입니다. 공식 발표 기준 hook은 Generate, Model, Tool 세 레이어에 붙습니다.

Genkit Middleware를 이해할 때는 역할을 나눠 보면 쉽습니다. tool calling은 모델과 도구 사이의 연결 방식입니다. Middleware는 그 연결이 실제로 실행되는 동안 개발자가 규칙을 삽입하는 자리입니다.

구분	주로 다루는 것	예시
프롬프트 규칙	모델에게 말로 지시	삭제 전에는 사용자에게 확인하라고 쓰기
tool calling	모델이 호출할 도구 정의	`send_email`, `read_file`, `deploy_service` 같은 도구 등록
Middleware	호출 전후의 실행 정책	retry, fallback, 승인 대기, 파일 접근 범위 제한

공식 설명에서 Generate hook은 generate 흐름과 도구 루프 반복을, Model hook은 모델 API 호출을, Tool hook은 개별 도구 실행을 다룹니다. 예를 들어 retry는 모델 호출 실패에 붙는 쪽이 자연스럽고, toolApproval은 도구 실행 직전에 의미가 있습니다.

실제로 확인할 부분은 middleware 순서입니다. 발표문은 미들웨어 스택이 왼쪽에서 오른쪽 순서로 적용되며 순서가 중요하다고 설명합니다. fallback을 먼저 둘지, retry를 먼저 둘지, 승인 미들웨어를 어떤 도구 앞에 둘지에 따라 운영 결과가 달라질 수 있습니다.

 

 

에이전트 앱 운영에서 중요한 이유

 

에이전트 앱은 한 번의 응답 품질보다 실패 복구, 비용 제어, 위험한 도구 호출 승인, 관측성이 더 중요해집니다. Genkit Middleware는 이런 운영 규칙을 프롬프트 문장에만 맡기지 않고 코드의 hook으로 분리하려는 업데이트입니다.

이 발표가 흥미로운 이유는 기능 이름보다 운영 문제에 있습니다. 모델 API가 일시적으로 실패하면 retry가 필요합니다. 특정 모델이나 provider가 막히면 fallback을 검토해야 합니다. 파일을 읽고 쓰는 에이전트라면 rootDirectory와 쓰기 권한을 제한해야 합니다. 결제, 삭제, 배포 같은 도구 호출은 사람이 승인하는 단계가 필요합니다.

이런 규칙을 모두 프롬프트에 적어 두면 시작은 빠릅니다. 하지만 운영 중에는 추적과 검증이 어렵습니다. 제가 보기에는 Middleware가 겨냥하는 지점은 모델을 더 똑똑하게 만드는 일이 아니라, 모델 주변의 실패와 권한을 더 눈에 보이게 만드는 일입니다.

공식 발표는 Genkit Developer UI에서 middleware 구성을 보고 hook 레이어별 trace를 확인할 수 있다고 소개합니다. 개인 프로젝트라도 첫 테스트에서 trace를 보는 편이 좋습니다. 답이 잘 나왔는지만 보면 retry가 실제로 모델 호출에 걸렸는지, toolApproval이 원하는 도구에서 멈췄는지 놓치기 쉽습니다.

 

 

도입 시뮬레이션: 설치, 첫 테스트, 운영 모델

 

처음 시험한다면 TypeScript 프로젝트에서 `@genkit-ai/middleware`를 설치하고 retry 또는 toolApproval 하나만 붙여 작은 generate 호출로 trace를 확인하는 흐름이 적합합니다. 한 번에 모든 middleware를 켜기보다 실패·승인·파일 접근 중 하나의 문제를 정해 검증하는 편이 안전합니다.

가장 작은 실험은 모델 호출 실패를 다루는 retry입니다. 공식 JavaScript 문서는 `@genkit-ai/middleware` 설치 경로를 제시합니다. TypeScript Genkit flow에 retry middleware 하나만 붙이고, Genkit Developer UI에서 모델 호출 trace가 남는지 보는 흐름이면 충분합니다.

두 번째 실험은 toolApproval입니다. 삭제, 배포, 결제, 외부 API 전송처럼 되돌리기 어려운 도구를 하나 정하고 승인 목록 밖 호출이 interrupt로 멈추는지 확인합니다. 여기서 중요한 점은 승인 UI와 감사 로그 저장은 애플리케이션 쪽 책임이라는 점입니다.

운영 모델은 설정값을 문서화해야 합니다. 예를 들어 `fallback models`, `retry statuses`, `allowed tools`, `rootDirectory`, `allowWriteAccess`, trace 확인 위치를 별도 설정으로 관리합니다. Genkit Middleware를 팀에서 쓴다면 코드 리뷰에서 프롬프트보다 이 설정 파일을 더 꼼꼼히 봐야 할 때가 많습니다.

호환해서 볼 대상은 `genkit-ai/genkit` 저장소, `@genkit-ai/middleware` 패키지, Dart의 `genkit_middleware`, 그리고 Genkit Developer UI입니다. 작은 팀의 첫 적용 후보는 고객지원 초안 생성보다 내부 개발 자동화 쪽이 현실적입니다. 파일 읽기 범위를 특정 작업 디렉터리로 제한하고, 쓰기 권한을 기본 꺼짐으로 두고, 위험한 도구만 승인 대기시키면 실험 범위를 좁힐 수 있습니다.

 

기능별 사용 판단: retry, fallback, toolApproval, filesystem, skills

 

retry는 일시적 모델 오류, fallback은 모델 또는 provider 장애 대응, toolApproval은 파괴적 도구 호출 전 승인, filesystem은 제한된 작업 디렉터리 접근, skills는 작업 지침 주입에 맞습니다.

기능 이름만 보면 모두 안전장치처럼 보이지만, 쓰임새는 꽤 다릅니다. 섞어 쓰기 전에 각 middleware가 막는 문제를 분리해야 합니다.

Middleware	먼저 쓸 상황	조심할 점
retry	일시적 모델 오류, quota성 실패, 네트워크성 실패를 흡수하고 싶을 때	도구 루프 전체를 무조건 다시 실행하는 장치로 보면 안 됩니다
fallback	기본 모델 실패 시 다른 모델이나 provider로 넘기고 싶을 때	입력·출력 스키마, 비용, 지연시간, tool calling 호환성을 따로 봐야 합니다
toolApproval	삭제, 결제, 배포, 외부 전송 전 사람이 승인해야 할 때	승인 UI, 권한 정책, 감사 로그는 직접 설계해야 합니다
filesystem	에이전트가 파일을 읽거나 제한적으로 써야 할 때	`rootDirectory`와 `allowWriteAccess`를 운영 기준으로 고정해야 합니다
skills	SKILL.md 기반 작업 지침을 필요할 때 불러오고 싶을 때	skill 내용이 시스템 프롬프트에 들어가는 범위를 검토해야 합니다

여기서 볼 부분은 retry와 toolApproval의 조합입니다. retry는 실패 복구를 맡고, toolApproval은 되돌리기 어려운 행동의 멈춤 지점을 담당합니다. fallback은 더 강력하지만 provider별 비용과 응답 차이를 검증해야 해서 두 번째 단계로 두는 편이 낫습니다.

 

 

 

주의할 점: Python, 보안, API 안정성

 

Python용 Middleware는 공식 발표 기준 coming soon이므로 지금 바로 사용 가능하다고 보면 안 됩니다. toolApproval도 보안 자동 해결책이 아니라 human-in-the-loop 구현 패턴이며, interrupts 문서의 Beta 안내를 함께 봐야 합니다.

다만 여기서 조심할 점은 명확합니다. 첫째, Python 사용자라면 Genkit 자체 문서와 Middleware 지원 상태를 분리해야 합니다. 이번 Middleware 발표에서 Python은 추후 지원으로 안내됐습니다.

둘째, toolApproval은 승인 목록 밖 도구 호출을 멈추는 구조를 제공합니다. 하지만 어떤 사용자가 승인할지, 승인 로그를 어디에 저장할지, 거부 후 flow를 어떻게 종료할지는 앱 쪽 설계입니다. 금융 결제, 고객 데이터 변경, 배포 자동화처럼 리스크가 큰 흐름에서는 이 부분을 가볍게 넘기면 안 됩니다.

셋째, filesystem middleware는 접근 범위를 줄이는 데 도움이 되지만 권한 설계의 끝은 아닙니다. `rootDirectory`를 잘못 잡으면 민감 파일이 포함될 수 있고, `allowWriteAccess`를 켜는 순간 테스트와 운영의 위험도가 달라집니다.

Google Genkit Middleware 에이전트 앱은 모든 에이전트 문제를 해결하는 만능 장치라기보다, 운영 규칙을 코드로 분리할 수 있게 해 주는 새 레이어입니다. 그래서 첫 도입 판단은 기능 수가 아니라 실패했을 때 멈출 위치가 보이는지로 해야 합니다.

 

자주 묻는 질문

 

Q. Genkit Middleware는 무엇인가?
A. Genkit의 generate 호출과 도구 실행 루프 사이에 정책을 넣는 hook 시스템입니다. 공식 발표 기준 Generate, Model, Tool 레이어에 붙을 수 있고, retry, fallback, toolApproval, filesystem, skills 같은 내장 middleware가 문서화되어 있습니다. 프롬프트 지시만으로 처리하던 운영 규칙을 코드 흐름에 붙인다는 점이 다릅니다.

Q. Gemini 에이전트 앱에서 retry와 fallback은 각각 언제 써야 합니까?
A. retry는 RESOURCE_EXHAUSTED나 UNAVAILABLE처럼 일시적 모델 generation 오류를 흡수할 때 먼저 검토합니다. fallback은 기본 모델이나 provider가 실패했을 때 다른 모델로 넘기는 선택지이지만, 비용·지연시간·출력 스키마·tool calling 호환성을 별도로 확인해야 합니다.

Q. Genkit toolApproval은 실제 도구 실행을 막습니까?
A. 승인 목록에 없는 도구 호출을 interrupt로 멈추고, 애플리케이션이 승인 또는 거부 로직을 처리한 뒤 재개하는 방식입니다. 다만 승인 UI, 권한 정책, 감사 로그 저장은 middleware가 자동으로 완성해 주는 영역이 아닙니다.

Q. filesystem middleware를 쓰면 모델이 모든 파일을 읽고 쓸 수 있습니까?
A. 아닙니다. 문서 기준 filesystem middleware는 `rootDirectory` 안으로 접근을 제한하며, JavaScript 문서에서 `allowWriteAccess` 기본값은 false입니다. 운영에서는 rootDirectory에 민감 파일이 들어가지 않는지 먼저 확인해야 합니다.

Q. Python용 Genkit Middleware는 지금 사용할 수 있습니까?
A. 공식 발표 기준 Middleware는 TypeScript, Go, Dart에서 사용 가능하고 Python 지원은 coming soon으로 안내되어 있습니다. Python 프로젝트라면 지금은 TypeScript 쪽으로 작은 PoC를 분리하거나 Python 지원 문서가 업데이트될 때까지 기다리는 편이 안전합니다.

Q. 개인 개발자가 가장 먼저 시험해 볼 구성은 무엇입니까?
A. TypeScript Genkit 프로젝트에서 `@genkit-ai/middleware`를 설치하고 retry 하나를 붙인 뒤 Genkit Developer UI trace를 확인하는 구성이 가장 작습니다. 그다음 되돌리기 어려운 더미 도구 하나를 정해 toolApproval interrupt 흐름을 시험하면 운영 판단에 필요한 정보가 빨리 나옵니다.

함께 읽으면 좋은 글

 

• Red Hat AI 3.4 업데이트: AgentOps, MCP Gateway, Eval Hub가 중요한 이유 — AI UPDATES
• GitHub Copilot App 기술 미리보기: 코딩 에이전트가 독립 앱으로 나온 이유 — AI UPDATES
• Claude Code Agent View와 /goal: 코딩 에이전트가 '끝날 때까지' 일하는 방식 — AI UPDATES

참조 링크

 

• Announcing Genkit Middleware: Intercept, extend, and harden your agentic apps — 2026년 5월 14일 Genkit Middleware 공식 발표 원문
• Middleware | Genkit — JavaScript 설치 경로, 내장 middleware, 옵션 확인
• Pause generation using interrupts | Genkit — toolApproval과 연결되는 interrupt 및 Beta 안내 확인
• Developer tools | Genkit — Genkit Developer UI와 trace 확인 흐름 참고
• Telemetry collection | Genkit — 운영 관측성 흐름을 추가로 확인할 때 참고할 문서
• genkit-ai/genkit — Genkit 공식 오픈소스 저장소
• genkit@1.34.0 release — 2026년 5월 릴리스 흐름 확인
• genkit_middleware | Dart package — Dart용 Genkit Middleware 패키지 확인