Genkit 미들웨어 발표: 에이전트 앱 가로채고, 확장하고, 더욱 튼튼하게 만들어요!

2026년 5월 14일

Genkit은 TypeScript, Go, Dart, Python을 지원하며 모든 플랫폼을 위한 풀스택 AI 기반 에이전트 앱을 구축하는 오픈소스 프레임워크예요. 프로덕션 레디(production-ready) 에이전트 앱과 AI 기능을 구축하려면 강력한 모델과 신중한 프롬프트 엔지니어링 그 이상이 필요해요. 최대의 신뢰성을 위해 재시도(retries)와 폴백(fallbacks)이 필요할 수도 있고, 파괴적인 도구 호출 전에 사람의 승인이 필요할 수도 있으며, 모든 레이어에 걸친 관측 가능성(observability)도 필수적이죠.

Genkit은 미들웨어로 이 문제를 해결해요. 미들웨어는 도구 실행 루프를 포함한 생성 호출을 가로채고 사용자 정의 동작을 주입하는 조합 가능한 훅(hook)이에요. 이 미들웨어 시스템은 오늘부터 TypeScript, Go, Dart에서 사용할 수 있으며, Python 지원도 곧 추가될 예정이에요.

Genkit 미들웨어 작동 방식

Genkit의 모든 generate() 호출은 도구 루프를 실행해요. 모델은 출력을 생성하고, 요청된 모든 도구가 실행되며, 그 결과가 새로운 모델 호출에 다시 피드백되고, 모델이 완료될 때까지 이 사이클이 반복되죠. 미들웨어 훅은 이 루프의 세 가지 레이어에 붙어요.

사전 빌드된 미들웨어

Genkit은 일반적인 사용 사례를 위한 여러 사전 빌드된 미들웨어 솔루션을 제공해요. 현재 사용할 수 있는 것들을 살펴볼까요?

1. 재시도 (Retry)

일시적인 오류(RESOURCE_EXHAUSTED, UNAVAILABLE 등)로 인해 실패한 모델 API 호출을 지터(jitter)가 있는 지수 백오프(exponential backoff)를 사용해 자동으로 재시도해요. 모델 호출만 재시도되고, 주변의 도구 루프는 다시 재생되지 않아요.

resp, err := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-flash-latest"),
    ai.WithPrompt("Summarize the quarterly earnings report."),
    ai.WithUse(&middleware.Retry{
        MaxRetries:     3,
        InitialDelayMs: 1000,
        BackoffFactor:  2,
    }),
)

Go

Copied

2. 폴백 (Fallback)

지정된 오류 코드 세트로 인해 기본 모델이 실패할 때 대체 모델로 전환해요. 기본 모델이 할당량을 초과했을 때 완전히 다른 공급자의 모델로 폴백하는 데 유용해요.

resp, err := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-flash-latest"),
    ai.WithPrompt("Analyze this complex document..."),
    ai.WithUse(&middleware.Fallback{
        Models: []ai.ModelRef{
            anthropic.ModelRef("claude-sonnet-4-6", nil), // Claude로 폴백
        },
        Statuses: []core.StatusName{core.RESOURCE_EXHAUSTED},
    }),
)

Go

Copied

3. 도구 승인 (Tool approval)

도구 실행을 허용 목록(allow-list)으로 제한해요. 목록에 없는 도구는 실행 시 인터럽트(interrupt)를 발생시켜, 작업 진행 전에 사람 개입(human-in-the-loop) 확인이 가능하게 해줘요.

resp, _ := genkit.Generate(ctx, g,
    ai.WithPrompt("Delete the temp files"),
    ai.WithTools(deleteFilesTool),
    ai.WithUse(&middleware.ToolApproval{
        AllowedTools: []string{}, // 비어 있으면 모든 도구 호출이 인터럽트 발생
    }),
)

if len(resp.Interrupts()) > 0 {
    interrupt := resp.Interrupts()[0]

    // 사용자에게 승인을 요청한 다음, 승인 플래그로 재개해요.
    approved, _ := deleteFilesTool.RestartWith(interrupt,
        ai.WithResumedMetadata[DeleteInput](map[string]any{"toolApproved": true}),
    )

    resp, err := genkit.Generate(ctx, g,
        ai.WithMessages(resp.History()...),
        ai.WithTools(deleteFilesTool),
        ai.WithToolRestarts(approved),
        ai.WithUse(&middleware.ToolApproval{}),
    )
    fmt.Println(resp.Text())
}

Go

Copied

4. 스킬 (Skills)

디렉토리에서 SKILL.md 파일을 스캔하고 그 내용을 시스템 프롬프트에 주입해요. 또한 use_skill 도구를 노출해서 모델이 필요할 때 특정 스킬을 로드할 수 있게 해줘요.

