1  ---
  2  title: "Google GenAI"
  3  id: integrations-google-genai
  4  description: "Google GenAI integration for Haystack"
  5  slug: "/integrations-google-genai"
  6  ---
  7  
  8  
  9  ## haystack_integrations.components.embedders.google_genai.document_embedder
 10  
 11  ### GoogleGenAIDocumentEmbedder
 12  
 13  Computes document embeddings using Google AI models.
 14  
 15  ### Authentication examples
 16  
 17  **1. Gemini Developer API (API Key Authentication)**
 18  
 19  ````python
 20  from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
 21  
 22  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
 23  document_embedder = GoogleGenAIDocumentEmbedder(model="gemini-embedding-001")
 24  
 25  **2. Vertex AI (Application Default Credentials)**
 26  ```python
 27  from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
 28  
 29  # Using Application Default Credentials (requires gcloud auth setup)
 30  document_embedder = GoogleGenAIDocumentEmbedder(
 31      api="vertex",
 32      vertex_ai_project="my-project",
 33      vertex_ai_location="us-central1",
 34      model="gemini-embedding-001"
 35  )
 36  ````
 37  
 38  **3. Vertex AI (API Key Authentication)**
 39  
 40  ```python
 41  from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
 42  
 43  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
 44  document_embedder = GoogleGenAIDocumentEmbedder(
 45      api="vertex",
 46      model="gemini-embedding-001"
 47  )
 48  ```
 49  
 50  ### Usage example
 51  
 52  ```python
 53  from haystack import Document
 54  from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
 55  
 56  doc = Document(content="I love pizza!")
 57  
 58  document_embedder = GoogleGenAIDocumentEmbedder()
 59  
 60  result = document_embedder.run([doc])
 61  print(result['documents'][0].embedding)
 62  
 63  # [0.017020374536514282, -0.023255806416273117, ...]
 64  ```
 65  
 66  #### __init__
 67  
 68  ```python
 69  __init__(
 70      *,
 71      api_key: Secret = Secret.from_env_var(
 72          ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
 73      ),
 74      api: Literal["gemini", "vertex"] = "gemini",
 75      vertex_ai_project: str | None = None,
 76      vertex_ai_location: str | None = None,
 77      model: str = "gemini-embedding-001",
 78      prefix: str = "",
 79      suffix: str = "",
 80      batch_size: int = 32,
 81      progress_bar: bool = True,
 82      meta_fields_to_embed: list[str] | None = None,
 83      embedding_separator: str = "\n",
 84      config: dict[str, Any] | None = None
 85  ) -> None
 86  ```
 87  
 88  Creates an GoogleGenAIDocumentEmbedder component.
 89  
 90  **Parameters:**
 91  
 92  - **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
 93    Not needed if using Vertex AI with Application Default Credentials.
 94    Go to https://aistudio.google.com/app/apikey for a Gemini API key.
 95    Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
 96  - **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
 97  - **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
 98    Application Default Credentials.
 99  - **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
100    Required when using Vertex AI with Application Default Credentials.
101  - **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
102    The default model is `gemini-embedding-001`.
103  - **prefix** (<code>str</code>) – A string to add at the beginning of each text.
104  - **suffix** (<code>str</code>) – A string to add at the end of each text.
105  - **batch_size** (<code>int</code>) – Number of documents to embed at once.
106  - **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
107  - **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed along with the document text.
108  - **embedding_separator** (<code>str</code>) – Separator used to concatenate the metadata fields to the document text.
109  - **config** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`.
110    If not specified, it defaults to `{"task_type": "SEMANTIC_SIMILARITY"}`.
111    For more information, see the [Google AI Task types](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
112  
113  #### to_dict
114  
115  ```python
116  to_dict() -> dict[str, Any]
117  ```
118  
119  Serializes the component to a dictionary.
120  
121  **Returns:**
122  
123  - <code>dict\[str, Any\]</code> – Dictionary with serialized data.
124  
125  #### from_dict
126  
127  ```python
128  from_dict(data: dict[str, Any]) -> GoogleGenAIDocumentEmbedder
129  ```
130  
131  Deserializes the component from a dictionary.
132  
133  **Parameters:**
134  
135  - **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
136  
137  **Returns:**
138  
139  - <code>GoogleGenAIDocumentEmbedder</code> – Deserialized component.
140  
141  #### run
142  
143  ```python
144  run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
145  ```
146  
147  Embeds a list of documents.
148  
149  **Parameters:**
150  
151  - **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
152  
153  **Returns:**
154  
155  - <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
156  - `documents`: A list of documents with embeddings.
157  - `meta`: Information about the usage of the model.
158  
159  #### run_async
160  
161  ```python
162  run_async(
163      documents: list[Document],
164  ) -> dict[str, list[Document]] | dict[str, Any]
165  ```
166  
167  Embeds a list of documents asynchronously.
168  
169  **Parameters:**
170  
171  - **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
172  
173  **Returns:**
174  
175  - <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
176  - `documents`: A list of documents with embeddings.
177  - `meta`: Information about the usage of the model.
178  
179  ## haystack_integrations.components.embedders.google_genai.multimodal_document_embedder
180  
181  ### GoogleGenAIMultimodalDocumentEmbedder
182  
183  Computes non-textual document embeddings using Google AI models.
184  
185  It supports images, PDFs, video and audio files. They are mapped to vectors in a single vector space.
186  
187  To embed textual documents, use the GoogleGenAIDocumentEmbedder.
188  To embed a string, like a user query, use the GoogleGenAITextEmbedder.
189  
190  ### Authentication examples
191  
192  **1. Gemini Developer API (API Key Authentication)**
193  
194  ````python
195  from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
196  
197  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
198  document_embedder = GoogleGenAIMultimodalDocumentEmbedder(model="gemini-embedding-2-preview")
199  
200  **2. Vertex AI (Application Default Credentials)**
201  ```python
202  from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
203  
204  # Using Application Default Credentials (requires gcloud auth setup)
205  document_embedder = GoogleGenAIMultimodalDocumentEmbedder(
206      api="vertex",
207      vertex_ai_project="my-project",
208      vertex_ai_location="us-central1",
209      model="gemini-embedding-2-preview"
210  )
211  ````
212  
213  **3. Vertex AI (API Key Authentication)**
214  
215  ```python
216  from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
217  
218  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
219  document_embedder = GoogleGenAIMultimodalDocumentEmbedder(
220      api="vertex",
221      model="gemini-embedding-2-preview"
222  )
223  ```
224  
225  ### Usage example
226  
227  ```python
228  from haystack import Document
229  from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
230  
231  doc = Document(content=None, meta={"file_path": "path/to/image.jpg"})
232  
233  document_embedder = GoogleGenAIMultimodalDocumentEmbedder()
234  
235  result = document_embedder.run([doc])
236  print(result['documents'][0].embedding)
237  
238  # [0.017020374536514282, -0.023255806416273117, ...]
239  ```
240  
241  #### __init__
242  
243  ```python
244  __init__(
245      *,
246      api_key: Secret = Secret.from_env_var(
247          ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
248      ),
249      api: Literal["gemini", "vertex"] = "gemini",
250      vertex_ai_project: str | None = None,
251      vertex_ai_location: str | None = None,
252      file_path_meta_field: str = "file_path",
253      root_path: str | None = None,
254      image_size: tuple[int, int] | None = None,
255      model: str = "gemini-embedding-2-preview",
256      batch_size: int = 6,
257      progress_bar: bool = True,
258      config: dict[str, Any] | None = None
259  ) -> None
260  ```
261  
262  Creates an GoogleGenAIMultimodalDocumentEmbedder component.
263  
264  **Parameters:**
265  
266  - **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
267    Not needed if using Vertex AI with Application Default Credentials.
268    Go to https://aistudio.google.com/app/apikey for a Gemini API key.
269    Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
270  - **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
271  - **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
272    Application Default Credentials.
273  - **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
274    Required when using Vertex AI with Application Default Credentials.
275  - **file_path_meta_field** (<code>str</code>) – The metadata field in the Document that contains the file path to the file to embed.
276  - **root_path** (<code>str | None</code>) – The root directory path where document files are located. If provided, file paths in
277    document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
278  - **image_size** (<code>tuple\[int, int\] | None</code>) – Only used for images and PDF pages. If provided, resizes the image to fit within the specified dimensions
279    (width, height) while maintaining aspect ratio. This reduces file size, memory usage, and processing time,
280    which is beneficial when working with models that have resolution constraints or when transmitting images
281    to remote services.
282  - **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
283  - **batch_size** (<code>int</code>) – Number of documents to embed at once. Maximum batch size varies depending on the input type.
284    See [Google AI documentation](https://ai.google.dev/gemini-api/docs/embeddings#supported-modalities) for
285    more information.
286  - **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
287  - **config** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`.
288    You can for example set the output dimensionality of the embedding: `{"output_dimensionality": 768}`.
289    It also allows customizing the task type. If the task type is not specified, it defaults to
290    `{"task_type": "RETRIEVAL_DOCUMENT"}`.
291    For more information, see the [Google AI documentation](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
292  
293  #### run
294  
295  ```python
296  run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
297  ```
298  
299  Embeds a list of documents.
300  
301  **Parameters:**
302  
303  - **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
304  
305  **Returns:**
306  
307  - <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
308  - `documents`: A list of documents with embeddings.
309  - `meta`: Information about the usage of the model.
310  
311  #### run_async
312  
313  ```python
314  run_async(
315      documents: list[Document],
316  ) -> dict[str, list[Document]] | dict[str, Any]
317  ```
318  
319  Embeds a list of documents asynchronously.
320  
321  **Parameters:**
322  
323  - **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
324  
325  **Returns:**
326  
327  - <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
328  - `documents`: A list of documents with embeddings.
329  - `meta`: Information about the usage of the model.
330  
331  ## haystack_integrations.components.embedders.google_genai.text_embedder
332  
333  ### GoogleGenAITextEmbedder
334  
335  Embeds strings using Google AI models.
336  
337  You can use it to embed user query and send it to an embedding Retriever.
338  
339  ### Authentication examples
340  
341  **1. Gemini Developer API (API Key Authentication)**
342  
343  ````python
344  from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
345  
346  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
347  text_embedder = GoogleGenAITextEmbedder(model="gemini-embedding-001")
348  
349  **2. Vertex AI (Application Default Credentials)**
350  ```python
351  from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
352  
353  # Using Application Default Credentials (requires gcloud auth setup)
354  text_embedder = GoogleGenAITextEmbedder(
355      api="vertex",
356      vertex_ai_project="my-project",
357      vertex_ai_location="us-central1",
358      model="gemini-embedding-001"
359  )
360  ````
361  
362  **3. Vertex AI (API Key Authentication)**
363  
364  ```python
365  from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
366  
367  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
368  text_embedder = GoogleGenAITextEmbedder(
369      api="vertex",
370      model="gemini-embedding-001"
371  )
372  ```
373  
374  ### Usage example
375  
376  ```python
377  from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
378  
379  text_to_embed = "I love pizza!"
380  
381  text_embedder = GoogleGenAITextEmbedder()
382  
383  print(text_embedder.run(text_to_embed))
384  
385  # {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
386  # 'meta': {'model': 'gemini-embedding-001-v2',
387  #          'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
388  ```
389  
390  #### __init__
391  
392  ```python
393  __init__(
394      *,
395      api_key: Secret = Secret.from_env_var(
396          ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
397      ),
398      api: Literal["gemini", "vertex"] = "gemini",
399      vertex_ai_project: str | None = None,
400      vertex_ai_location: str | None = None,
401      model: str = "gemini-embedding-001",
402      prefix: str = "",
403      suffix: str = "",
404      config: dict[str, Any] | None = None
405  ) -> None
406  ```
407  
408  Creates an GoogleGenAITextEmbedder component.
409  
410  **Parameters:**
411  
412  - **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
413    Not needed if using Vertex AI with Application Default Credentials.
414    Go to https://aistudio.google.com/app/apikey for a Gemini API key.
415    Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
416  - **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
417  - **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
418    Application Default Credentials.
419  - **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
420    Required when using Vertex AI with Application Default Credentials.
421  - **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
422    The default model is `gemini-embedding-001`.
423  - **prefix** (<code>str</code>) – A string to add at the beginning of each text to embed.
424  - **suffix** (<code>str</code>) – A string to add at the end of each text to embed.
425  - **config** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`.
426    If not specified, it defaults to `{"task_type": "SEMANTIC_SIMILARITY"}`.
427    For more information, see the [Google AI Task types](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
428  
429  #### to_dict
430  
431  ```python
432  to_dict() -> dict[str, Any]
433  ```
434  
435  Serializes the component to a dictionary.
436  
437  **Returns:**
438  
439  - <code>dict\[str, Any\]</code> – Dictionary with serialized data.
440  
441  #### from_dict
442  
443  ```python
444  from_dict(data: dict[str, Any]) -> GoogleGenAITextEmbedder
445  ```
446  
447  Deserializes the component from a dictionary.
448  
449  **Parameters:**
450  
451  - **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
452  
453  **Returns:**
454  
455  - <code>GoogleGenAITextEmbedder</code> – Deserialized component.
456  
457  #### run
458  
459  ```python
460  run(text: str) -> dict[str, list[float]] | dict[str, Any]
461  ```
462  
463  Embeds a single string.
464  
465  **Parameters:**
466  
467  - **text** (<code>str</code>) – Text to embed.
468  
469  **Returns:**
470  
471  - <code>dict\[str, list\[float\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
472  - `embedding`: The embedding of the input text.
473  - `meta`: Information about the usage of the model.
474  
475  #### run_async
476  
477  ```python
478  run_async(text: str) -> dict[str, list[float]] | dict[str, Any]
479  ```
480  
481  Asynchronously embed a single string.
482  
483  This is the asynchronous version of the `run` method. It has the same parameters and return values
484  but can be used with `await` in async code.
485  
486  **Parameters:**
487  
488  - **text** (<code>str</code>) – Text to embed.
489  
490  **Returns:**
491  
492  - <code>dict\[str, list\[float\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
493  - `embedding`: The embedding of the input text.
494  - `meta`: Information about the usage of the model.
495  
496  ## haystack_integrations.components.generators.google_genai.chat.chat_generator
497  
498  ### GoogleGenAIChatGenerator
499  
500  A component for generating chat completions using Google's Gemini models via the Google Gen AI SDK.
501  
502  Supports models like gemini-2.5-flash and other Gemini variants. For Gemini 2.5 series models,
503  enables thinking features via `generation_kwargs={"thinking_budget": value}`.
504  
505  ### Thinking Support (Gemini 2.5 Series)
506  
507  - **Reasoning transparency**: Models can show their reasoning process
508  - **Thought signatures**: Maintains thought context across multi-turn conversations with tools
509  - **Configurable thinking budgets**: Control token allocation for reasoning
510  
511  Configure thinking behavior:
512  
513  - `thinking_budget: -1`: Dynamic allocation (default)
514  - `thinking_budget: 0`: Disable thinking (Flash/Flash-Lite only)
515  - `thinking_budget: N`: Set explicit token budget
516  
517  ### Multi-Turn Thinking with Thought Signatures
518  
519  Gemini uses **thought signatures** when tools are present - encrypted "save states" that maintain
520  context across turns. Include previous assistant responses in chat history for context preservation.
521  
522  ### Authentication
523  
524  **Gemini Developer API**: Set `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable
525  **Vertex AI**: Use `api="vertex"` with Application Default Credentials or API key
526  
527  ### Authentication Examples
528  
529  **1. Gemini Developer API (API Key Authentication)**
530  
531  ```python
532  from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
533  
534  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
535  chat_generator = GoogleGenAIChatGenerator(model="gemini-2.5-flash")
536  ```
537  
538  **2. Vertex AI (Application Default Credentials)**
539  
540  ```python
541  from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
542  
543  # Using Application Default Credentials (requires gcloud auth setup)
544  chat_generator = GoogleGenAIChatGenerator(
545      api="vertex",
546      vertex_ai_project="my-project",
547      vertex_ai_location="us-central1",
548      model="gemini-2.5-flash",
549  )
550  ```
551  
552  **3. Vertex AI (API Key Authentication)**
553  
554  ```python
555  from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
556  
557  # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
558  chat_generator = GoogleGenAIChatGenerator(
559      api="vertex",
560      model="gemini-2.5-flash",
561  )
562  ```
563  
564  ### Usage example
565  
566  ```python
567  from haystack.dataclasses.chat_message import ChatMessage
568  from haystack.tools import Tool, Toolset
569  from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
570  
571  # Initialize the chat generator with thinking support
572  chat_generator = GoogleGenAIChatGenerator(
573      model="gemini-2.5-flash",
574      generation_kwargs={"thinking_budget": 1024}  # Enable thinking with 1024 token budget
575  )
576  
577  # Generate a response
578  messages = [ChatMessage.from_user("Tell me about the future of AI")]
579  response = chat_generator.run(messages=messages)
580  print(response["replies"][0].text)
581  
582  # Access reasoning content if available
583  message = response["replies"][0]
584  if message.reasonings:
585      for reasoning in message.reasonings:
586          print("Reasoning:", reasoning.reasoning_text)
587  
588  # Tool usage example with thinking
589  def weather_function(city: str):
590      return f"The weather in {city} is sunny and 25°C"
591  
592  weather_tool = Tool(
593      name="weather",
594      description="Get weather information for a city",
595      parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
596      function=weather_function
597  )
598  
599  # Can use either List[Tool] or Toolset
600  chat_generator_with_tools = GoogleGenAIChatGenerator(
601      model="gemini-2.5-flash",
602      tools=[weather_tool],  # or tools=Toolset([weather_tool])
603      generation_kwargs={"thinking_budget": -1}  # Dynamic thinking allocation
604  )
605  
606  messages = [ChatMessage.from_user("What's the weather in Paris?")]
607  response = chat_generator_with_tools.run(messages=messages)
608  ```
609  
610  ### Usage example with structured output
611  
612  ```python
613  from pydantic import BaseModel
614  from haystack.dataclasses.chat_message import ChatMessage
615  from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
616  
617  class City(BaseModel):
618      name: str
619      country: str
620      population: int
621  
622  chat_generator = GoogleGenAIChatGenerator(
623      model="gemini-2.5-flash",
624      generation_kwargs={"response_format": City}
625  )
626  
627  messages = [ChatMessage.from_user("Tell me about Paris")]
628  response = chat_generator.run(messages=messages)
629  print(response["replies"][0].text)  # JSON output matching the City schema
630  ```
631  
632  ### Usage example with FileContent embedded in a ChatMessage
633  
634  ```python
635  from haystack.dataclasses import ChatMessage, FileContent
636  from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
637  
638  file_content = FileContent.from_url("https://arxiv.org/pdf/2309.08632")
639  chat_message = ChatMessage.from_user(content_parts=[file_content, "Summarize this paper in 100 words."])
640  chat_generator = GoogleGenAIChatGenerator()
641  response = chat_generator.run(messages=[chat_message])
642  ```
643  
644  #### SUPPORTED_MODELS
645  
646  ```python
647  SUPPORTED_MODELS: list[str] = [
648      "gemini-3.1-pro-preview",
649      "gemini-3-flash-preview",
650      "gemini-3.1-flash-lite-preview",
651      "gemini-2.5-pro",
652      "gemini-2.5-flash",
653      "gemini-2.5-flash-lite",
654  ]
655  
656  ```
657  
658  A non-exhaustive list of chat models supported by this component.
659  
660  See https://ai.google.dev/gemini-api/docs/models for the full list of models and up-to-date model IDs.
661  
662  #### __init__
663  
664  ```python
665  __init__(
666      *,
667      api_key: Secret = Secret.from_env_var(
668          ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
669      ),
670      api: Literal["gemini", "vertex"] = "gemini",
671      vertex_ai_project: str | None = None,
672      vertex_ai_location: str | None = None,
673      model: str = "gemini-2.5-flash",
674      generation_kwargs: dict[str, Any] | None = None,
675      safety_settings: list[dict[str, Any]] | None = None,
676      streaming_callback: StreamingCallbackT | None = None,
677      tools: ToolsType | None = None,
678      timeout: float | None = None,
679      max_retries: int | None = None
680  ) -> None
681  ```
682  
683  Initialize a GoogleGenAIChatGenerator instance.
684  
685  **Parameters:**
686  
687  - **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
688    Not needed if using Vertex AI with Application Default Credentials.
689    Go to https://aistudio.google.com/app/apikey for a Gemini API key.
690    Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
691  - **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
692  - **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
693    Application Default Credentials.
694  - **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
695    Required when using Vertex AI with Application Default Credentials.
696  - **model** (<code>str</code>) – Name of the model to use (e.g., "gemini-2.5-flash")
697  - **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Configuration for generation (temperature, max_tokens, etc.).
698    For Gemini 2.5 series, supports `thinking_budget` to configure thinking behavior:
699  - `thinking_budget`: int, controls thinking token allocation
700    - `-1`: Dynamic (default for most models)
701    - `0`: Disable thinking (Flash/Flash-Lite only)
702    - Positive integer: Set explicit budget
703      For Gemini 3 series and newer, supports `thinking_level` to configure thinking depth:
704  - `thinking_level`: str, controls thinking (https://ai.google.dev/gemini-api/docs/thinking#levels-budgets)
705    - `minimal`: Matches the "no thinking" setting for most queries. The model may think very minimally for
706      complex coding tasks. Minimizes latency for chat or high throughput applications.
707    - `low`: Minimizes latency and cost. Best for simple instruction following, chat, or high-throughput
708      applications.
709    - `medium`: Balanced thinking for most tasks.
710    - `high`: (Default, dynamic): Maximizes reasoning depth. The model may take significantly longer to reach
711      a first token, but the output will be more carefully reasoned.
712  - **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering
713  - **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
714  - **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
715    Each tool should have a unique name.
716  - **timeout** (<code>float | None</code>) – Timeout for Google GenAI client calls. If not set, it defaults to the default set by the Google GenAI
717    client.
718  - **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
719    the Google GenAI client.
720  
721  #### to_dict
722  
723  ```python
724  to_dict() -> dict[str, Any]
725  ```
726  
727  Serializes the component to a dictionary.
728  
729  **Returns:**
730  
731  - <code>dict\[str, Any\]</code> – Dictionary with serialized data.
732  
733  #### from_dict
734  
735  ```python
736  from_dict(data: dict[str, Any]) -> GoogleGenAIChatGenerator
737  ```
738  
739  Deserializes the component from a dictionary.
740  
741  **Parameters:**
742  
743  - **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
744  
745  **Returns:**
746  
747  - <code>GoogleGenAIChatGenerator</code> – Deserialized component.
748  
749  #### run
750  
751  ```python
752  run(
753      messages: list[ChatMessage],
754      generation_kwargs: dict[str, Any] | None = None,
755      safety_settings: list[dict[str, Any]] | None = None,
756      streaming_callback: StreamingCallbackT | None = None,
757      tools: ToolsType | None = None,
758  ) -> dict[str, Any]
759  ```
760  
761  Run the Google Gen AI chat generator on the given input data.
762  
763  **Parameters:**
764  
765  - **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
766  - **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Configuration for generation. If provided, it will override
767    the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
768  - **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering. If provided, it will override the
769    default settings.
770  - **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is
771    received from the stream.
772  - **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
773    If provided, it will override the tools set during initialization.
774  
775  **Returns:**
776  
777  - <code>dict\[str, Any\]</code> – A dictionary with the following keys:
778  - `replies`: A list containing the generated ChatMessage responses.
779  
780  **Raises:**
781  
782  - <code>RuntimeError</code> – If there is an error in the Google Gen AI chat generation.
783  - <code>ValueError</code> – If a ChatMessage does not contain at least one of TextContent, ToolCall, or
784    ToolCallResult or if the role in ChatMessage is different from User, System, Assistant.
785  
786  #### run_async
787  
788  ```python
789  run_async(
790      messages: list[ChatMessage],
791      generation_kwargs: dict[str, Any] | None = None,
792      safety_settings: list[dict[str, Any]] | None = None,
793      streaming_callback: StreamingCallbackT | None = None,
794      tools: ToolsType | None = None,
795  ) -> dict[str, Any]
796  ```
797  
798  Async version of the run method. Run the Google Gen AI chat generator on the given input data.
799  
800  **Parameters:**
801  
802  - **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
803  - **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Configuration for generation. If provided, it will override
804    the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
805    See https://ai.google.dev/gemini-api/docs/thinking for possible values.
806  - **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering. If provided, it will override the
807    default settings.
808  - **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is
809    received from the stream.
810  - **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
811    If provided, it will override the tools set during initialization.
812  
813  **Returns:**
814  
815  - <code>dict\[str, Any\]</code> – A dictionary with the following keys:
816  - `replies`: A list containing the generated ChatMessage responses.
817  
818  **Raises:**
819  
820  - <code>RuntimeError</code> – If there is an error in the async Google Gen AI chat generation.
821  - <code>ValueError</code> – If a ChatMessage does not contain at least one of TextContent, ToolCall, or
822    ToolCallResult or if the role in ChatMessage is different from User, System, Assistant.