`400 INVALID_ARGUMENT` after Python Tool Call when `VertexAiRagRetrieval` is Present in Tools List

[rdaros]

Hello everyone. This issue caused a lot of headache, so I decided to share with you. Let me know if you need any additional details. I didn't find any reference to this issue or a solution.

Describe the bug

When an ADK Agent has both a custom Python function tool (that modifies state using ToolContext) and an instance of VertexAiRagRetrieval in its tools list, the agent fails with google.genai.errors.ClientError: 400 INVALID_ARGUMENT during the LLM call immediately after the custom Python tool successfully executes and returns its result dictionary.

This failure occurs even if the VertexAiRagRetrieval tool is never actually called during the interaction sequence that leads to the error. The error seems specifically triggered by the framework preparing the next LLM request after processing the history containing the successful Python tool's FunctionResponse, but only when the VertexAiRagRetrieval tool's schema is also registered with the agent.

The custom Python tools return standard JSON-serializable dictionaries (e.g., {"result": "...", "status": "success"}). The issue persists regardless of whether an after_tool_callback modifies this response or passes it through. Disabling a before_tool_callback also did not resolve the issue.

To Reproduce

Steps to reproduce the behavior:

1. Define a simple Agent (Agent A).
2. Define a basic Python function tool (tool_py) that accepts tool_context: ToolContext, modifies the state (e.g., tool_context.state["test_key"] = "test_value"), and returns a dictionary (e.g., {"result": "Python tool success", "status": "success"}).
3. Define an instance of VertexAiRagRetrieval (tool_rag), configured with a valid corpus (using either rag.RagResource or the string resource ID for rag_resources - both trigger the bug).
4. Configure Agent A's tools list to include both: tools=[tool_py, tool_rag].
5. Provide Agent A with simple instructions, for example: "Your first action is to call the [tool_py] tool. After it finishes, just respond with the text 'Acknowledged'."
6. Run the agent interactively (adk run ... or adk web).
7. Give an initial input to trigger the agent. It should call tool_py.
8. Observe the logs. tool_py executes successfully and returns its dictionary.
9. Observe the subsequent traceback: google.genai.errors.ClientError: 400 INVALID_ARGUMENT occurs when the agent attempts the LLM call to generate the "Acknowledged" response.

Contrast:

1. Comment out tool_rag from the tools list (tools=[tool_py]).
2. Repeat steps 6-8.
3. Observe that the agent successfully calls tool_py and then successfully generates the "Acknowledged" response without error.

Expected behavior

The agent should successfully execute the custom Python tool (tool_py), process its dictionary result, and then successfully make the subsequent LLM call (e.g., to generate the "Acknowledged" message or call another tool) without encountering a 400 INVALID_ARGUMENT error, even when the VertexAiRagRetrieval instance (tool_rag) is present in the tools list but not invoked in that specific sequence.

Environment:

• OS: macOS Darwin 24.4.0
• Python version: 3.12.9
• ADK version: 0.3.0

Additional context

• The Python tools tested used ToolContext to modify session state (e.g., tool_context.state["key"] = value), which may or may not have an impact on the issue.
• Callbacks (before_tool_callback, after_tool_callback) were used during debugging but disabling them did not prevent the core issue. Tool return values were confirmed to be JSON-serializable dictionaries.

Workaround:

The issue was successfully resolved by isolating the VertexAiRagRetrieval instance within its own dedicated agent (KnowledgeAgent) whose only tool was the VertexAiRagRetrieval instance. The main agent (Agent A) then interacted with this KnowledgeAgent using AgentTool(knowledge_agent) instead of having VertexAiRagRetrieval directly in its own tools list. This prevented the direct mix of the RAG tool schema and the Python function tool schemas in Agent A and allowed the flow to complete without the 400 INVALID_ARGUMENT error.

[hangfei]

VertexAiRagRetrieval is a built-in tool so it has some limitations: https://google.github.io/adk-docs/tools/built-in-tools/#limitations

[rdaros]

@hangfei Thanks for the feedback. I saw the limitations section, but my interpretation of the section was that I could not use 2 or more built-in tools in the same agent - and not that I couldn't use ANY other tool with built-in tools. Now that I looked closely at the code snippet of that section, I see that it does show a built-in tool and a regular python function within the same agent.

Perhaps a slight clarification on the text of that section would be a good idea.

Original:
"For example, the following approach that uses two or more built-in tools within a root agent (or a single agent) is not currently supported."

Suggested Edit:
"For example, the following approach that uses a built-in tool along with other tools within a root agent (or a single agent) is not currently supported."

You guys are doing a great job, keep up the amazing work!

[hangfei]

That's a good suggestion. Thanks. Would you or someone mind sending a PR to fix it in https://github.com/google/adk-docs?

[rdaros]

Sure, I'll do it.