resp, err := genkit.Generate(ctx, g,
    ai.WithPrompt("How do I deploy this service?"),
    ai.WithUse(&middleware.Skills{SkillPaths: []string{"./skills"}}),
)

Go

Copied

5. 파일 시스템 (Filesystem)

주입된 도구(list_files, read_file, 그리고 쓰기 권한이 활성화되면 write_file 및 edit_file)를 통해 모델에 로컬 파일 시스템에 대한 제한된 접근 권한을 부여해요. 모델이 루트 디렉토리를 벗어날 수 없도록 경로 안전(path safety)이 강제돼요.

resp, err := genkit.Generate(ctx, g,
    ai.WithPrompt("Create a hello world program in the workspace"),
    ai.WithUse(&middleware.Filesystem{
        RootDir:          "./workspace",
        AllowWriteAccess: true,
    }),
)

Go

Copied

커스텀 미들웨어 구축

사전 빌드된 미들웨어는 일반적인 시나리오를 다루지만, 이 시스템의 진정한 힘은 여러분만의 미들웨어를 작성하는 데 있어요. 예를 들어, 에이전트 기반 고객 지원 앱을 구축 중인데 모델이 경쟁사 제품이나 내부 가격 데이터를 절대 언급하지 않도록 하고 싶다고 상상해 보세요. 이런 규칙들을 모든 프롬프트에 인코딩하는 대신, 미들웨어를 사용해 확정적으로(deterministically) 강제할 수 있어요.

커스텀 미들웨어는 모든 언어에서 간단한 계약을 따라요: 이름과 원하는 훅을 반환하는 팩토리 함수를 제공하는 거죠. 팩토리는 generate() 호출당 한 번 호출되며, 필요한 훅만 구현하면 돼요.

다음은 약 20줄의 코드로 작성된 완전한 커스텀 콘텐츠 필터 예시예요.

// ContentFilter는 금지된 용어를 포함하는 모델 응답을 거부해요.
type ContentFilter struct {
    ForbiddenTerms []string `json:"forbiddenTerms"`
}

func (ContentFilter) Name() string { return "app/contentFilter" }

func (f ContentFilter) New(ctx context.Context) (*ai.Hooks, error) {
    return &ai.Hooks{
        WrapModel: func(ctx context.Context, p *ai.ModelParams, next ai.ModelNext) (*ai.ModelResponse, error) {
            resp, err := next(ctx, p)
            if err != nil {
                return nil, err
            }
            text := strings.ToLower(resp.Text())
            for _, term := range f.ForbiddenTerms {
                if strings.Contains(text, strings.ToLower(term)) {
                    return nil, fmt.Errorf("content filter: response contains %q", term)
                }
            }
            return resp, nil
        },
    }, nil
}

Go

Copied

심지어 여러 미들웨어 솔루션들을 조합하고 쌓을 수도 있어요. 미들웨어는 왼쪽에서 오른쪽으로 쌓이는데, 가장 먼저 나열된 것이 가장 바깥쪽 래퍼가 되는 식이에요.

resp, err := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-flash-latest"),
    ai.WithPrompt("What CRM should our customer use?"),
    ai.WithUse(
        &middleware.Retry{MaxRetries: 3},           // 바깥쪽: 내부 스택을 재시도해요.
        &ContentFilter{                              // 안쪽: 모델 출력을 검증해요.
            ForbiddenTerms: []string{"CompetitorCRM", "RivalCo", "internal price"},
        },
    ),
)

Go

Copied

여기서 Retry는 ContentFilter를 감싸고, ContentFilter는 모델 호출을 감싸는 형태예요. 순서가 중요하고, Genkit은 이를 명확하게 보여줘요.

만약 다른 개발자들에게 유용할 만한 미들웨어를 구축했다고 생각한다면, 패키지로 발행해서 다른 사람들도 이점을 누릴 수 있게 할 수 있어요!

개발자 UI 경험

Genkit 개발자 UI를 사용해 미들웨어 실행을 포함한 애플리케이션을 검사하고, 테스트하고, 디버깅할 수 있어요. 미들웨어를 등록하면 개발자 UI에 표시돼요. 여기서 설정을 검사하고, 각 훅 레이어를 통해 실행을 추적하고, 다양한 조합을 테스트할 수 있죠.

시작하기

Genkit 미들웨어가 여러분의 앱에 가져올 기능들에 대해 무척 기대하고 있어요. 여러분의 사용 사례를 해결하기 위해 어떤 커스텀 미들웨어를 구축할지 정말 궁금하네요. 더 자세히 알아보려면 미들웨어 문서를 확인해 보시거나, 이 프레임워크가 처음이라면 Genkit 시작하기를 참조해 주세요.

새로운 사전 빌드 미들웨어에 대한 아이디어가 있다면 이슈를 제출해 주세요. 여러분의 개발 경험을 개선하는 데 무엇이 도움이 될지 듣고 싶어요!

즐거운 코딩 되세요! 🚀

이전

다음