Genkit Agents API 프리뷰: 풀스택 에이전트 앱 구조가 바뀌는 지점

Google이 2026년 7월 1일 Genkit Agents API 프리뷰를 공개했다. Genkit은 TypeScript, Go, Dart, Python을 지원하는 오픈소스 프레임워크이고, 이번 Agents API의 초점은 “대화형 AI 앱에서 반복되는 배관 작업을 하나의 인터페이스로 묶는 것”이다. 메시지 히스토리, tool loop, streaming, persistence, frontend protocol을 매번 직접 붙이던 팀이라면 확인할 만한 업데이트다.

다만 이 소식은 “새 프레임워크가 나왔다” 정도로 읽으면 손해다. 실제로는 풀스택 에이전트 앱의 책임 경계가 어디로 이동하는지 보여준다. 이제 개발자는 단발성 generate() 호출이 아니라, 세션 상태와 도구 실행, 중단·재개, 승인 흐름, 장기 작업을 하나의 제품 흐름으로 설계해야 한다.

무엇이 달라졌나

기존 대화형 기능은 대개 다음 코드 조각들의 모음이었다.

• 서버에서 모델 호출
• DB에 메시지 저장
• tool call 결과 반영
• SSE나 WebSocket으로 스트리밍
• 클라이언트에서 상태 병합
• 사용자가 승인해야 하는 작업의 보류 처리
• 긴 작업의 백그라운드 실행과 재접속

Genkit Agents API는 이 반복 구조를 agent 객체와 chat 인터페이스로 감싼다. 서버에서 agent를 정의하고, 같은 agent를 in-process 또는 HTTP endpoint 뒤에서 실행할 수 있다. Google 문서 기준 프리뷰는 TypeScript와 Go에서 제공되며, minor version에서 breaking change가 날 수 있다는 점도 명시되어 있다.

개발팀 입장에서는 API 표면보다 운영 모델이 중요하다. “대화가 길어지면 상태를 어디에 둘 것인가”, “도구 실행 중 사용자의 승인을 어떻게 받을 것인가”, “탭을 닫아도 진행해야 하는 작업은 어떻게 재개할 것인가”가 설계 질문이 된다.

서버 관리 상태와 클라이언트 관리 상태의 선택

Agents API는 서버 관리 state와 클라이언트 관리 state를 모두 다룬다. 서버 관리 방식은 session store를 붙여 메시지, custom state, artifact를 snapshot으로 저장한다. 사용자는 sessionId로 최신 상태를 이어가거나 snapshotId로 특정 시점에서 분기할 수 있다. 팀 단위 업무, 고객지원, 장기 리포트 생성처럼 대화가 여러 기기와 시간에 걸쳐 이어지는 기능에 적합하다.

클라이언트 관리 방식은 서버가 전체 상태를 반환하고, 클라이언트가 다음 turn에 다시 보낸다. 서버를 stateless하게 유지하고 싶거나 앱이 이미 자체 persistence를 갖고 있을 때 유용하다. 단, 상태 크기, 민감 정보 노출, 클라이언트 변조 가능성을 별도로 관리해야 한다.

실무 기준은 명확하다. 결제, 배포, 계정 변경, 문서 생성처럼 결과물이 남는 작업은 서버 관리가 안전하다. 짧은 튜터링, 임시 질의응답, 로컬 UI 보조 기능은 클라이언트 관리도 가능하다.

HTTP endpoint와 프론트엔드 프로토콜의 의미

Genkit agent는 servable action으로 노출할 수 있고, route helper가 turn endpoint와 snapshot, abort companion을 연결한다. 프론트엔드는 remoteAgent를 통해 같은 chat 인터페이스로 접근한다. 이 구조는 프론트엔드 팀에게 꽤 큰 의미가 있다.

