Merge https://github.com/google/adk-python/pull/3365
**Please ensure you have read the [contribution guide](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) before creating a pull request.**
fix typo for several files.
### 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.
- [ ] I have commented my code, particularly in hard-to-understand areas.
- [ ] 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.
- [x] I have manually tested my changes end-to-end.
- [x] Any dependent changes have been merged and published in downstream modules.
### Additional context
_Add any other context or screenshots about the feature request here._
Co-authored-by: Liang Wu <wuliang@google.com>
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/3365 from UlookEE:fix_typo 1469de4ea354d1c205268b999183ee86c9d6a1d5
PiperOrigin-RevId: 827724001
Merge #3163
END_PUBLIC
Hello,
Since global_instruction has been deprecated, I’m migrating to GlobalInstructionPlugin.
During the migration, I encountered an error and am submitting this PR to fix it.
In [df05ed6](https://github.com/google/adk-python/commit/df05ed6b3b7b218d85fddc1acd6617802cdf6f2a) ,
GlobalInstructionPlugin references invocation_context, but CallbackContext actually contains _invocation_context.
This mismatch always causes an error during execution.
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/3180 from UlookEE:fix_global_instruction_plugin e289a12d69812f0abcfe77db0114fdb2045b31bc
PiperOrigin-RevId: 827682501
Merge https://github.com/google/adk-python/pull/2326
`adk run --help` (adk 1.9.0)
```
--resume FILE The json file that contains a previously saved session
(by--save_session option). The previous session will be
re-displayed. And user can continue to interact with the
agent.
```
## testing plan
N/A (because this is a simple string correction)
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/2326 from ftnext:fix-typo-run-help-resume a896fa38e223b13e7edd8125d7b38139f1ca3712
PiperOrigin-RevId: 827311506
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
Removes the dataset_id field from the BigQuery table schema and from each log entry created by the BigQueryAgentAnalyticsPlugin. This field is redundant, as all rows logged to a specific table belong to the same dataset.
To ensure the plugin can still target the correct dataset, dataset_id is now a required argument in the BigQueryAgentAnalyticsPlugin constructor, and its default value has been removed.
The BigQuery client user_agent is also updated with plugin version info to help identify traffic originating from this plugin. Unit tests have been updated to reflect the removal of dataset_id from log entries.
PiperOrigin-RevId: 826596499
This change adds an optional `runner` parameter to the `to_a2a` function, enabling users to provide a pre-configured `Runner` instance instead of always using the default in-memory services. A new test case has been added to verify this functionality.
closes#3104
Co-authored-by: Dongyu Jia <dongyuj@google.com>
PiperOrigin-RevId: 826526861
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
It is common for expected response and expected tool calls column to be empty for user simulated conversations. So, we don't render those.
Co-authored-by: Ankur Sharma <ankusharma@google.com>
PiperOrigin-RevId: 826202867
Previously we only do a simple prefix string matching, thus `agent_00` will match with `agent_0`
With this new change, we either check directly equality, or must expect seeing `agent_0.`. See added test for branches we now match / skip.
TBF `.` is also not a perfect delimiter (I would imagine users might put dot in agent names). We might consider a follow up that bans such agent names.
Tested with script in the linked issue (I updated prompt so we see which agent they see from):
Before:
```
[agent_8]: 73
[agent_0]: 97
[agent_1]: 73
[agent_5]: 97
[agent_4]: 73
[agent_2]: 73
[agent_3]: 73
[agent_9]: 93
[agent_6]: 73
[agent_7]: 1
[agent_70]: 1 (agent_7)
[agent_20]: 73 (agent_2)
[agent_30]: 73 (agent_3)
[agent_00]: 97 (agent_0)
[agent_40]: 73 (agent_4)
[agent_80]: 73 (agent_8)
[agent_50]: 97 (agent_5)
[agent_90]: 93 (agent_9)
[agent_10]: 73 (agent_1)
[agent_60]: 73 (agent_6)
```
After:
```
[agent_9]: 73
[agent_6]: 73
[agent_2]: 73
[agent_7]: 93
[agent_4]: 73
[agent_1]: 73
[agent_3]: 73
[agent_5]: 97
[agent_0]: 73
[agent_8]: 87
[agent_50]: 0
[agent_80]: 0
[agent_10]: 0
[agent_90]: 0
[agent_30]: 0
[agent_20]: 0
[agent_60]: 0
[agent_00]: 0
[agent_40]: 0
[agent_70]: 0
```
Closes#2948
Co-authored-by: Kevin Qian <kqian@google.com>
PiperOrigin-RevId: 826187198
Merge https://github.com/google/adk-python/pull/3219
## Summary
Enhance error messages for tool and agent not found errors to provide actionable guidance and reduce developer debugging time from hours to minutes.
Fixes#3217
## Changes
### Modified Files
1. **`src/google/adk/flows/llm_flows/functions.py`**
- Enhanced `_get_tool()` error message with:
- Available tools list (formatted, truncated to 20 for readability)
- Possible causes
- Suggested fixes
- Fuzzy matching suggestions
2. **`src/google/adk/agents/llm_agent.py`**
- Enhanced `__get_agent_to_run()` error message with:
- Available agents list (formatted, truncated to 20 for readability)
- Timing/ordering issue explanation
- Fuzzy matching for agent names
- Added `_get_available_agent_names()` helper method
### New Test Files
3. **`tests/unittests/flows/llm_flows/test_functions_error_messages.py`**
- Tests for enhanced tool not found error messages
- Fuzzy matching validation
- Edge cases (no close matches, empty tools dict, 100+ tools)
4. **`tests/unittests/agents/test_llm_agent_error_messages.py`**
- Tests for enhanced agent not found error messages
- Agent tree traversal validation
- Fuzzy matching for agents
- Long list truncation
## Testing Plan
### Unit Tests
```bash
pytest tests/unittests/flows/llm_flows/test_functions_error_messages.py -v
pytest tests/unittests/agents/test_llm_agent_error_messages.py -v
```
**Results**: ✅ 8/8 tests passing
```
tests/unittests/flows/llm_flows/test_functions_error_messages.py::test_tool_not_found_enhanced_error PASSED
tests/unittests/flows/llm_flows/test_functions_error_messages.py::test_tool_not_found_fuzzy_matching PASSED
tests/unittests/flows/llm_flows/test_functions_error_messages.py::test_tool_not_found_no_fuzzy_match PASSED
tests/unittests/flows/llm_flows/test_functions_error_messages.py::test_tool_not_found_truncates_long_list PASSED
tests/unittests/agents/test_llm_agent_error_messages.py::test_agent_not_found_enhanced_error PASSED
tests/unittests/agents/test_llm_agent_error_messages.py::test_agent_not_found_fuzzy_matching PASSED
tests/unittests/agents/test_llm_agent_error_messages.py::test_agent_tree_traversal PASSED
tests/unittests/agents/test_llm_agent_error_messages.py::test_agent_not_found_truncates_long_list PASSED
8 passed, 1 warning in 4.38s
```
### Example Enhanced Error Messages
#### Before (Current Error)
```
ValueError: Function get_equipment_specs is not found in the tools_dict: dict_keys(['get_equipment_details', 'query_vendor_catalog', 'score_proposals'])
```
#### After (Enhanced Error)
```
Function 'get_equipment_specs' is not found in available tools.
Available tools: get_equipment_details, query_vendor_catalog, score_proposals
Possible causes:
1. LLM hallucinated the function name - review agent instruction clarity
2. Tool not registered - verify agent.tools list
3. Name mismatch - check for typos
Suggested fixes:
- Review agent instruction to ensure tool usage is clear
- Verify tool is included in agent.tools list
- Check for typos in function name
Did you mean one of these?
- get_equipment_details
```
## Community Impact
- **Addresses 3 active issues**: #2050, #2933 (12 comments), #2164
- **Reduces debugging time** from 3+ hours to < 5 minutes (validated in production multi-agent RFQ solution for recent partner nanothon initiative)
- **Improves developer experience** for new ADK users
## Implementation Details
- Uses standard library `difflib` for fuzzy matching (no new dependencies)
- Error path only (no performance impact on happy path)
- Measured performance: < 0.03ms per error
- Truncates long lists to first 20 items to prevent log overflow
- Fully backward compatible (same exception types)
## Checklist
- [x] Unit tests added and passing (8/8 tests)
- [x] Code formatted with `./autoformat.sh` (isort + pyink)
- [x] No new dependencies (uses standard library `difflib`)
- [x] Docstrings updated
- [x] Tested with Python 3.11
- [x] Issue #3217 created and linked
## Related Issues
- Fixes#3217
- Addresses #2050 - Tool verification callback request
- Addresses #2933 - How to handle "Function is not found in the tools_dict" Error
- Addresses #2164 - ValueError: {agent} not found in agent tree
---
**Note**: For production scenarios where LLM tool hallucinations occur, ADK's built-in [`ReflectAndRetryToolPlugin`](https://github.com/google/adk-python/blob/main/src/google/adk/plugins/reflect_retry_tool_plugin.py) can automatically retry failed tool calls (available since v1.16.0). This PR's enhanced error messages complement that by helping developers quickly identify and fix configuration issues during development.
Cheers, JP
Co-authored-by: Yvonne Yu <yyyu@google.com>
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/3219 from jpantsjoha:feat/better-error-messages a4df8bfb031685dce9e528d8eb7006f53447b75b
PiperOrigin-RevId: 826132579
Haegyun Lee
Xuan Yang
Yifan Wang
Josh Soref
Google Team Member
Kacper Jawoszek
nikkie
Jeroen Overschie
FingerLiu
Ankur Sharma
Kathy Wu
Lavi Nigam
Dongyu Jia
Eliza Huang
Kevin Qian
Jaroslav Pantsjoha