이 튜토리얼은 TypeScript와 Agent Development Kit (ADK)의 네이티브 TypeScript 버전을 사용하여 시작 단계인 "Hello World" 스타일의 에이전트를 구축합니다.

전체 샘플 프로젝트는 GitHub에서 확인할 수 있습니다:

xbill9 (xbill) · GitHub

12032025/16785778. xbill9은 209개의 리포지토리(repositories)를 보유하고 있습니다. GitHub에서 이들의 코드를 팔로우하세요.

favicon github.com

TypeScript란 무엇인가?
TypeScript는 Microsoft에서 유지 관리하는 JavaScript 기반의 강력한 타입 시스템을 갖춘 프로그래밍 언어입니다. 이는 일반 JavaScript로 컴파일되며 Node.js를 포함하여 JavaScript가 실행되는 모든 곳에서 실행됩니다. TypeScript용 ADK는 바로 Node.js를 대상으로 합니다. 정적 타입 시스템(static type system)은 에이전트 개발과 자연스럽게 결합됩니다. 도구 파라미터(tool parameters), 도구 결과(tool results), 그리고 에이전트 설정(agent configuration)은 모델이 이를 확인하기 전, 컴파일 타임(compile time)에 모두 검사됩니다.

Node.js 설치하기
TypeScript용 ADK를 사용하려면 Node.js 20 이상의 버전이 필요합니다. 환경에 Node.js가 설치되어 있지 않다면, Node Version Manager (nvm)가 버전을 설치하고 관리하는 가장 쉬운 방법입니다:

nvm.sh · GitHub

nvm - node version manager. nvm.sh는 4개의 리포지토리를 보유하고 있습니다. GitHub에서 이들의 코드를 팔로우하세요.

favicon github.com

현재 Node.js 릴리스를 설치하고 활성화하세요:

version 명령어를 통해 설치를 확인할 수 있습니다:

**
Agent Development Kit (ADK)란 무엇인가요?
Agent Development Kit (ADK)는 AI 에이전트를 개발하고 배포하기 위한 유연하고 모듈화된 프레임워크 (framework)입니다. Gemini 및 Google 생태계에 최적화되어 있지만, ADK는 모델 불가지론적 (model-agnostic)이며, 배포 불가지론적 (deployment-agnostic)이고, 다른 프레임워크와의 호환성을 위해 구축되었습니다.

Google은 여기서 ADK에 대한 전체 문서를 제공합니다:

Agent Development Kit (ADK) - Agent Development Kit (ADK)Agent Development Kit (ADK)

Agent Development Kit (ADK)로 강력한 멀티 에이전트 시스템 (multi-agent systems)을 구축하세요

favicon adk.dev

Google은 ADK 프로젝트의 완전한 TypeScript 버전 소스 코드를 제공합니다:

Google · GitHub

Google ❤️ Open Source. Google은 2888개의 저장소 (repositories)를 제공합니다. GitHub에서 그들의 코드를 팔로우하세요.

favicon github.com

ADK는 npm에 @google/adk로 게시되어 있으며, 개발 도구는 @google/adk-devtools에 포함되어 있습니다. 이 튜토리얼에서는 ADK 1.4.0 버전을 사용합니다.

Gemini API Key
애플리케이션 기본 인증 정보 (Application Default Credentials (ADC))를 사용하지 않는 경우, Gemini API 키가 필요합니다. Google AI Studio에서 Gemini 키를 받을 수 있습니다:

accounts.google.com

개발 환경 확인
Node.js가 설치되면, 샘플 저장소(repo)를 클론(clone)하고 init.sh 스크립트를 실행하세요. 이 스크립트는 npm 의존성(dependencies)을 설치하고 시작용 .env 파일을 생성합니다:

출력 결과:

.env 파일을 편집하고 하나의 인증 방식을 선택하세요:
Gemini Developer API: GOOGLE_API_KEY를 설정합니다.
Vertex AI: GOOGLE_GENAI_USE_VERTEXAI=TRUE, GOOGLE_CLOUD_PROJECT, 그리고 GOOGLE_CLOUD_LOCATION을 설정한 다음, ADC(Application Default Credentials)로 인증합니다:

참고: .env 파일은 절대 커밋(commit)하지 마세요. 이미 .gitignore에 등록되어 있습니다.
API 권한 오류 디버깅
애플리케이션 기본 인증 정보(Application Default Credentials)가 만료되거나 Google Cloud 인증이 만료된 경우, 다음 명령어로 다시 인증하세요:

또 다른 흔한 문제는 환경 변수(environment variables) 누락입니다. 에이전트는 dotenv를 통해 .env를 자동으로 로드하며, 동일한 값이 필요한 셸(shell) 명령어를 위해 set_env.sh 스크립트가 제공됩니다:

TypeScript ADK 에이전트
전체 에이전트는 src/agent.ts라는 단일 파일에 존재합니다. 이 파일은 두 개의 로컬 도구(날씨 및 현재 시간)를 정의하고, 이를 Gemini 2.5 Flash에서 실행되는 LlmAgent에 연결합니다.

도구 파라미터(Tool parameters)는 Zod 스키마로 선언되므로, ADK는 타입(types)으로부터 함수 호출(function-calling) 선언을 직접 도출합니다:

도구들은 판별 가능한 유니온(discriminated union) — 보고서가 포함된 성공 결과 또는 메시지가 포함된 에러 결과 — 를 반환하며, 이는 모델이 추론할 수 있는 일관된 형태를 제공합니다:

날씨와 현지 시간은 뉴욕(New York)에 대해 사용할 수 있으며, 다른 도시의 경우 명확한 지원되지 않는 도시(unsupported-city) 결과를 반환합니다.

타입 체크(Type-Checking) 및 단위 테스트(Unit Tests)

이 샘플의 이전 Go 및 Python 버전과 달리, TypeScript 프로젝트는 Node.js 네이티브 테스트 러너(test runner)로 구축된 단위 테스트 스위트(unit test suite)를 포함하여 제공됩니다. 단일 명령으로 프로젝트의 타입을 체크하고 테스트를 실행할 수 있습니다:

테스트 출력 예시:

도구(tools)들이 일반적인 export 함수들이기 때문에, 모델을 전혀 호출하지 않고도 결정론적(deterministically)으로 테스트할 수 있습니다.

CLI에서 ADK 실행하기
에이전트는 터미널에서 로컬로 디버깅할 수 있습니다. cli.sh를 사용하거나 npm 스크립트를 직접 실행하세요: