Skip to content

url_context tool's retrieval status is discarded: LlmResponse drops candidate.url_context_metadata #8226

Description

@karthik-0306

🔴 Required Information

Describe the Bug:
When the built-in url_context tool is used, Gemini reports what happened to each URL in candidate.url_context_metadata: the retrieved URL and a url_retrieval_status (SUCCESS, ERROR, PAYWALL, UNSAFE). LlmResponse.create (models/llm_response.py) copies grounding_metadata, citation_metadata and the logprobs from the candidate, but LlmResponse has no field for url_context_metadata, so it's discarded. The field name appears nowhere in src/google/adk.

As a result, callbacks, plugins, events and evals can't tell whether the model actually read the page. A failed or paywalled fetch looks the same as a successful one, and the model may have answered from its own knowledge instead.

Steps to Reproduce:

  1. pip install google-adk
  2. Run this script. It needs no API key:
from google.genai import types
from google.adk.models.llm_response import LlmResponse

resp = types.GenerateContentResponse(candidates=[types.Candidate(
    content=types.Content(role="model", parts=[types.Part(text="The page says X.")]),
    finish_reason=types.FinishReason.STOP,
    url_context_metadata=types.UrlContextMetadata(url_metadata=[
        types.UrlMetadata(
            retrieved_url="https://example.com/a",
            url_retrieval_status=types.UrlRetrievalStatus.URL_RETRIEVAL_STATUS_ERROR,
        )
    ]),
)])
r = LlmResponse.create(resp)
print(getattr(r, "url_context_metadata", "<no such field>"))
print("url_retrieval" in r.model_dump_json())

Expected Behavior:
LlmResponse (and so the resulting Event) carries url_context_metadata, the same way it carries grounding_metadata for google_search. Then an after_model_callback can react to URL_RETRIEVAL_STATUS_ERROR, for example by telling the user the page couldn't be read.

Observed Behavior:

<no such field>
False

Environment Details:

  • ADK Library Version: 2.14.1 (main @ c74df83)
  • Desktop OS: Windows 11 (the bug isn't OS-specific)
  • Python Version: 3.11

Model Information:

  • Are you using LiteLLM: No
  • Which model is being used: any Gemini model that supports the url_context tool

🟡 Optional Information

Regression:
No. The field has never been carried over.

Proposed fix:
Add url_context_metadata: types.UrlContextMetadata | None = None to LlmResponse and set it from the candidate in both branches of LlmResponse.create, as citation_metadata is. Events are stored as JSON in the v1 session schema, so the field is persisted without a migration. Add unit tests for the success branch and the error-finish branch. I'm happy to send a PR.

Activity

  1. added
    tools[Component] This issue is related to tools
    core[Component] This issue is related to the core interface and implementation
    and removed
    tools[Component] This issue is related to tools
    on Nov 20, 2026
  2. llalitkumarrr commented on Nov 20, 2026

    @llalitkumarrr
    Collaborator

    Hello @karthik-0306 ,

    Thank you for raising this issue and for your contribution, your PR is currently under review. It will be merged once the reviewer approves the changes and all checks pass. If we have further questions we will reach out to you. In the meantime we appreciate your patience.

  3. karthik-0306 commented on Nov 20, 2026

    @karthik-0306
    Author

    Thanks @llalitkumarrr! Happy to make any changes if the reviewer needs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

core[Component] This issue is related to the core interface and implementation

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions