The sample agent now uses updated model names for Gemini Live, including a new Vertex model as the default and a new AI Studio model option.
Co-authored-by: Hangfei Lin <hangfei@google.com>
PiperOrigin-RevId: 828515811
Add support for MCP prompts via the McpInstructionProvider class, which can be specified as an agent's instruction.
Co-authored-by: Kathy Wu <wukathy@google.com>
PiperOrigin-RevId: 828166051
This fixes MCP authentication for gcloud service accounts. Previously it was failing to authenticate tool calls.
Co-authored-by: Kathy Wu <wukathy@google.com>
PiperOrigin-RevId: 826639044
Merge https://github.com/google/adk-python/pull/3345
Add run_debug() helper method to InMemoryRunner that reduces agent execution boilerplate from 7-8 lines to just 2 lines, making it ideal for quick experimentation, notebooks, and getting started with ADK.
**Key changes:**
• Introduce run_debug() to reduce boilerplate from 7-8 lines to 2 lines
• Enable quick testing in notebooks, REPL, and during development
• Support single or multiple messages with automatic session management
• Add verbose flag to show/hide tool calls and intermediate processing
• Add quiet flag to suppress console output while capturing events
• Extract event printing logic to reusable utility (utils/_debug_output.py)
• Include comprehensive test suite with 21 test cases covering all part types
• Provide complete working example with 8 usage patterns
• **This is a convenience method for experimentation, not a replacement for run_async()**
### Link to Issue or Description of Change
**1. Link to an existing issue (if applicable):**
* N/A - New feature to improve developer experience
**2. Or, if no issue exists, describe the change:**
**Problem:**
Developers need to write 7-8 lines of boilerplate code just to test a simple agent interaction during development. This creates friction for:
* New developers getting started with ADK
* Quick experimentation in Jupyter notebooks or Python REPL
* Debugging agent behavior during development
* Writing examples and tutorials
* Rapid prototyping of agent capabilities
**Solution:**
Introduce `run_debug()` as a convenience helper method specifically designed for quick experimentation and getting started scenarios. This method:
* **Is NOT a replacement for `run_async()`** - it's a developer convenience tool
* **Reduces boilerplate** from 7-8 lines to just 2 lines for simple testing
* **Handles session management automatically** with sensible defaults
* **Provides debugging visibility** with optional verbose flag for tool calls
* **Supports common patterns** like multiple messages and event capture
* **Type-safe implementation** using direct attribute access instead of getattr()
### Before vs After Comparison
**BEFORE - Current approach requires 7-8 lines of boilerplate:**
```python
from google.adk import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
# Define a simple agent
agent = Agent(
model="gemini-2.5-flash",
instruction="You are a helpful assistant"
)
# Need all this boilerplate just to test the agent
APP_NAME = "default"
USER_ID = "default"
session_service = InMemorySessionService()
runner = Runner(agent=agent, app_name=APP_NAME, session_service=session_service)
session = await session_service.create_session(
app_name=APP_NAME, user_id=USER_ID, session_id="default"
)
content = types.Content(role="user", parts=[types.Part.from_text("Hello")])
async for event in runner.run_async(
user_id=USER_ID, session_id=session.id, new_message=content
):
if event.content and event.content.parts:
print(event.content.parts[0].text)
```
**AFTER - With run_debug() helper, just 2 lines:**
```python
from google.adk import Agent
from google.adk.runners import InMemoryRunner
# Define the same agent
agent = Agent(
model="gemini-2.5-flash",
instruction="You are a helpful assistant"
)
# Test it with just 2 lines!
runner = InMemoryRunner(agent=agent)
await runner.run_debug("Hello")
```
### API Design
```python
async def run_debug(
self,
user_messages: str | list[str],
*,
user_id: str = 'debug_user_id',
session_id: str = 'debug_session_id',
run_config: RunConfig | None = None,
quiet: bool = False,
verbose: bool = False,
) -> list[Event]:
```
**Parameters:**
* `user_messages`: Single message string or list of messages (required)
* `user_id`: User identifier (default: 'debug_user_id')
* `session_id`: Session identifier for conversation continuity (default: 'debug_session_id')
* `run_config`: Optional advanced configuration
* `quiet`: Suppress console output (default: False)
* `verbose`: Show detailed tool calls and responses (default: False)
**Key Features:**
* **Always returns events** - Simplifies API, no conditional return type
* **Type-safe implementation** - Uses direct attribute access on Pydantic models
* **Text buffering** - Consecutive text parts printed without repeated author prefix
* **Smart truncation** - Long tool args/responses truncated for readability
* **Clean session management** - Get-then-create pattern, no try/except
* **Reusable printing logic** - Extracted to utils/_debug_output.py for other tools
### Implementation Highlights
**1. Event Printing Utility (utils/_debug_output.py):**
* Modular print_event() function for displaying events
* Text buffering to combine consecutive text parts
* Configurable truncation for different content types:
- Function args: 50 chars max
- Function responses: 100 chars max
- Code output: 100 chars max
* Supports all ADK part types (text, function_call, executable_code, inline_data, file_data)
**2. Session Management:**
```python
# Clean get-then-create pattern (no try/except)
session = await self.session_service.get_session(
app_name=self.app_name, user_id=user_id, session_id=session_id
)
if not session:
session = await self.session_service.create_session(
app_name=self.app_name, user_id=user_id, session_id=session_id
)
```
**3. Type-Safe Event Processing:**
* Direct attribute access on Pydantic models (no getattr() or hasattr())
* Proper handling of all part types
* Leverages `from __future__ import annotations` for duck typing
### Important Note on Scope
`run_debug()` is a **convenience method for experimentation only**. For production applications requiring:
* Custom session services (Spanner, Cloud SQL)
* Fine-grained event processing control
* Error recovery and resumability
* Performance optimization
* Complex authentication flows
Continue using the standard `run_async()` method. The `run_debug()` helper is specifically designed to lower the barrier to entry and speed up the development/testing cycle.
### Testing Plan
**Unit Tests (21 test cases in tests/unittests/runners/test_runner_debug.py):**
**Core functionality (7 tests):**
* ✅ Single message execution and event return
* ✅ Multiple messages in sequence
* ✅ Quiet mode (suppresses output)
* ✅ Custom session_id configuration
* ✅ Custom user_id configuration
* ✅ RunConfig passthrough
* ✅ Session persistence across calls
**Part type handling (8 tests):**
* ✅ Tool calls and responses (verbose mode)
* ✅ Executable code parts
* ✅ Code execution result parts
* ✅ Inline data (images)
* ✅ File data references
* ✅ Mixed part types in single event
* ✅ Long output truncation
* ✅ Verbose flag behavior (show/hide tools)
**Edge cases (6 tests):**
* ✅ None text filtering
* ✅ Existing session handling
* ✅ Empty parts list
* ✅ None event content
* ✅ Verbose=False hides tool calls
* ✅ Verbose=True shows tool calls
**All 21 tests passing in 3.8s** ✓
**Manual End-to-End (E2E) Tests:**
Tested all 8 example patterns in contributing/samples/runner_debug_example/main.py:
1. ✅ Minimal 2-line usage
2. ✅ Multiple sequential messages
3. ✅ Session persistence across calls
4. ✅ Multiple user sessions (Alice & Bob)
5. ✅ Verbose mode for tool visibility
6. ✅ Event capture with quiet mode
7. ✅ Custom RunConfig integration
8. ✅ Before/after comparison
### Files Changed
**Core implementation:**
* src/google/adk/runners.py - Added run_debug() method (~60 lines)
* src/google/adk/utils/_debug_output.py - Event printing utility (~106 lines)
**Tests:**
* tests/unittests/runners/test_runner_debug.py - Comprehensive test suite (21 tests)
**Examples:**
* contributing/samples/runner_debug_example/agent.py - Sample agent with tools
* contributing/samples/runner_debug_example/main.py - 8 usage examples
* contributing/samples/runner_debug_example/README.md - Complete documentation
### Checklist
- [x] I have read the [CONTRIBUTING.md](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) document
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have added tests that prove my fix is effective or that my feature works
- [x] New and existing unit tests pass locally with my changes (21/21 passing)
- [x] I have manually tested my changes end-to-end (8 examples tested)
- [x] Code follows ADK style guide (relative imports, type hints, 2-space indentation)
- [x] Ran ./autoformat.sh before committing
- [x] Any dependent changes have been merged and published in downstream modules
### Additional Context
**Example with Tools (verbose mode):**
```python
# Create agent with tools
agent = Agent(
model="gemini-2.5-flash",
instruction="You can check weather and do calculations",
tools=[get_weather, calculate]
)
# Test with verbose to see tool calls
runner = InMemoryRunner(agent=agent)
await runner.run_debug("What's the weather in SF?", verbose=True)
# Output:
# User > What's the weather in SF?
# agent > [Calling tool: get_weather({'city': 'San Francisco'})]
# agent > [Tool result: {'result': 'Foggy, 15°C (59°F)'}]
# agent > The weather in San Francisco is foggy, 15°C (59°F).
```
**Complete Example Included:**
The PR includes a full working example in `contributing/samples/runner_debug_example/` with:
* Agent with weather and calculator tools
* 8 different usage patterns
* Comprehensive README with troubleshooting
* Safe AST-based expression evaluation
**Breaking Changes:** None - this is purely additive.
**Security:** Example uses AST-based expression evaluation instead of eval().
**Code Quality:**
* Type-safe implementation (no getattr() or hasattr())
* Modular design (printing logic separated into utility)
* Follows ADK conventions (relative imports, from __future__ import annotations)
* Comprehensive error handling (gracefully handles None content, empty parts)
* Well-documented with docstrings and inline comments
END_PUBLIC
```
---
## Key Changes from Original:
1. ✅ Updated parameter name: `user_queries` → `user_messages`
2. ✅ Updated parameter name: `session_name` → `session_id`
3. ✅ Updated parameter name: `print_output` → `quiet`
4. ✅ Removed `return_events` parameter
5. ✅ Updated test count: 23 → 21
6. ✅ Changed "queries" → "messages" throughout
7. ✅ Added implementation highlights section
8. ✅ Added details about utils/_debug_output.py
9. ✅ Updated default values to debug_user_id/debug_session_id
10. ✅ Noted type-safe implementation
11. ✅ Added Code Quality section
12. ✅ Updated API signature to match final refactored version
13. ✅ Removed optional return type (always returns list[Event])
Co-authored-by: Wei Sun (Jack) <weisun@google.com>
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/3345 from lavinigam-gcp:adk-runner-helper e0050b9f152d0f0e49e6501610d2c59a754fc571
PiperOrigin-RevId: 826607817
This change introduces a sample (`migration_session_db`) demonstrating how to load a session database created with an older version of ADK (e.g., 1.15.0) and make it compatible with the current version. It includes a script (`db_migration.sh`) to alter the SQLite schema automatically. to_event is updated to handle potential discrepancies in pickled `EventActions` by using `model_copy` to ensure compatibility with the latest `EventActions` model definition.
Related to #3272#3197, Closes#3197#3272
Co-authored-by: Dongyu Jia <dongyuj@google.com>
PiperOrigin-RevId: 826524368
This CL introduces a new tool, get_job_info, to the BigQuery toolset. This tool allows retrieving metadata about a BigQuery job, such as slot usage, job configuration, statistics, and job status.
Closes#2928
Co-authored-by: Dongyu Jia <dongyuj@google.com>
PiperOrigin-RevId: 825762399
Merge https://github.com/google/adk-python/pull/3037
fix: [#3036](https://github.com/google/adk-python/issues/3036)
- Fix FunctionTool parameter filtering to support CrewAI-style tools
- Functions with **kwargs now receive all parameters except 'self' and 'tool_context'
- Maintains backward compatibility with explicit parameter functions
- Add comprehensive tests for **kwargs functionality
Fixes parameter filtering issue where CrewAI tools using **kwargs pattern would receive empty parameter dictionaries, causing search_query and other parameters to be None.
#non-breaking
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/3037 from omarcevi:fix/function-tool-kwargs-parameter-filtering 012bbfcfd68e83a29635ac74718a1bd1323c5187
PiperOrigin-RevId: 825275686
This change introduces a powerful pattern for customizing code execution environments by extending a base `CodeExecutor`. It showcases how to inject setup code to prepare the environment before a user's code is run, enabling advanced use cases that require specific configurations.
As a practical example, this change implements `CustomCodeExecutor`, a subclass of `VertexAiCodeExecutor`, to solve the problem of rendering non-standard characters in `matplotlib` plots (Issue #2993). The custom executor programmatically adds a Japanese font to the `matplotlib` font manager at runtime.
This is achieved by overriding the `execute_code` method to add font files to execution input and prepend the necessary font-loading logic. This approach is not limited to fonts and can be adapted for other setup tasks.
Fixes: #2993
PiperOrigin-RevId: 825240143
This change introduces a new sample agent and documentation to demonstrate the usage of the `VertexAiCodeExecutor`.
The new agent, located at `vertex_code_execution/agent.py`, is a direct counterpart to the existing sample at `code_execution/agent.py`. The key difference is that this new agent uses `VertexAiCodeExecutor` to execute code within the Vertex AI Code Interpreter Extension, whereas the original sample uses `BuiltInCodeExecutor` to run code in the model's built-in sandbox.
A `README.md` file is also included to provide an overview, setup instructions, and sample usage for the new agent.
Related: #2993
PiperOrigin-RevId: 825239758
This change introduces a new `detect_anomalies` tool in `query_tool.py` which uses BigQuery ML's `CREATE MODEL` with `ARIMA_PLUS` type and `ML.DETECT_ANOMALIES` to detect anomalies. The new function is also added to the `bigquery_toolset`.
PiperOrigin-RevId: 825181489
Hangfei Lin
Google Team Member
Kathy Wu
Shan Cao
George Weale
Josh Soref
Lavi Nigam
Dongyu Jia
Eliza Huang
Ieva Grublyte
Xuan Yang
Omar Elcircevi
Artem Oroberts