0
# Execution Engine
1
2
Runners provide the execution environment for agents, supporting synchronous, asynchronous, and streaming execution modes with resource management and cleanup.
3
4
## Capabilities
5
6
### Core Runner Classes
7
8
Main execution engines that provide different execution modes and environments for agents.
9
10
```python { .api }
11
class Runner:
12
"""Main execution engine with methods for different execution modes."""
13
14
def __init__(
15
self,
16
*,
17
app_name: str,
18
agent: BaseAgent,
19
plugins: Optional[List[BasePlugin]] = None,
20
artifact_service: Optional[BaseArtifactService] = None,
21
session_service: BaseSessionService,
22
memory_service: Optional[BaseMemoryService] = None,
23
credential_service: Optional[BaseCredentialService] = None,
24
):
25
"""
26
Initialize the runner.
27
28
Args:
29
app_name (str): The application name of the runner
30
agent (BaseAgent): The root agent to run
31
plugins (Optional[List[BasePlugin]]): A list of plugins for the runner
32
artifact_service (Optional[BaseArtifactService]): The artifact service for the runner
33
session_service (BaseSessionService): The session service for the runner
34
memory_service (Optional[BaseMemoryService]): The memory service for the runner
35
credential_service (Optional[BaseCredentialService]): The credential service for the runner
36
"""
37
pass
38
39
def run(
40
self,
41
*,
42
user_id: str,
43
session_id: str,
44
new_message: types.Content,
45
run_config: RunConfig = RunConfig(),
46
) -> Generator[Event, None, None]:
47
"""
48
Execute agent synchronously.
49
50
Args:
51
user_id (str): The user ID of the session
52
session_id (str): The session ID of the session
53
new_message (types.Content): A new message to append to the session
54
run_config (RunConfig): The run config for the agent
55
56
Yields:
57
Event: The events generated by the agent
58
"""
59
pass
60
61
async def run_async(
62
self,
63
*,
64
user_id: str,
65
session_id: str,
66
new_message: types.Content,
67
state_delta: Optional[dict[str, Any]] = None,
68
run_config: RunConfig = RunConfig(),
69
) -> AsyncGenerator[Event, None]:
70
"""
71
Execute agent asynchronously.
72
73
Args:
74
user_id (str): The user ID of the session
75
session_id (str): The session ID of the session
76
new_message (types.Content): A new message to append to the session
77
state_delta (Optional[dict[str, Any]]): Optional state changes
78
run_config (RunConfig): The run config for the agent
79
80
Yields:
81
Event: The events generated by the agent
82
"""
83
pass
84
85
async def run_live(
86
self,
87
*,
88
user_id: Optional[str] = None,
89
session_id: Optional[str] = None,
90
live_request_queue: LiveRequestQueue,
91
run_config: RunConfig = RunConfig(),
92
session: Optional[Session] = None,
93
) -> AsyncGenerator[Event, None]:
94
"""
95
Execute agent in live/streaming mode.
96
97
Args:
98
user_id (Optional[str]): The user ID for the session. Required if session is None
99
session_id (Optional[str]): The session ID for the session. Required if session is None
100
live_request_queue (LiveRequestQueue): The queue for live requests
101
run_config (RunConfig): The run config for the agent
102
session (Optional[Session]): The session to use (deprecated)
103
104
Yields:
105
Event: Events from the agent's live execution
106
"""
107
pass
108
109
async def close(self):
110
"""Clean up resources and close the runner."""
111
pass
112
113
class InMemoryRunner(Runner):
114
"""In-memory runner for testing and development."""
115
116
def __init__(
117
self,
118
agent: BaseAgent,
119
*,
120
app_name: str = 'InMemoryRunner',
121
plugins: Optional[list[BasePlugin]] = None,
122
):
123
"""
124
Initialize in-memory runner.
125
126
Args:
127
agent (BaseAgent): The root agent to run
128
app_name (str): The application name of the runner. Defaults to 'InMemoryRunner'
129
plugins (Optional[list[BasePlugin]]): A list of plugins for the runner
130
"""
131
pass
132
```
133
134
## Usage Examples
135
136
### Basic Synchronous Execution
137
138
```python
139
from google.adk.agents import Agent
140
from google.adk.runners import InMemoryRunner
141
from google.genai import types
142
143
# Create agent and in-memory runner (recommended for simple usage)
144
agent = Agent(name="assistant", model="gemini-2.0-flash")
145
runner = InMemoryRunner(agent)
146
147
# Create message content
148
user_message = types.Content(parts=[types.Part(text="Hello, how can you help me?")])
149
150
# Execute synchronously and process events
151
for event in runner.run(
152
user_id="user123",
153
session_id="session456",
154
new_message=user_message
155
):
156
if event.content and not event.partial:
157
print(event.content)
158
159
# Clean up
160
await runner.close()
161
```
162
163
### Asynchronous Execution
164
165
```python
166
import asyncio
167
from google.adk.agents import Agent
168
from google.adk.runners import InMemoryRunner
169
from google.genai import types
170
171
async def main():
172
agent = Agent(name="async_assistant", model="gemini-2.0-flash")
173
runner = InMemoryRunner(agent)
174
175
# Create message content
176
user_message = types.Content(parts=[types.Part(text="What's the weather like?")])
177
178
# Execute asynchronously and process events
179
async for event in runner.run_async(
180
user_id="user123",
181
session_id="session456",
182
new_message=user_message
183
):
184
if event.content and not event.partial:
185
print(event.content)
186
187
await runner.close()
188
189
# Run the async function
190
asyncio.run(main())
191
```
192
193
### Live/Streaming Execution
194
195
```python
196
from google.adk import Runner
197
from google.adk.agents import Agent
198
199
agent = Agent(name="streaming_assistant", model="gemini-2.0-flash")
200
runner = Runner()
201
202
# Execute in live mode for streaming responses
203
for chunk in runner.run_live(agent, input_text="Tell me a story"):
204
print(chunk, end="", flush=True)
205
206
runner.close()
207
```
208
209
### In-Memory Runner for Testing
210
211
```python
212
from google.adk.runners import InMemoryRunner
213
from google.adk.agents import Agent
214
215
# Use in-memory runner for development/testing
216
runner = InMemoryRunner()
217
agent = Agent(name="test_agent", model="gemini-2.0-flash")
218
219
response = runner.run(agent, "Test input")
220
print(response)
221
222
runner.close()
223
```
224
225
### Context Manager Pattern
226
227
```python
228
from google.adk import Runner
229
from google.adk.agents import Agent
230
231
agent = Agent(name="context_agent", model="gemini-2.0-flash")
232
233
# Use runner as context manager for automatic cleanup
234
with Runner() as runner:
235
response = runner.run(agent, "What can you do?")
236
print(response)
237
# Runner is automatically closed
238
```
239
240
### Batch Processing
241
242
```python
243
from google.adk import Runner
244
from google.adk.agents import Agent
245
246
agent = Agent(name="batch_processor", model="gemini-2.0-flash")
247
runner = Runner()
248
249
inputs = [
250
"Summarize this text...",
251
"Translate this to French...",
252
"Analyze this data..."
253
]
254
255
responses = []
256
for input_text in inputs:
257
response = runner.run(agent, input_text)
258
responses.append(response)
259
260
runner.close()
261
```
262
263
### Error Handling
264
265
```python
266
from google.adk import Runner
267
from google.adk.agents import Agent
268
269
agent = Agent(name="error_handling_agent", model="gemini-2.0-flash")
270
runner = Runner()
271
272
try:
273
response = runner.run(agent, "Process this request", timeout=30)
274
print(response)
275
except TimeoutError:
276
print("Agent execution timed out")
277
except Exception as e:
278
print(f"Error during execution: {e}")
279
finally:
280
runner.close()
281
```