개요

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

⚠️ 비공식 포트 및 실험적 상태: 이 라이브러리는 Google ADK Python 라이브러리의 비공식 TypeScript 포트입니다. 현재 알파 단계이며 API가 변경될 수 있습니다.

ADK TypeScript는 AI 에이전트를 구축하고 배포하기 위한 코드 우선 프레임워크입니다. Gemini에 최적화되었지만 모델에 구애받지 않습니다(model-agnostic). 모듈식이고, 테스트 가능하며, 프로덕션 준비가 된 소프트웨어처럼 에이전트를 구축할 수 있습니다.

코드 우선 개발 (Code-First Development): TypeScript로 에이전트, 툴(tool), 오케스트레이션(orchestration)을 정의합니다. 완벽한 제어력, 테스트 용이성 및 버전 관리가 가능합니다.

풍부한 툴 생태계 (Rich Tool Ecosystem): 미리 구축된 툴, 사용자 지정 함수, OpenAPI 스펙 등을 제공하며 Google 에코시스템과 긴밀하게 통합됩니다.

다중 에이전트 시스템 (Multi-Agent Systems): 전문화된 에이전트를 조합하여 확장 가능한 계층 구조를 만듭니다.

어디서든 배포 (Deploy Anywhere): Cloud Run, Docker 또는 모든 플랫폼에서 배포할 수 있습니다. 사용자가 선택합니다.

개발자 툴링 (Developer Tooling): CLI (npx adk), 웹 UI (npx adk web), 그래프 시각화 및 실행 검사 기능을 제공합니다.

네이티브 스트리밍 (Native Streaming): Runner.runLive와 LiveRequestQueue를 통해 양방향 스트리밍을 지원합니다.

내장 평가 기능 (Built-in Evaluation): npx adk eval을 사용하여 .test.json 데이터셋으로 에이전트를 테스트할 수 있습니다.

프로젝트 로컬에 ADK TypeScript 설치하기:

# 프로젝트 디렉토리로 이동
mkdir my-adk-project
cd my-adk-project
...

설치 후에는 npx를 사용하여 ADK CLI 명령을 사용합니다:

# 새 에이전트 생성
npx adk create my-new-agent
# 에이전트 실행
...

이 접근 방식은 다음을 보장합니다:

모든 의존성이 package.json에 추적됩니다.

프로젝트를 복제하는 누구나 단일 명령으로 모든 것을 설치할 수 있습니다.

프로젝트가 개발 환경과 프로덕션 환경 전반에서 일관되게 작동합니다.

환경 설정에 대한 자세한 내용은 설치 가이드를 참조하세요.

시작을 위한 간단한 날씨 에이전트 예제입니다:

// agent.ts
import { LlmAgent } from 'adk-typescript/agents';
import { ToolContext, FunctionTool } from 'adk-typescript/tools';
...

에이전트 실행하기:

# CLI를 통해 (대화형 채팅)
npx adk run .
# 또는 Node/ts-node으로 직접 실행
...

TypeScript 전용 문서는 **https://njraladdin.github.io/adk-typescript/**에서 확인할 수 있습니다.

문서가 작업 중인 상태(work in progress)이므로 완벽하게 정확하지 않을 수 있다는 점을 유의해 주십시오. 개념적인 정보는 공식 Python ADK 문서를 참조할 수도 있지만, 구현상의 차이가 있을 수 있음을 염두에 두시기 바랍니다.

ADK TypeScript CLI는 에이전트를 관리하고 실행하는 명령어를 제공합니다:

1. 새 에이전트 프로젝트 생성:

필요한 파일들(agent.ts, package.json, tsconfig.json, .env)을 포함하는 스타터 에이전트 템플릿을 생성합니다.

npx adk create <에이전트-이름>
# 예시: npx adk create my_weather_agent

모델과 백엔드를 구성하기 위해 대화형 프롬프트를 따르십시오.

2. 에이전트를 대화형으로 실행하기 (터미널):

에이전트와 상호작용할 수 있는 명령줄 채팅 인터페이스를 시작합니다.

# 에이전트 폴더의 상위 디렉토리로 이동
npx adk run <에이전트_폴더_이름>
# 예시: npx adk run my_weather_agent
...

3. 개발용 웹 UI 실행:

테스트 및 에이전트 동작 검사를 위한 채팅 UI가 포함된 로컬 웹 서버를 시작합니다.

# 에이전트 폴더(들)의 상위 디렉토리로 이동
npx adk web <에이전트_폴더_이름>
# 예시: npx adk web my_weather_agent
...

브라우저에서 UI에 접속하십시오 (일반적으로 http://localhost:3000).

4. API 서버 실행:

에이전트(들)와 프로그래밍 방식으로 상호작용할 수 있는 REST 엔드포인트를 노출하는 로컬 Express.js 서버를 시작합니다. 통합 테스트에 유용합니다.

# 에이전트 폴더(들)의 상위 디렉토리로 이동
npx adk api_server --agent_dir <에이전트_폴더_이름_또는_상위_디렉토리>
# 예시 (하나의 에이전트 제공): npx adk api_server --agent_dir my_weather_agent
...

5. 에이전트 평가:

미리 정의된 데이터셋(*.test.json 파일)을 기반으로 평가를 실행합니다.

npx adk eval <path_to_agent_folder> <path_to_eval_set.test.json>

예시:

npx adk eval ./my_weather_agent ./my_weather_agent/eval_data.test.json

6. 에이전트 그래프 생성 (Generate Agent Graph):

에이전트와 그 도구(tools)/하위 에이전트(sub-agents)의 시각적 표현을 만듭니다 (Graphviz 설치 필요).

npx adk graph <path_to_agent_folder> --output graph.png
# 예시: npx adk graph ./my_weather_agent --output weather_agent_graph.png

7. Cloud Run 배포 (Deploy to Cloud Run):

에이전트를 패키징하고 Google Cloud Run에 배포합니다.

npx adk deploy cloud_run <path_to_agent_folder> --project <your-gcp-project> --region <gcp-region> --service_name <your-service-name>

기여를 환영합니다! 이 프로젝트는 커뮤니티 주도 포트입니다. 버그 보고, 기능 제안, 문서 및 코드는 모두 감사하게 생각합니다. Contributing Guidelines를 참조하세요.

이 프로젝트는 Apache 2.0 License에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참고하십시오.

본 소프트웨어(ADK TypeScript Port)는 현재 **실험적 (alpha)**이며 공식적으로 지원되는 Google 제품이 아닙니다. 이는 서비스별 약관의 일반 서비스 약관 섹션에 명시된