Google Gen AI SDK for TypeScript 2.21

Apply the Node.js 24 and TypeScript 7 prompts first. These rules cover @google/genai 2.21 client construction, backend selection, prompt assembly, tools and function calling, safety controls, grounding and retrieval, files, caches, batches, live sessions, and ephemeral tokens. The package requires Node.js 20 or later; pin <3.0.0 if you cannot move to Node.js 22 when the 3.0 line ships.

Client construction and backend selection

• Create GoogleGenAI once on the server from deployment configuration, and never let request data choose between the Gemini Developer API and the Gemini Enterprise Agent Platform (Vertex) backend.
• Prefer the enterprise: true flag with fixed project and location over the older vertexai alias, and never set both to conflicting values — the constructor throws when they disagree.
• Authenticate enterprise clients with googleAuthOptions or workload identity rather than an embedded key, and give the service account only the model, file, and cache permissions the workload actually calls.
• Treat apiKey as a server-only secret. The web build accepts one, but a key in browser or mobile code is extractable; front the SDK with your own authenticated endpoint instead.
• Pin httpOptions.apiVersion to the version whose behavior you tested. The client otherwise defaults to v1beta on the Gemini API and v1beta1 on the enterprise backend, so a default upgrade can change validation and field handling under you.
• Keep httpOptions.baseUrl, baseUrlResourceScope, and headers in configuration. A base URL derived from user input sends