Genkit Agents API 사용법: 대화 상태와 장기 작업을 풀스택 앱에 붙이는 패턴

Google Developers Blog는 2026년 7월 1일 “Build agentic full-stack apps with Genkit” 글에서 Genkit Agents API preview를 소개했습니다. 핵심은 message history, tool loop, streaming, state persistence를 풀스택 앱에서 다루기 쉽게 묶는 것입니다. TypeScript와 Go에서 preview로 제공되고, Genkit Developer UI로 agent snapshot을 테스트하고 디버깅할 수 있다는 점도 중요합니다.

개발자 입장에서 이 업데이트는 “챗봇 SDK가 하나 더 나왔다”가 아닙니다. 대화형 AI 기능을 실제 앱 기능으로 만들 때 반복해서 부딪히는 상태 관리 문제를 줄여주는 방향입니다.

에이전트 앱에서 어려운 것은 모델 호출이 아니다

LLM 호출 자체는 이제 어렵지 않습니다. 어려운 건 호출 주변입니다.

• 사용자의 이전 대화를 어디까지 기억할지
• 도구 호출 중간 상태를 어떻게 UI에 보여줄지
• 오래 걸리는 작업을 요청 후 분리해서 처리할지
• 사용자가 중간에 다른 흐름으로 분기하면 기록을 어떻게 관리할지
• 서버가 상태를 가질지, 클라이언트가 상태를 들고 있을지
• 실패한 tool loop를 어디서 재시도할지

Genkit Agents API가 강조하는 server-managed 또는 client-managed state persistence, history branching, long-running detached tasks, multi-agent coordination은 바로 이 문제를 겨냥합니다.

기본 구조: 대화 상태를 제품 기능으로 본다

많은 팀이 AI 기능을 붙일 때 “채팅창 하나”로 시작합니다. 하지만 실제 제품에서는 대화가 곧 작업 상태입니다.

예를 들어 여행 일정 앱의 AI 플래너를 생각해봅시다.

• 사용자가 일정 초안을 요청합니다.
• 에이전트가 항공편, 숙소, 이동 시간을 계산합니다.
• 사용자가 “2일차는 더 여유롭게”라고 수정합니다.
• 에이전트가 기존 일정을 일부 유지하고 일부만 바꿉니다.
• 사용자가 최종 확정하면 캘린더와 공유 링크가 생성됩니다.

이때 대화 기록은 단순 로그가 아닙니다. 일정 버전, 사용자 의도, 도구 호출 결과, 확정 상태가 섞인 작업 데이터입니다. Genkit 같은 프레임워크를 쓸 때도 이 관점이 먼저입니다.

서버 관리 상태 vs 클라이언트 관리 상태

Genkit Agents API는 state persistence를 서버 또는 클라이언트 관리 방식으로 유연하게 가져갈 수 있다고 설명합니다. 선택 기준은 명확해야 합니다.

서버 관리 상태가 맞는 경우

• 여러 기기에서 이어서 작업해야 한다.
• 결제, 예약, 문서 생성처럼 결과가 중요하다.
• 감사 로그와 재현 가능성이 필요하다.
• 장기 작업이 백그라운드에서 돌아간다.
• 민감한 도구 토큰을 서버가 관리해야 한다.

클라이언트 관리 상태가 맞는 경우

• 가벼운 개인화 대화다.
• 로그인 없이 빠르게 써보는 기능이다.
• 서버 저장 비용을 줄이고 싶다.
• 사용자가 세션을 닫으면 상태가 사라져도 된다.

실무에서는 둘을 섞는 경우가 많습니다. 예를 들어 초안 생성 중간 대화는 클라이언트가 들고 있다가, 사용자가 “저장”을 누르는 순간 서버 상태로 승격시키는 방식입니다.

장기 작업은 detached task로 분리한다

AI 에이전트가 외부 도구를 여러 번 호출하면 응답 시간이 길어집니다. 사용자에게 30초, 60초 동안 로딩 스피너만 보여주는 건 좋지 않습니다. Genkit이 long-running detached tasks를 언급하는 이유도 여기에 있습니다.

장기 작업은 다음처럼 분리하는 게 좋습니다.

1. 사용자가 작업을 요청합니다.
2. 서버는 task id를 즉시 반환합니다.
3. 백그라운드 worker가 에이전트 실행을 이어갑니다.
4. 프론트엔드는 streaming 또는 polling으로 상태를 보여줍니다.
5. 완료 후 결과 snapshot을 저장합니다.

이 구조에서는 실패 처리도 쉬워집니다. task 단위로 재시도하고, 사용자에게 “자료 조사 중”, “초안 작성 중”, “검토 중” 같은 상태를 보여줄 수 있습니다.

history branching은 언제 필요한가

대화형 앱에서는 사용자가 “아까 버전으로 돌아가서 다시 해줘”라고 자주 말합니다. 단순 append-only history만 있으면 어렵습니다. history branching은 특정 시점에서 다른 방향의 대화를 만들 수 있게 합니다.

활용 사례는 많습니다.

• 코드 생성: 구현안 A와 B 비교
• 마케팅 카피: 톤별 문구 분기
• 여행 일정: 예산형과 여유형 분기
• 리포트 작성: 보수적 분석과 공격적 분석 분기
• 고객 지원: 정책 안내와 예외 처리 분기

중요한 건 모든 메시지를 무한히 저장하는 게 아니라, 분기 기준이 되는 snapshot을 명확히 저장하는 것입니다. 그래야 비용과 복잡도를 줄일 수 있습니다.

Developer UI를 운영 전에 쓰는 법

Genkit Developer UI는 테스트, 디버깅, agent snapshot 점검에 유용하다고 소개됐습니다. 이런 도구는 데모용으로만 쓰면 아깝습니다. 운영 전 QA 흐름에 넣어야 합니다.

추천하는 테스트 케이스는 다음과 같습니다.

• 정상 요청: 가장 흔한 사용자 플로우
• 애매한 요청: 정보가 부족한 상태
• 긴 요청: 컨텍스트가 길어지는 상태
• 도구 실패: 외부 API가 500 또는 timeout을 반환
• 중단 후 재개: 사용자가 나갔다가 돌아오는 상태
• 분기: 이전 버전에서 다른 결과를 만드는 상태

이 케이스를 snapshot으로 남기면 프롬프트를 수정하거나 모델을 바꿀 때 회귀 테스트처럼 사용할 수 있습니다.

바로 적용할 체크리스트

• AI 대화 기록을 단순 로그가 아니라 작업 상태로 모델링
• 서버 관리 상태와 클라이언트 관리 상태 기준 정의
• 10초 이상 걸리는 플로우는 detached task 구조로 분리
• task id, status, result snapshot, error reason 스키마 작성
• history branching이 필요한 사용자 시나리오를 먼저 선정
• tool loop 중간 상태를 프론트엔드에 보여주는 이벤트 설계
• Developer UI 또는 별도 harness로 정상·실패·분기 케이스 테스트

Genkit Agents API의 가치는 모델 호출 추상화보다 상태 관리에 있습니다. 대화형 AI 기능을 제품 기능으로 만들려면 “무엇을 기억하고, 어디서 재개하고, 언제 분기할지”를 먼저 설계해야 합니다. 그 다음에야 tool loop와 streaming이 안정적으로 붙습니다.