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
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
Remove validation for output_schema and agent transfer flags.
The check that prevented `output_schema` from co-existing with agent transfer capabilities (`disallow_transfer_to_parent` or `disallow_transfer_to_peers` being False) has been removed. The agent will no longer automatically set these transfer flags to True when `output_schema` is present.
Co-authored-by: Ieva Grublyte <ievagrublyte@google.com>
PiperOrigin-RevId: 825998224
Previously this will return true for events yielded from before_agent_callback when there are state changes.
Note with this change, it will also return false for state delta only callbacks even after main response, but this is fine as long as the actual final response event has it to be true.
Closes#2992
PiperOrigin-RevId: 825313208
Previously this will return true for events yielded from before_agent_callback when there are state changes.
Note with this change, it will also return false for state delta only callbacks even after main response, but this is fine as long as the actual final response event has it to be true.
Closes#2992
PiperOrigin-RevId: 825279439
This is so we don't need to worry about side effect of Loop in all agent type. Custom agent should do the same if there exists loop inside.
PiperOrigin-RevId: 818766305
before this change, we estimate the token count of the contents to cache and use it to compare with the threshold user set. but that's not precise , so we use the actual prompt token count of previous llm request.
We won't create cache for the very initial request
PiperOrigin-RevId: 814484840
Currently, the A2A Task -> ADK event conversion is producing the same events on the last two update events (the last is a status update marking the task complete)
The change here based on A2AClientEvent(task, update):
- if the update == None: handle the non-streaming task case and also streaming case for the initial task creation event
- if the update = TaskStatusUpdateEvent AND a message is set: emit an event with that message
- if a task status update AND no message is set: don't emit event (for example, the final status update)
- if the update is ArtifactUpdateEvent and it's final artifact: emit the event
PiperOrigin-RevId: 812878869
