googleapis/js-genai

Google Gen AI SDK for TypeScript & JavaScript

소개 – Google이 공식 관리하는 npm 패키지(@google/genai)로, Gemini 2.0+ API(퍼블릭 Gemini Developer API 및 Gemini Enterprise Agent Platform)를 래핑합니다. JavaScript/TypeScript 코드에 대해 다음과 같은 기능을 위한 가볍고 관용적인 레이어를 제공합니다:

텍스트, 이미지, 오디오, 비디오 생성
스트리밍 응답
함수(도구) 호출 / 자동 함수 호출
상태 유지 채팅 세션
파일 업로드, 라이브 세션 처리 및 최신 Interactions 통합 API

대상 사용자 – 원시 HTTP 요청을 작성하지 않고 Node.js나 브라우저에서 Gemini 모델을 호출하려는 프론트엔드 또는 백엔드 개발자.

주요 개념

개념	기능
`GoogleGenAI` 클래	진입점; 인증 설정(API 키 또는 엔터프라이즈 자격 증명)을 보유하고 하위 모듈(`models`, `chats`, `caches`, `files`, `live`, `interactions`)을 생성합니다.
`ai.models.generateContent`	텍스트(또는 멀티모달) 생성을 위한 단일 요청.
`generateContentStream`	모델이 스트리밍 출력할 때 부분 청크를 생성하는 비동기 반복자.
`ai.chats`	대화 기록을 유지하고 다중 턴 상호작용을 단순화하는 로컬 `Chat` 객체를 생성합니다.
`ai.caches`	서버 측 프롬프트 캐시를 관리하여 반복되는 긴 접두사의 토큰 비용을 절감합니다.
`ai.files`	대용량 파일(이미지, 오디오, PDF 등)을 업로드하고 프롬프트에서 참조합니다.
`ai.live`	라이브 오디오/비디오를 수락하고 라이브 출력을 반환할 수 있는 실시간 세션을 시작합니다.
`ai.interactions`	모델 호출, 채팅 상태, 도구 오케스트레이션 및 장기 실행 작업(예: 딥 리서치 에이전트)을 통합하는 상위 수준 API.
함수 호출 / 도구	JSON-schema 함수를 선언하고 Gemini가 호출하게 한 다음 결과를 피드백합니다.
자동 연속	SDK는 비활성화하지 않는 한 자동으로 연속 토큰을 따릅니다.

설치

npm install @google/genai

빠른 시작 (API-key)

import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const resp = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: 'Why is the sky blue?'
});
console.log(resp.text);

동일한 생성자가 브라우저에서도 작동하지만, README는 키를 서버 측에 보관해야 한다고 경고합니다.

Enterprise-Agent 초기화

const ai = new GoogleGenAI({
  enterprise: true,
  project: 'my-project',
  location: 'us-central1'
});

환경 변수(GOOGLE_GENAI_USE_ENTERPRISE, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)도 사용할 수 있습니다.

스트리밍 예제

for await (const chunk of ai.models.generateContentStream({
  model: 'gemini-flash-latest',
  contents: 'Write a 100-word poem.'
})) {
  console.log(chunk.text);
}

함수 호출 (도구) 예제

const controlLight: FunctionDeclaration = {
  name: 'controlLight',
  parametersJsonSchema: {
    type: 'object',
    properties: {
      brightness: {type: 'number'},
      colorTemperature: {type: 'string'}
    },
    required: ['brightness', 'colorTemperature']
  }
};

const resp = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: 'Dim the lights so the room feels cozy.',
  config: {
    toolConfig: {functionCallingConfig: {mode: FunctionCallingConfigMode.ANY, allowedFunctionNames: ['controlLight']}},
    tools: [{functionDeclarations: [controlLight]}]
  }
});
console.log(resp.functionCalls);

SDK는 functionCalls 배열을 반환하며, 이를 실행하고 후속 요청(또는 ai.chats를 통해)을 통해 피드백할 수 있습니다.

Interactions API (상태 유지, 에이전트 스타일)

// 첫 번째 턴
const i1 = await ai.interactions.create({model: 'gemini-flash-latest', input: 'Hi, I am Amir.'});
// 두 번째 턴 – 대화 컨텍스트 유지
const i2 = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: 'What is my name?',
  previous_interaction_id: i1.id
});

딥 리서치 에이전트, 멀티모달 입력, 내장 도구(Google 검색, 코드 실행) 및 사용자 지정 함수 도구를 지원합니다.

오류 처리 – 모든 API 오류는 name, message 및 HTTP status 필드가 있는 ApiError로 나타납니다.

버전 및 호환성 참고 사항

현재 SDK는 Node 20+에서 작동합니다. 3.0.0 버전부터는 Node 22+가 필요합니다. 이전 런타임이 필요한 경우 <3.0.0으로 고정하세요.
다음 메이저 릴리스에서는 자동 함수 호출이 Models.generateContent에서 Chats 모듈로 이동됩니다.
일부 필드는 더 이상 사용되지 않습니다(LiveConnectConfig.generation_config, generate_videos 내의 prompt/text/image 등).

더 알아보기

전체 문서: https://googleapis.github.io/js-genai/
샘플 프로젝트: https://github.com/googleapis/js-genai/tree/main/sdk-samples
코드 생성 가이드: 저장소의 codegen_instructions.md.

결론 – 이 저장소는 JavaScript/TypeScript 개발자가 Google의 Gemini 모델(엔터프라이즈 에이전트 포함)을 앱에 통합할 수 있도록 하는 본격적인 프로덕션급 SDK입니다. 스트리밍, 채팅 상태, 도구 호출 및 멀티모달 데이터를 지원합니다.

googleapis/js-genai

Google Gen AI SDK for TypeScript & JavaScript

관련