0
# Google Agent Development Kit (ADK)
1

2
A comprehensive Python framework designed for building, evaluating, and deploying sophisticated AI agents with maximum flexibility and control. This code-first toolkit provides developers with a rich ecosystem of pre-built tools, seamless integration with the Google ecosystem (particularly Gemini models), and the ability to create modular multi-agent systems that can be deployed anywhere from Cloud Run to Vertex AI Agent Engine.
3

4
## Package Information
5

6
- **Package Name**: google-adk
7
- **Language**: Python 3.9+
8
- **Installation**: `pip install google-adk`
9
- **License**: Apache 2.0
10
- **Documentation**: https://google.github.io/adk-docs/
11

12
## Core Imports
13

14
```python
15
import google.adk
16
from google.adk import Agent, Runner
17
```
18

19
For agents and execution:
20

21
```python
22
from google.adk.agents import Agent, LlmAgent, BaseAgent, LoopAgent, ParallelAgent, SequentialAgent
23
from google.adk.runners import Runner, InMemoryRunner
24
```
25

26
For tools:
27

28
```python
29
from google.adk.tools import BaseTool, FunctionTool, google_search, enterprise_web_search
30
```
31

32
## Basic Usage
33

34
### Single Agent
35

36
```python
37
from google.adk.agents import Agent
38
from google.adk.tools import google_search
39

40
# Create a simple search assistant
41
agent = Agent(
42
    name="search_assistant",
43
    model="gemini-2.0-flash",
44
    instruction="You are a helpful assistant. Answer user questions using Google Search when needed.",
45
    description="An assistant that can search the web.",
46
    tools=[google_search]
47
)
48

49
# Run the agent using InMemoryRunner (recommended for simple usage)
50
from google.adk.runners import InMemoryRunner
51
from google.genai import types
52

53
runner = InMemoryRunner(agent)
54
user_message = types.Content(parts=[types.Part(text="What's the weather like today?")])
55

56
# Execute and get events
57
for event in runner.run(
58
    user_id="user123",
59
    session_id="session456", 
60
    new_message=user_message
61
):
62
    if event.content:
63
        print(event.content)
64
```
65

66
### Multi-Agent System
67

68
```python
69
from google.adk.agents import LlmAgent
70

71
# Define individual agents
72
greeter = LlmAgent(
73
    name="greeter", 
74
    model="gemini-2.0-flash",
75
    instruction="Greet users warmly and professionally."
76
)
77

78
task_executor = LlmAgent(
79
    name="task_executor", 
80
    model="gemini-2.0-flash",
81
    instruction="Execute tasks efficiently and provide detailed results."
82
)
83

84
# Create coordinator agent with sub-agents
85
coordinator = LlmAgent(
86
    name="Coordinator",
87
    model="gemini-2.0-flash",
88
    description="I coordinate greetings and tasks.",
89
    sub_agents=[greeter, task_executor]
90
)
91

92
# Run the multi-agent system using InMemoryRunner
93
from google.adk.runners import InMemoryRunner
94
from google.genai import types
95

96
runner = InMemoryRunner(coordinator)
97
user_message = types.Content(parts=[types.Part(text="Hello, can you help me with a task?")])
98

99
# Execute and get events
100
for event in runner.run(
101
    user_id="user123",
102
    session_id="session456",
103
    new_message=user_message
104
):
105
    if event.content:
106
        print(event.content)
107
```
108

109
## Architecture
110

111
The ADK follows a modular, hierarchical architecture:
112

113
- **Agents**: Core agent classes (BaseAgent, LlmAgent, specialized agents)
114
- **Runners**: Execution engines for synchronous, asynchronous, and live execution
115
- **Tools**: Extensible tool framework for agent capabilities
116
- **Models**: LLM integration layer supporting Gemini and other models
117
- **Services**: Infrastructure for memory, sessions, artifacts, and authentication
118
- **Plugins**: Extensible plugin system for custom functionality
119

120
## Capabilities
121

122
### Agent Framework
123

124
Core agent classes and configuration for building single agents and multi-agent systems, supporting various execution patterns and orchestration strategies.
125

126
```python { .api }
127
class Agent: ...  # Main agent class (alias for LlmAgent)
128
class BaseAgent: ...  # Abstract base class for all agents
129
class LlmAgent: ...  # LLM-based agent implementation
130
class LoopAgent: ...  # Agent that executes in a loop
131
class ParallelAgent: ...  # Agent for parallel task execution
132
class SequentialAgent: ...  # Agent for sequential task execution
133
```
134

135
[Agent Framework](./agents.md)
136

137
### Execution Engine
138

139
Runners provide the execution environment for agents, supporting synchronous, asynchronous, and streaming execution modes with resource management and cleanup.
140

141
```python { .api }
142
class Runner:
143
    def __init__(
144
        self,
145
        *,
146
        app_name: str,
147
        agent: BaseAgent,
148
        plugins: Optional[List[BasePlugin]] = None,
149
        artifact_service: Optional[BaseArtifactService] = None,
150
        session_service: BaseSessionService,
151
        memory_service: Optional[BaseMemoryService] = None,
152
        credential_service: Optional[BaseCredentialService] = None,
153
    ): ...
154
    
155
    def run(
156
        self,
157
        *,
158
        user_id: str,
159
        session_id: str,
160
        new_message: types.Content,
161
        run_config: RunConfig = RunConfig(),
162
    ) -> Generator[Event, None, None]: ...
163
    
164
    async def run_async(
165
        self,
166
        *,
167
        user_id: str,
168
        session_id: str,
169
        new_message: types.Content,
170
        state_delta: Optional[dict[str, Any]] = None,
171
        run_config: RunConfig = RunConfig(),
172
    ) -> AsyncGenerator[Event, None]: ...
173
    
174
    async def run_live(
175
        self,
176
        *,
177
        user_id: Optional[str] = None,
178
        session_id: Optional[str] = None,
179
        live_request_queue: LiveRequestQueue,
180
        run_config: RunConfig = RunConfig(),
181
        session: Optional[Session] = None,
182
    ) -> AsyncGenerator[Event, None]: ...
183
    
184
    async def close(self): ...
185

186
class InMemoryRunner(Runner):
187
    def __init__(
188
        self,
189
        agent: BaseAgent,
190
        *,
191
        app_name: str = 'InMemoryRunner',
192
        plugins: Optional[list[BasePlugin]] = None,
193
    ): ...
194
```
195

196
[Execution Engine](./runners.md)
197

198
### Tools Framework
199

200
Comprehensive tool ecosystem including built-in tools, custom function wrappers, and specialized toolsets for Google Cloud services, databases, and APIs.
201

202
```python { .api }
203
class BaseTool: ...  # Base class for all tools
204
class FunctionTool: ...  # Tool wrapper for Python functions
205
class LongRunningFunctionTool: ...  # Tool for long-running operations
206
class AgentTool: ...  # Tool for agent interactions
207

208
# Built-in tool functions
209
def google_search(query: str, **kwargs): ...
210
def enterprise_web_search(query: str, **kwargs): ...
211
def url_context(url: str): ...
212
def get_user_choice(choices: list, prompt: str = None): ...
213
```
214

215
[Tools Framework](./tools.md)
216

217
### Language Models
218

219
Model integration layer supporting Google Gemini and other LLM providers with a unified interface and model registry for management.
220

221
```python { .api }
222
class BaseLlm: ...  # Base class for LLM implementations
223
class Gemini: ...  # Google Gemini LLM implementation
224
class LLMRegistry: ...  # Registry for LLM model management
225
```
226

227
[Language Models](./models.md)
228

229
### Google Cloud Integration
230

231
Specialized toolsets for Google Cloud services including BigQuery, Bigtable, Spanner, and Google APIs (Calendar, Gmail, Sheets, Docs, YouTube).
232

233
```python { .api }
234
class BigQueryToolset: ...  # BigQuery database interaction
235
class BigtableToolset: ...  # Bigtable interaction toolset
236
class SpannerToolset: ...  # Spanner database interaction
237
class GoogleApiToolset: ...  # Generic Google API toolset
238
class CalendarToolset: ...  # Google Calendar integration
239
class GmailToolset: ...  # Gmail integration
240
```
241

242
[Google Cloud Integration](./google-cloud.md)
243

244
### Memory and Session Management
245

246
Infrastructure services for persistent memory, session state, and artifact storage with support for in-memory and cloud-based implementations.
247

248
```python { .api }
249
class BaseMemoryService: ...  # Base class for memory services
250
class InMemoryMemoryService: ...  # In-memory memory implementation
251
class VertexAiMemoryBankService: ...  # Vertex AI memory bank service
252

253
class BaseSessionService: ...  # Base class for session services
254
class InMemorySessionService: ...  # In-memory session implementation
255
class VertexAiSessionService: ...  # Vertex AI session service
256
```
257

258
[Memory and Sessions](./memory-sessions.md)
259

260
### Authentication and Security
261

262
Authentication framework supporting OAuth2, OpenID Connect, and Google Cloud authentication with configurable schemes and credential management.
263

264
```python { .api }
265
class AuthCredential: ...  # Authentication credential object
266
class OAuth2Auth: ...  # OAuth2 authentication
267
class OpenIdConnectWithConfig: ...  # OpenID Connect authentication
268
class AuthHandler: ...  # Authentication handler
269
class AuthConfig: ...  # Authentication configuration
270
```
271

272
[Authentication](./authentication.md)
273

274
### Code Execution
275

276
Code execution framework supporting built-in, local, container-based, and Vertex AI code execution environments with safety controls.
277

278
```python { .api }
279
class BaseCodeExecutor: ...  # Base class for code executors
280
class BuiltInCodeExecutor: ...  # Built-in code executor
281
class UnsafeLocalCodeExecutor: ...  # Local code executor (unsafe)
282
class VertexAiCodeExecutor: ...  # Vertex AI code executor
283
class ContainerCodeExecutor: ...  # Container-based code executor
284
```
285

286
[Code Execution](./code-execution.md)
287

288
### Advanced Features
289

290
Planning, evaluation, event system, and plugin framework for sophisticated agent behaviors and custom extensions.
291

292
```python { .api }
293
class BasePlanner: ...  # Base class for planners
294
class BuiltInPlanner: ...  # Built-in planner implementation
295
class AgentEvaluator: ...  # Agent evaluation framework
296
class Event: ...  # Event object for agent communication
297
class BasePlugin: ...  # Base class for plugins
298
```
299

300
[Advanced Features](./advanced.md)
301

302
## Types
303

304
```python { .api }
305
# Core execution types
306
class InvocationContext:
307
    """Context passed during agent invocation."""
308
    pass
309

310
class RunConfig:
311
    """Configuration for agent execution."""
312
    pass
313

314
class Event:
315
    """Event object for agent communication and results."""
316
    pass
317

318
# Tool and context types
319
class ToolContext:
320
    """Context passed to tools during execution."""
321
    pass
322

323
# Live streaming types  
324
class LiveRequest:
325
    """Live request object for streaming."""
326
    pass
327

328
class LiveRequestQueue:
329
    """Queue for managing live requests."""
330
    pass
331

332
# Session and memory types
333
class Session:
334
    """Session object for conversation state."""
335
    pass
336

337
# Service interfaces
338
class BaseAgent:
339
    """Abstract base class for all agents."""
340
    pass
341

342
class BasePlugin:
343
    """Base class for plugins."""
344
    pass
345

346
class BaseArtifactService:
347
    """Base class for artifact services."""
348
    pass
349

350
class BaseSessionService:
351
    """Base class for session services."""
352
    pass
353

354
class BaseMemoryService:
355
    """Base class for memory services."""
356
    pass
357

358
class BaseCredentialService:
359
    """Base class for credential services."""
360
    pass
361

362
# External types (from google.genai)
363
from google.genai import types  # Content, Part, etc.
364
from typing import Generator, AsyncGenerator, Optional, List, Any
365
```