software

Google의 ADK for TypeScript를 활용한 대규모 에이전트 흐름

발행: (2025년 12월 21일 오전 07:08 GMT+9)
7 min read
원문: Dev.to

Source: Dev.to

Agent Flows At Scale with Google의 ADK for TypeScript 커버 이미지

코드‑우선 혁명

너무 오랫동안 AI 에이전트를 구축하는 것이 추상적인 프롬프트 엔지니어링 연습처럼 느껴졌습니다. Agent Development Kit (ADK) for TypeScript는 개발자가 로직, 도구 및 오케스트레이션을 직접 TypeScript로 정의할 수 있게 함으로써 이 패러다임을 바꿉니다. Google’s December 2025 announcement에서 강조된 바와 같이, 이 접근 방식은 엔지니어가 버전 관리, 자동 테스트, CI/CD 통합과 같은 표준 소프트웨어 개발 모범 사례를 AI 워크플로에 적용할 수 있게 합니다.

이 프레임워크는 엔드‑투‑엔드 타입 안전성을 제공하여, 개발자가 에이전트 백엔드와 애플리케이션 프론트엔드를 일관된 언어로 구축할 수 있게 함으로써 통합 오류를 크게 줄여줍니다. Agents, Instructions, Tools와 같은 모듈형 컴포넌트를 활용함으로써 ADK는 복잡한 AI 행동을 깔끔하고 읽기 쉬우며 확장 가능한 코드로 변환합니다.

사례 연구: “Chef & Sommelier” 다중‑에이전트 시스템

여기에서 작업 중인 프로젝트를 확인할 수 있습니다; Gemini API 키만 추가하면 됩니다.

ADK의 강력함을 보여주기 위해, 실용적인 구현 예시인 계층형 Chef Agent를 살펴보겠습니다. 이 프로젝트는 최신 Gemini 3 모델 gemini-3-pro-preview를 사용하여 단순한 레시피 생성 수준을 넘어서는 요리 경험을 제공합니다.

프로젝트 구조

chef-agent/
├── agent.ts               # The Head Chef
└── sommelier-agent/
    └── agent.ts           # The Wine Expert

계층형 아키텍처

이 애플리케이션의 핵심은 chef-agent/agent.ts에 있습니다. 여기서 루트 에이전트는 Chef(요리사)로 정의되며, 단일 재료 입력을 받아 이름, 설명, 레시피, 그리고 플레이팅 지시까지 포함된 걸작 요리를 생성하도록 지시됩니다.

ADK의 진정한 힘은 하위 에이전트를 다루는 방식에 있습니다. Chef는 혼자 작업하지 않으며, 코드에서는 subAgents 배열을 명시적으로 정의합니다:

import { LlmAgent } from "@google/adk";
import { sommelierAgent } from "./sommelier-agent/agent";

export const rootAgent = new LlmAgent({
  name: "chef_agent",
  model: "gemini-3-pro-preview",
  description:
    "A chef that creates amazing food based on a single ingredient.",
  instruction: `You are a world‑renowned Chef with a passion for creating culinary masterpieces.
Your specialty is taking a SINGLE INGREDIENT provided by the user and designing a complete, delicious, and amazing dish around it.

When you receive an input (which will be an ingredient):
1. **Conceive a Dish**: Create a unique name for a dish highlighting that ingredient.
2. **Description**: Write a mouth‑watering description.
3. **Recipe**: Provide a detailed recipe including:
   * Ingredients list (quantities and items).
   * Step‑by‑step cooking instructions.
4. **Presentation**: Suggest how to plate the dish for maximum visual appeal.

Be enthusiastic, professional, and creative.
You also have a colleague, "sommelier_agent", who must suggest wine pairings for the dish you create.`,
  subAgents: [sommelierAgent],
});

이 설정은 Chef 에이전트가 동료에게 접근할 수 있음을 알려줍니다. Chef가 레시피를 생성하면 자동으로 sommelier-agent/agent.ts에 정의된 sommelier_agent에게 상담할 수 있습니다. 해당 하위 에이전트는 매우 제한된 범위—Chef가 방금 만든 요리의 풍미 프로파일을 기반으로 완벽한 와인 페어링을 제안하는 역할—을 담당합니다.

소믈리에 에이전트 코드

import { LlmAgent } from "@google/adk";

export const instruction = `You are an expert Sommelier.
Your goal is to suggest the perfect wine pairing for a given dish.
When provided with a dish name or description:
1. Suggest a specific type of wine (e.g., Cabernet Sauvignon, Chardonnay).
2. Explain why it pairs well with the dish (flavor profile, acidity, etc.).
3. Recommend a specific region if applicable.`;

export const sommelierAgent = new LlmAgent({
  name: "sommelier_agent",
  model: "gemini-3-pro-preview",
  description: "A sommelier that suggests wine pairings for a given dish.",
  instruction,
});

개발자 경험

이 프로젝트는 @google/adk 라이브러리를 활용하며 원활한 개발자 경험을 제공합니다. package.json을 보면 ADK 개발 도구를 사용하는 내장 스크립트가 있습니다:

  • 터미널 모드: pnpm run run:terminal 은 개발자가 명령줄에서 직접 Chef와 상호작용하여 빠르게 테스트할 수 있게 해줍니다.

ADK Terminal

Chef Agent diagram

  • 웹 인터페이스: pnpm run run:web 은 로컬 서버(localhost:8000)를 실행하여 사용자, Chef, 그리고 숨겨진 Sommelier 서브 에이전트 간의 상호작용을 시각화하는 채팅 인터페이스를 제공합니다.

ADK Web

Chef Agent 프로젝트는 ADK for TypeScript가 왜 게임 체인저인지 완벽히 보여줍니다. 이는 명확한 계약(typed contracts)을 통해 서로 다른 AI 퍼스낼리티(Chef와 Sommelier)가 상호작용하는 구조화된 환경을 만들기 때문입니다.

새로운 Gemini 3 모델의 추론 능력과 TypeScript의 신뢰성을 결합함으로써, Google의 ADK는 다음 세대 소프트웨어의 기반을 제공합니다—코드가 단순히 명령을 실행하는 것이 아니라 사고하고, 창조하고, 협업하게 만드는 환경입니다.

GitHub에서 저를 팔로우하세요. 멋진 프로젝트들을 만들고 있습니다.

읽어 주셔서 감사합니다. 다음에 또 뵙겠습니다 👋

gioboa image

Back to Blog

관련 글

더 보기 »