0
# Chat Models
1

2
Advanced conversational AI interface providing access to Google's Gemini chat models with comprehensive support for tool calling, structured outputs, multimodal inputs, safety controls, and streaming responses.
3

4
## Capabilities
5

6
### ChatGoogleGenerativeAI
7

8
Primary chat model interface that extends LangChain's `BaseChatModel` to provide seamless integration with Google's Gemini models.
9

10
```python { .api }
11
class ChatGoogleGenerativeAI:
12
    def __init__(
13
        self,
14
        *,
15
        model: str,
16
        google_api_key: Optional[SecretStr] = None,
17
        credentials: Any = None,
18
        temperature: float = 0.7,
19
        top_p: Optional[float] = None,
20
        top_k: Optional[int] = None,
21
        max_output_tokens: Optional[int] = None,
22
        n: int = 1,
23
        max_retries: int = 6,
24
        timeout: Optional[float] = None,
25
        client_options: Optional[Dict] = None,
26
        transport: Optional[str] = None,
27
        additional_headers: Optional[Dict[str, str]] = None,
28
        response_modalities: Optional[List[Modality]] = None,
29
        thinking_budget: Optional[int] = None,
30
        include_thoughts: Optional[bool] = None,
31
        safety_settings: Optional[Dict[HarmCategory, HarmBlockThreshold]] = None,
32
        convert_system_message_to_human: bool = False,
33
        response_mime_type: Optional[str] = None,
34
        response_schema: Optional[Dict[str, Any]] = None,
35
        cached_content: Optional[str] = None,
36
        model_kwargs: Dict[str, Any] = None,
37
        default_metadata: Optional[Sequence[Tuple[str, str]]] = None
38
    )
39
```
40

41
**Parameters:**
42
- `model` (str): Model name (e.g., "gemini-2.5-pro", "gemini-2.0-flash")
43
- `google_api_key` (Optional[SecretStr]): Google API key (defaults to GOOGLE_API_KEY env var)
44
- `credentials` (Any): Google authentication credentials object
45
- `temperature` (float): Generation temperature [0.0, 2.0], controls randomness
46
- `top_p` (Optional[float]): Nucleus sampling parameter [0.0, 1.0]
47
- `top_k` (Optional[int]): Top-k sampling parameter for vocabulary selection
48
- `max_output_tokens` (Optional[int]): Maximum tokens in response
49
- `n` (int): Number of completions to generate (default: 1)
50
- `max_retries` (int): Maximum retry attempts for failed requests (default: 6)
51
- `timeout` (Optional[float]): Request timeout in seconds
52
- `client_options` (Optional[Dict]): API client configuration options
53
- `transport` (Optional[str]): Transport method ["rest", "grpc", "grpc_asyncio"]
54
- `additional_headers` (Optional[Dict[str, str]]): Additional HTTP headers
55
- `response_modalities` (Optional[List[Modality]]): Response output modalities
56
- `thinking_budget` (Optional[int]): Thinking budget in tokens for reasoning
57
- `include_thoughts` (Optional[bool]): Include reasoning thoughts in response
58
- `safety_settings` (Optional[Dict[HarmCategory, HarmBlockThreshold]]): Content safety configuration
59
- `convert_system_message_to_human` (bool): Convert system messages to human messages
60
- `response_mime_type` (Optional[str]): Expected response MIME type
61
- `response_schema` (Optional[Dict[str, Any]]): JSON schema for structured responses
62
- `cached_content` (Optional[str]): Cached content name for context reuse
63
- `model_kwargs` (Dict[str, Any]): Additional model parameters to pass to the API
64
- `default_metadata` (Optional[Sequence[Tuple[str, str]]]): Default metadata headers for requests
65

66
### Core Methods
67

68
#### Message Generation
69

70
```python { .api }
71
def invoke(
72
    self,
73
    input: LanguageModelInput,
74
    config: Optional[RunnableConfig] = None,
75
    *,
76
    stop: Optional[List[str]] = None,
77
    code_execution: Optional[bool] = None,
78
    **kwargs: Any
79
) -> BaseMessage
80
```
81

82
Generate a single response message.
83

84
**Parameters:**
85
- `input`: Input messages, text, or prompt
86
- `config`: Optional run configuration
87
- `stop`: List of stop sequences
88
- `code_execution`: Enable code execution capabilities
89
- `**kwargs`: Additional generation parameters
90

91
**Returns:** Generated AI message
92

93
```python { .api }
94
async def ainvoke(
95
    self,
96
    input: LanguageModelInput,
97
    config: Optional[RunnableConfig] = None,
98
    **kwargs: Any
99
) -> BaseMessage
100
```
101

102
Async version of invoke().
103

104
#### Streaming
105

106
```python { .api }
107
def stream(
108
    self,
109
    input: LanguageModelInput,
110
    config: Optional[RunnableConfig] = None,
111
    *,
112
    stop: Optional[List[str]] = None,
113
    **kwargs: Any
114
) -> Iterator[ChatGenerationChunk]
115
```
116

117
Stream response chunks as they're generated.
118

119
**Returns:** Iterator of chat generation chunks
120

121
```python { .api }
122
async def astream(
123
    self,
124
    input: LanguageModelInput,
125
    config: Optional[RunnableConfig] = None,
126
    **kwargs: Any
127
) -> AsyncIterator[ChatGenerationChunk]
128
```
129

130
Async version of stream().
131

132
### Tool Calling
133

