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

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

GitHub logo xbill9 / adk-hello-world-typescript

TypeScript를 위한 ADK Hello World

Google의 Agent Development Kit for TypeScript로 구축된 최소 기능의 날씨 및 시간 에이전트입니다.

요구 사항

• Node.js 20 이상
• Gemini API 키 또는 Vertex AI를 위한 Google Cloud 자격 증명

설정

npm install
cp .env.example .env

.env 파일을 편집하고 한 가지 인증 방법을 선택하세요:

• Gemini Developer API: GOOGLE_API_KEY 설정
• Vertex AI: GOOGLE_GENAI_USE_VERTEXAI=TRUE, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION을 설정한 후 gcloud auth application-default login 실행

.env 파일은 절대 커밋하지 마세요.

실행

대화형 터미널 (Interactive terminal)

npm start

ADK 개발 UI (ADK development UI)

npm run web

타입 체크 및 단위 테스트 실행 (Type-check and run unit tests)

npm run check

ADK CLI를 직접 호출할 수도 있습니다:

npx adk run src/agent.ts
npx adk web

에이전트 소스는 src/agent.ts에 있습니다. 두 개의 로컬 도구(local tools)는 원래 샘플 동작을 유지합니다: 뉴욕(New York)의 날씨와 현지 시간을 사용할 수 있으며, 다른 도시들은 명확한 지원되지 않는 도시(unsupported-city) 결과를 반환합니다.

GitHub에서 보기

TypeScript란 무엇인가요?

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

Node.js 설치

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

GitHub logo nvm-sh / nvm

Node Version Manager - 여러 개의 활성 Node.js 버전을 관리하기 위한 POSIX 준수 bash 스크립트

Node Version Manager

Tests

nvm version

CII Best Practices

목차 (Table of Contents)

• 소개 (Intro)

• 정보 (About)

• 설치 및 업데이트 (Installing and Updating)

  • 설치 및 업데이트 스크립트 (Install & Update Script)
    • 추가 참고 사항 (Additional Notes)
    • Docker에서 설치하기 (Installing in Docker)
      • CI/CD 작업을 위한 Docker 설치 (Installing in Docker for CICD-Jobs)
    • Linux에서의 문제 해결 (Troubleshooting on Linux)
    • macOS에서의 문제 해결 (Troubleshooting on macOS)
    • Ansible
  • 설치 확인 (Verify Installation)
  • 중요 참고 사항 (Important Notes)
  • Git 설치 (Git Install)
  • 수동 설치 (Manual Install)
  • 수동 업그레이드 (Manual Upgrade)

• 사용법 (Usage)

  • 장기 지원 (Long-term Support)

• 설치 중 글로벌 패키지 마이그레이션 (Migrating Global Packages While Installing)

  • 설치된 버전 간의 글로벌 패키지 마이그레이션 (Migrating Global Packages Between Installed Versions)
  • 오프라인 설치 (Offline Install)
  • 설치 시 파일로부터 기본 글로벌 패키지 가져오기 (Default Global Packages From File While Installing)
  • io.js
  • 시스템 Node 버전 (System Version of Node)
  • 버전 목록 표시 (Listing Versions)
  • 사용자 정의 색상 설정 (Setting Custom Colors)
    • 사용자 정의 색상 유지 (Persisting custom colors)
    • 색상이 적용된 출력 억제 (Suppressing colorized output)
  • PATH 복구 (Restoring PATH)
  • 기본 Node 버전 설정 (Set default node version)
  • Node 바이너리 미러 사용 (Use a mirror of node binaries)
    • 미러에 인증 헤더 전달 (Pass Authorization header to mirror)
  • .nvmrc
  • 심층적인 셸 통합 (Deeper Shell Integration)
    • .nvmrc 파일이 있는 디렉토리에서 nvm use 자동 호출 (Calling nvm use automatically in a directory with a .nvmrc file)
      • bash
      • zsh
      • fish

• 테스트 실행 (Running Tests)

• 환경 변수 (Environment variables)

• Bash 완성 기능 (Bash Completion)

  • 사용법 (Usage)

• 호환성 문제 (Compatibility Issues)

• Alpine Linux에 nvm 설치하기 (Installing nvm on Alpine Linux)

  • Alpine Linux 3.13+
  • Alpine Linux 3.5 - 3.12

• 제거 / 삭제 (Uninstalling / Removal)

  • 수동 제거 (Manual Uninstall)

• 개발 환경을 위한 Docker (Docker For Development Environment)

• 문제점 (Problems)

• macOS 문제 해결 (macOS Troubleshooting)

• …

GitHub에서 보기

현재 Node.js 릴리스를 설치하고 활성화합니다:

nvm install --lts
nvm use --lts

버전 명령어로 설치를 검증할 수 있습니다:

node --version
# v22.x

에이전트 개발 키트(Agent Development Kit)란 무엇인가?

Agent Development Kit (ADK)는 AI 에이전트를 개발하고 배포하기 위한 유연하고 모듈식 프레임워크입니다. ADK는 Gemini 및 Google 생태계에 최적화되어 있지만, 모델에 구애받지 않고(model-agnostic), 배포 환경에 구애받지 않으며(deployment-agnostic), 다른 프레임워크와의 호환성을 위해 구축되었습니다.

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

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

Agent Development Kit (ADK)를 사용하여 강력한 다중 에이전트 시스템을 구축하세요.

Google은 ADK 프로젝트의 전체 TypeScript 버전을 위한 소스를 제공합니다:

GitHub logo google / adk-js

유연성과 제어력을 갖춘 정교한 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈 소스 기반의 코드 우선 (code-first) TypeScript 툴킷입니다.

TypeScript용 Agent Development Kit (ADK)

NPM Version

r/agentdevelopmentkit

유연성과 제어력을 갖춘 정교한 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈 소스 기반의 코드 우선 (code-first) TypeScript 툴킷입니다.

주요 링크: Docs, Samples 및 ADK Web.

Agent Development Kit (ADK)는 단순한 작업부터 복잡한 멀티 에이전트 시스템 (multi-agent systems)에 이르기까지, AI 에이전트 워크플로 (workflows)를 구축, 배포 및 오케스트레이션 (orchestrating)하기 위한 유연하고 모듈식인 프레임워크입니다. 에이전트의 동작, 오케스트레이션 및 도구 사용 (tool use)을 코드에서 직접 정의하여 강력한 디버깅 (debugging), 버전 관리 (versioning) 및 어디에서나 배포가 가능하도록 합니다.

ADK의 TypeScript 버전은 Node.js 및 브라우저 생태계를 위해 구축되었으며, 완전한 타입 안전성 (type safety), Zod 스키마 검증 (schema validation), 그리고 ESM, CommonJS 및 웹 런타임 (web runtimes)을 지원합니다.

✨ 주요 특징

• 코드 우선 TypeScript (Code-First TypeScript): 완전한 타입 안전성을 바탕으로 에이전트 로직, 도구 및 오케스트레이션을 정의합니다. 도구 파라미터 (tool parameters)는 컴파일 타임 타입 추론 (compile-time type inference)과 함께 Zod v3 및 v4 스키마를 지원합니다.

• 브라우저 및 서버: ESM, CommonJS 및 웹 번들 (web bundles)을 제공합니다. Node.js 또는 브라우저에서 직접 에이전트를 실행할 수 있습니다.

• 풍부한…

GitHub에서 보기

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

Gemini API 키

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

https://aistudio.google.com/apikey