대부분의 "AI 에이전트 프레임워크 (AI agent frameworks)"는 50가지 옵션이 담긴 거대한 Agent 클래스를 던져주고 운 좋게 작동하기를 바랍니다. Genkit은 다른 방식을 택합니다. 에이전트는 이미 사용 중인 동일한 작은 프리미티브 (primitives) (도구 (tools), 미들웨어 (middleware), 인터럽트 (interrupts), 세션 (sessions), 스트리밍 (streaming))로 구축됩니다. 따라서 고급 동작은 단순히 덧붙여지는 것이 아니라 계층적으로 조합 (composes in layers) 됩니다.

그 결과, 인간 참여형 승인 (human-in-the-loop approval), 샌드박스형 코딩 어시스턴트 (sandboxed coding assistant), 그리고 멀티 에이전트 위임 (multi-agent delegation)이 별개의 기능이 아닌 프레임워크의 결과물이 됩니다. 이들은 그저 몇 가지 아이디어가 서로 맞물려 돌아가는 것뿐입니다. 이것이 바로 "전체가 부분의 합보다 크다"는 개념이며, 실제로 사용하기 매우 즐겁습니다.

요약 (TL;DR)

굵은 글씨만 읽는다면:

• 작동하는 에이전트는 약 10줄 내외입니다. ai.defineAgent({ system, tools, store }) + agent.chat().sendStream().
• 상태 (state)가 저장될 위치를 직접 선택합니다. 서버 관리형 세션을 위해 store를 전달하거나, 클라이언트 관리형 상태를 위해 생략할 수 있습니다 (클라이언트가 상태 블롭 (state blob)을 왕복 처리). 동일한 에이전트, 동일한 API입니다.
• 인터럽트 (Interrupts)는 도구 호출 (tool call)을 일시 정지 버튼으로 바꿉니다. 핸들러가 없는 "도구 (tool)"를 정의하면, 실행이 중단되고 제어권이 사용자에게 넘어갔다가 중단된 지점에서 정확히 재개됩니다. 이것이 인간 참여형 (human-in-the-loop)을 구현하는 방식입니다.
• 미들웨어 (Middleware)는 한 줄씩 실제 기능을 추가합니다. use: [...] 배열을 통해 파일 시스템, 기술 라이브러리 (skills library), 승인 게이트 (approval gates), 재시도 (retries), 그리고 하위 에이전트 위임 (sub-agent delegation)을 쌓아 올릴 수 있습니다.
• 각 구성 요소가 서로를 강화합니다. 승인 게이트 미들웨어는 사용자가 직접 사용하는 것과 동일한 인터럽트 메커니즘을 기반으로 구축되었습니다. 하위 에이전트 (Sub-agents)는 단지 도구로서의 에이전트일 뿐입니다. 아티팩트 (Artifacts)가 그들 사이를 흐릅니다.
• 동일한 에이전트가 서버와 브라우저 모두에서 실행됩니다. 백엔드에서는 expressHandler(agent), 클라이언트에서는 remoteAgent({ url })를 사용하며, 스트리밍 및 인터럽트-재개 (interrupt-resume) 시맨틱 (semantics)은 동일합니다.

아래의 모든 내용은 이러한 포인트들을 확장하여 설명하며, 모든 코드 스니펫은 Genkit 리포지토리의 실제 샘플에서 가져왔습니다. 관심 있는 부분으로 건너뛰세요.

1. 10줄짜리 에이전트

가장 작은 단위부터 시작하세요. 도구(Tool), 에이전트(Agent), 그리고 채팅(Chat)입니다:

import { z } from 'genkit';
import { FileSessionStore } from 'genkit/beta';
import { ai } from './genkit.js';
...

이와 대화하는 것은 일반적인 Node.js를 사용하는 것처럼 느껴집니다. 채팅을 시작하고, 메시지를 보내고, 청크(Chunks)를 스트리밍하세요:

const chat = weatherAgent.chat();
const turn = chat.sendStream('What is the weather like in London?');

...

멀티턴(Multi-turn)은 기본으로 제공됩니다. 단일 chat 객체는 해당 store를 통해 턴(Turn) 간의 상태(State)를 유지하므로, 후속 질문은 단순히 또 다른 send일 뿐입니다:

await chat.sendStream('What about Paris?').response;
await chat.sendStream('now say that in French').response;

단 한 줄로 상태가 어디에 저장될지 제어할 수 있습니다. 해당 store는 서버 관리형(server-managed) 상태를 제공합니다. 즉, 세션이 서버에 존재하며 채팅이 이를 대신 추적합니다. store를 제거하면 에이전트는 _클라이언트 관리형(client-managed)_이 됩니다. 클라이언트가 상태 블롭(State blob)을 소유하고 매 턴마다 이를 다시 전달(Echo)하는 방식입니다. 동일한 에이전트와 동일한 채팅 API를 사용하지만, 메모리를 누가 보유할지만 선택하면 됩니다 (브라우저에서는 remoteAgent가 왕복 과정을 대신 처리해 줍니다).

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

store를 생략하면 에이전트는 서버 측에서 상태가 없는(Stateless) 상태가 됩니다. 클라이언트가 보유한 블롭으로부터 재개한 다음, 업데이트된 블롭을 다시 전달합니다:

// `store` 없음 → 클라이언트가 세션 상태를 소유함.
export const weatherAgentStateless = ai.defineAgent({
  name: 'weatherAgentStateless',
...

왜 신경 써야 할까요? 서버 관리형 상태는 신뢰할 수 있는 백엔드에 가장 단순한 방식입니다. 클라이언트 관리형 상태는 서버가 턴 사이에 아무것도 보유하지 않음을 의미합니다. 이는 상태가 없는(Stateless)/서버리스(Serverless) 배포, 쉬운 수평 확장(Horizontal scaling), 또는 (서버가 아닌) 클라이언트가 대화의 주권을 가져야 할 때 유용합니다. 도구 호출(Tool-calling)과 멀티턴은 어떤 방식이든 동일하게 작동합니다.

이것이 전체 기본 레이어입니다. 이제 그 위에 레이어를 쌓음으로써 얼마나 많은 것을 얻을 수 있는지 확인해 보세요.

2. 인터럽트(Interrupts): (의도적으로) 실행되지 않는 도구 호출

여기 다른 모든 곳에서 보상을 주는 첫 번째 아이디어가 있습니다.

인터럽트(Interrupt)는 핸들러(handler)가 없는 도구입니다. 모델이 이를 "호출"할 때, 에이전트는 아무것도 실행하지 않습니다. 대신 실행을 _일시 중지(pause)_하고, 사용자에게 요청을 노출한 뒤 기다립니다. 사용자가 결과를 제공하면, 실행은 멈췄던 정확한 지점부터 다시 재개됩니다. 도구 호출(Tool calls)이 제어 흐름(control flow)이 되는 것입니다.

이것은 제가 본 것 중 가장 깔끔한 인간 참여형(human-in-the-loop) 프리미티브(primitive)입니다. 돈을 이체하기 전에 반드시 승인을 받아야 하는 뱅킹 에이전트를 예로 들어보겠습니다:

export const userApproval = ai.defineInterrupt({
  name: 'userApproval',
  description: '민감한 작업을 진행하기 전에 사용자에게 승인을 요청합니다.',
...

마법은 응답(response)에 있습니다. 에이전트가 일시 중지되면 res.interrupts에 데이터가 채워지며, 각 인터럽트는 실행을 계속할 수 있도록 respond/restart 빌더(builder)를 제공합니다:

const chat = bankingAgent.chat();
let res = await chat.sendStream('내 저축 계좌로 $500를 이체해줘.').response;

...

"절대 실행되지 않는 도구"가 초능력인 이유

일시 중지는 단순한 데이터(res.interrupts)일 뿐이고, 재개는 또 다른 호출(chat.resumeStream)일 뿐이기 때문에, 이 메커니즘은 인간이 어디에 있는지 상관하지 않습니다. 테스트 환경에서 자동으로 승인하든, CLI에서 프롬프트를 입력하든, 브라우저에서 대화 상자를 렌더링하든 동일하게 작동합니다. 별도로 구성해야 하는 특수한 "인간 참여형 모드(human-in-the-loop mode)"는 없습니다. 이미 이해하고 있는 동일한 요청/응답(request/response) 구조가 중간에 일시 중지된 것뿐입니다.

두 가지 재개(resume) 스타일이 있습니다:

• **respond**는 도구의 출력값을 직접 제공합니다 (도구 본문은 절대 실행되지 않습니다). 승인 절차나 "사용자에게 질문하기"에 완벽합니다.
• **restart**는 원래의 도구 호출을 다시 발행하여 이번에는 실제로 실행되도록 합니다. 이때 { toolApproved: true }와 같은 메타데이터를 선택적으로 태깅할 수 있습니다. "내가 승인한 후에만 이것을 실행하라"는 작업에 완벽합니다.

3. 미들웨어(Middleware): 한 줄로 정의하는 기능(capabilities)

모든 에이전트는 use: [...] 배열을 받습니다. 각 항목은 도구와 동작을 에이전트의 생성 루프(generate loop)에 엮어주는 미들웨어 조각입니다. 이를 통해 여러분이 복잡한 배관 작업(plumbing)을 직접 작성하지 않고도, 단순한 챗봇을 강력한 무언가로 탈바꿈시킬 수 있습니다.

@genkit-ai/middleware 패키지는 filesystem, skills, toolApproval, retry, artifacts, agents와 같은 팩토리(factories)를 제공합니다. 다음은 이들을 거의 전부 사용하여 조립한 풀 기능(full-featured) 코딩 어시스턴트 예시입니다:

import { filesystem, retry, skills, toolApproval } from '@genkit-ai/middleware';

export const codingAgent = ai.defineAgent({
...

use 배열을 위에서 아래로 읽어보면 에이전트의 전체 기능 세트를 파악할 수 있습니다: 도구를 승인하고, 샌드박스화된 파일 시스템(sandboxed filesystem)을 편집하며, 기술(skills)을 로드하고, 실패 시 재시도(retry)할 수 있습니다. 별도의 연결 코드(glue code)는 필요 없습니다. 각 줄이 실제 프로덕션급(production-grade) 기능입니다.

순서가 중요합니다 (주석에 그 이유가 나와 있습니다)

샘플에서 toolApproval은 의도적으로 filesystem 앞에 배치되었습니다. 이는 승인 대기 중 발생하는 인터럽트(interrupt)가 파일 시스템 미들웨어의 에러 핸들링(error handling)에 의해 삼켜지는 대신, 상위로 깔끔하게 전파되도록 하기 위함입니다. 미들웨어는 양파처럼 겹겹이 구성되므로, 순서는 우연이 아니라 실제로 (문서화된) 조절 가능한 요소(knob)입니다.

4. 보상: 조각들이 서로를 강화함

이 섹션은 "부분의 합보다 크다"라는 주장을 구체화하는 부분입니다. 섹션 2와 3에서 다룬 기본 요소(primitives)들이 어떻게 결합되는지 살펴보세요.

승인 게이트(Approval gates)는 곧 인터럽트입니다

코딩 에이전트에 사용된 저 toolApproval 미들웨어는 새로운 승인 시스템을 발명한 것이 아닙니다. 쓰기 작업이 시도될 때, 이는 뱅킹 데모에서 보았던 것과 **정확히 동일한 종류의 인터럽트를 발생(emits)**시킵니다. 따라서 클라이언트 처리 코드는 동일합니다: res.interrupts를 확인한 다음 resumeStream을 호출하면 됩니다. 한 번 배우면 어디에서나 작동합니다.

도구는 ctx.interrupt()를 통해 스스로 일시 중지할 수 있습니다

코딩 에이전트의 run_shell 도구에는 AI 기반의 안전 게이트(safety gate)가 있습니다. 저렴하고 빠른 모델이 각 명령어를 분류하며, 위험한 명령어는 도구 핸들러 내부에서 인터럽트를 트리거합니다:

async (input, ctx) => {
  const isApproved = ctx.metadata?.resumed?.toolApproved === true;

...

방금 일어난 일을 보세요: 모델, 도구, 그리고 인터럽트(interrupt)가 결합되어 스스로를 보호하는 동작을 만들어냈습니다. 안전한 명령은 즉시 실행되고, 위험한 명령은 허가를 요청합니다. 이는 세 가지 기본 요소(primitives)가 결합되어, 그 어느 것도 단독으로는 가질 수 없는 동작을 생성해낸 것입니다.

서브 에이전트(Sub-agents)는 단지 도구로서의 에이전트일 뿐입니다

agents 미들웨어는 하나의 에이전트가 특화된 다른 에이전트들에게 작업을 위임(delegate)할 수 있게 해줍니다. 서브 에이전트를 일반적인 에이전트와 똑같이 정의한 다음, 오케스트레이터(orchestrator)의 use에 나열하기만 하면 됩니다:

export const orchestratorAgent = ai.defineAgent({
  name: 'orchestratorAgent',
  system: '요청을 분석하고 적절한 서브 에이전트에게 위임한 다음, 최종 답변을 합성하세요.',
...

미들웨어는 서브 에이전트당 하나의 위임 도구(delegate_to_researcher, delegate_to_coder)를 주입합니다. 오케스트레이터가 도구를 호출하면, 미들웨어가 해당 서브 에이전트를 실행하고 그 답변을 도구 결과값으로 반환합니다. 또한 서브 에이전트들이 공유 세션에 병합되는 **아티팩트(artifacts)**를 작성하기 때문에, 연구자(researcher)의 조사 결과는 코더(coder)와 오케스트레이터가 사용할 수 있습니다. 다시 강조하지만, 이는 맞춤형 "멀티 에이전트 엔진(multi-agent engine)"이 아니라 구성(composition)의 결과입니다.

5. 동일한 에이전트, 백엔드와 브라우저

이제 마지막 매듭을 짓는 부분입니다. 위에서 설명한 모든 것은 웹 클라이언트에서도 동일하게 작동하는데, 이는 클라이언트가 동일한 프로토콜을 사용하기 때문입니다.

서버: 에이전트를 HTTP 엔드포인트로 노출합니다.

import { expressHandler } from '@genkit-ai/express';

app.post('/api/bankingAgent', expressHandler(bankingAgent));

브라우저: remoteAgent로 연결하면 서버 측에서 사용했던 것과 동일한 chat(), sendStream(), res.interrupts, resumeStream()을 사용할 수 있습니다:

import { remoteAgent, type AgentChat } from 'genkit/beta/client';

const agent = remoteAgent({ url: '/api/bankingAgent' });
...

이 코드 스니펫 하나가 핵심을 보여줍니다. 테스트 흐름을 위해 배웠던 인터럽트/재개(interrupt/resume) 패턴이 실제 운영 환경의 승인 대화창(approval dialog)을 구동하는 바로 그 방식입니다. 새로운 개념은 없습니다. 서버가 세션 스냅샷(session snapshot)을 추적하고, 클라이언트는 그저 "이 답변으로 재개(resume)하세요"라고 말할 뿐입니다.

결론

수많은 프레임워크가 LLM (Large Language Model)을 호출하고 도구 (tool)를 실행할 수 있습니다. Genkit의 에이전트 레이어 (agent layer)를 돋보이게 만드는 것은 그 기능들이 바로 _서로 다른 각도에서 바라본 동일한 몇 가지 아이디어들_이라는 점입니다:

• 인터럽트 (Interrupts)는 인간 참여 (human-in-the-loop)를 가능하게 합니다.
• 미들웨어 (Middleware)는 파일 시스템 (filesystems), 기술 (skills), 재시도 (retries), 그리고 위임 (delegation)을 제공합니다.
• 승인 미들웨어 (approval middleware)는 인터럽트입니다.
• 서브 에이전트 (Sub-agents)는 도구 (tools)입니다.
• 브라우저 클라이언트 (browser client)는 서버 API (server API)입니다.

기본 요소 (primitives)를 한 번 익히면 그 외의 모든 것은 재조합일 뿐입니다. 이것이 바로 코드에서