첫째, 스트리밍 포맷을 매번 설계하지 않아도 된다. 텍스트 chunk뿐 아니라 custom state와 artifact 변경을 함께 받을 수 있다. 예를 들어 리포트 생성 agent가 “자료 수집 중”, “초안 작성 중”, “표 생성 완료” 같은 상태와 실제 산출물을 동시에 흘려보낼 수 있다.

둘째, 백엔드 언어가 바뀌어도 클라이언트 프로토콜을 유지할 수 있다. JavaScript나 Go backend가 같은 wire protocol을 제공한다면 제품 UI는 덜 흔들린다.

셋째, Vercel AI SDK UI를 쓰는 팀은 Genkit adapter를 통해 기존 UI 구성요소와 연결할 수 있다. 이미 useChat 기반으로 인터페이스를 만든 팀이라면 마이그레이션 비용을 낮출 여지가 있다.

Human approval이 기본 설계가 되는 이유

이번 발표에서 눈에 띄는 부분은 interruptible tool이다. 도구가 사용자 승인 없이는 계속 진행하지 않도록 turn을 중단하고, 클라이언트가 approve, reject, 값 보완을 한 뒤 resume한다. shell command, 결제, 배포, 외부 메시지 발송처럼 자동 실행이 위험한 작업에 필수다.

여기서 중요한 건 “프롬프트에 위험하면 물어보라고 쓴다”가 아니라 런타임 레벨에서 중단을 표현한다는 점이다. tool이 interrupt를 반환하고, resume payload를 세션 히스토리 기준으로 검증해야 forged input 위험을 줄일 수 있다. 에이전트 UX는 부드럽게 보여도 내부는 승인 가능한 transaction처럼 다뤄야 한다.

긴 작업과 detached turn

실무 에이전트는 사용자가 브라우저 탭을 열어둔 30초 안에 끝나지 않는다. 시장 리포트 작성, 코드베이스 리팩터링, 대량 문서 요약, 데이터 정제는 몇 분에서 몇십 분 걸린다. Genkit은 server-managed state에서 turn을 detach하고 snapshotId로 나중에 재접속하는 흐름을 제공한다.

이 기능은 단순 편의가 아니다. 제품 신뢰성의 기본이다. 사용자가 모바일로 이동하거나 네트워크가 끊겨도 작업이 계속되고, 상태를 poll하거나 abort할 수 있어야 한다. 백그라운드 agent를 제품에 넣는 팀은 작업 큐, timeout, idempotency, partial result 저장 정책까지 같이 설계해야 한다.

도입 전 체크할 리스크

프리뷰 API라는 점은 무시하면 안 된다. TypeScript와 Go에서 먼저 열렸고, minor version breaking change 가능성이 있다. 따라서 핵심 결제나 배포 자동화에 바로 깊게 넣기보다는 내부 도구나 베타 기능에서 시작하는 게 안전하다.

또 하나는 persistence 비용이다. 모든 성공 turn이 snapshot을 남기면 저장량과 개인정보 보존 문제가 생긴다. snapshot 보존 기간, 사용자 삭제 요청 처리, artifact 접근 권한을 제품 요구사항에 넣어야 한다.

실행 체크리스트

• 단발성 호출인지, 세션형 agent인지 먼저 구분한다.
• 서버 관리 state가 필요한 기능과 클라이언트 관리 state가 충분한 기능을 나눈다.
• 결제, 배포, shell, 외부 전송 tool은 interruptible tool로 설계한다.
• snapshot 보존 기간과 개인정보 삭제 정책을 정한다.
• 긴 작업은 detach, poll, abort UX를 처음부터 넣는다.
• 프리뷰 API 변경에 대비해 Genkit wrapper layer를 둔다.
• UI에는 text stream뿐 아니라 custom state와 artifact 상태를 노출한다.
• 평가 환경에서는 session branch와 snapshot replay를 테스트 케이스로 만든다.

출처: Google Developers Blog, “Build agentic full-stack apps with Genkit”