134
#### Bind Tools
135

136
```python { .api }
137
def bind_tools(
138
    self,
139
    tools: Sequence[Union[Dict[str, Any], Type[BaseModel], Callable, BaseTool]],
140
    *,
141
    tool_config: Optional[Dict] = None,
142
    tool_choice: Optional[Union[str, Literal["auto", "required"]]] = None,
143
    **kwargs: Any
144
) -> Runnable
145
```
146

147
Bind tools to the model for function calling capabilities.
148

149
**Parameters:**
150
- `tools`: Sequence of tools (functions, Pydantic models, or tool objects)
151
- `tool_config`: Tool configuration options
152
- `tool_choice`: Tool selection strategy ("auto", "required", or specific tool name)
153

154
**Returns:** Runnable model with bound tools
155

156
#### Structured Output
157

158
```python { .api }
159
def with_structured_output(
160
    self,
161
    schema: Union[Dict, Type[BaseModel]],
162
    *,
163
    method: Literal["function_calling", "json_mode"] = "function_calling",
164
    include_raw: bool = False,
165
    **kwargs: Any
166
) -> Runnable
167
```
168

169
Configure the model to return structured output matching a schema.
170

171
**Parameters:**
172
- `schema`: Output schema (dict or Pydantic model)
173
- `method`: Output method ("function_calling" or "json_mode")
174
- `include_raw`: Include raw response alongside structured output
175

176
**Returns:** Runnable model configured for structured output
177

178
### Utility Methods
179

180
```python { .api }
181
def get_num_tokens(self, text: str) -> int
182
```
183

184
Estimate token count for input text.
185

186
**Parameters:**
187
- `text` (str): Input text to count tokens for
188

189
**Returns:** Estimated token count
190

191
## Usage Examples
192

193
### Basic Chat
194

195
```python
196
from langchain_google_genai import ChatGoogleGenerativeAI
197

198
# Initialize model
199
llm = ChatGoogleGenerativeAI(model="gemini-2.5-pro")
200

201
# Simple text generation
202
response = llm.invoke("Explain the concept of machine learning")
203
print(response.content)
204
```
205

206
### Streaming Responses
207

208
```python
209
# Stream response chunks
210
for chunk in llm.stream("Write a creative story about robots"):
211
    print(chunk.content, end="", flush=True)
212
```
213

214
### Tool Calling
215

216
```python
217
from pydantic import BaseModel, Field
218

219
class WeatherTool(BaseModel):
220
    """Get weather information for a location."""
221
    location: str = Field(description="The city and state")
222
    
223
def get_weather(location: str) -> str:
224
    return f"Weather in {location}: 72°F, sunny"
225

226
# Bind tools to model
227
llm_with_tools = llm.bind_tools([WeatherTool])
228

229
# Use tools in conversation
230
response = llm_with_tools.invoke("What's the weather like in San Francisco?")
231

232
# Process tool calls
233
if response.tool_calls:
234
    for tool_call in response.tool_calls:
235
        if tool_call["name"] == "WeatherTool":
236
            result = get_weather(tool_call["args"]["location"])
237
            print(result)
238
```
239

240
### Structured Output
241

242
```python
243
from pydantic import BaseModel
244

245
class PersonInfo(BaseModel):
246
    name: str
247
    age: int
248
    occupation: str
249

250
# Configure for structured output
251
structured_llm = llm.with_structured_output(PersonInfo)
252

253
# Get structured response
254
result = structured_llm.invoke("Tell me about a fictional character")
255
print(f"Name: {result.name}, Age: {result.age}, Job: {result.occupation}")
256
```
257

258
### Safety Settings
259

260
```python
261
from langchain_google_genai import HarmCategory, HarmBlockThreshold
262

263
# Configure safety settings
264
safe_llm = ChatGoogleGenerativeAI(
265
    model="gemini-2.5-pro",
266
    safety_settings={
267
        HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
268
        HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
269
    }
270
)
271

272
response = safe_llm.invoke("Generate content with safety controls")
273
```
274

275
### Advanced Features
276

277
```python
278
# Enable reasoning mode
279
reasoning_llm = ChatGoogleGenerativeAI(
280
    model="gemini-2.5-pro",
281
    thinking_budget=8192,  # Budget for internal reasoning
282
    include_thoughts=True   # Include reasoning in response
283
)
284

285
response = reasoning_llm.invoke("Solve this complex math problem step by step")
286
print("Reasoning:", response.response_metadata.get("thoughts"))
287
print("Answer:", response.content)
288
```
289

290
### Multimodal Inputs
291

292
```python
293
from langchain_core.messages import HumanMessage
294

295
# Image analysis
296
message = HumanMessage(content=[
297
    {"type": "text", "text": "What do you see in this image?"},
298
    {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
299
])
300

301
response = llm.invoke([message])
302
print(response.content)
303
```
304

305
## Error Handling
306

307
Handle errors appropriately:
308

309
```python
310
from langchain_google_genai import ChatGoogleGenerativeAI
311

312
try:
313
    llm = ChatGoogleGenerativeAI(model="gemini-2.5-pro")
314
    response = llm.invoke("Your prompt here")
315
except Exception as e:
316
    if "safety" in str(e).lower():
317
        print(f"Safety filter blocked content: {e}")
318
    elif "rate" in str(e).lower():
319
        print(f"Rate limit exceeded: {e}")
320
    else:
321
        print(f"Generation error: {e}")
322
```