Catching only the deprecations that touch you — feeding the official changelog to url-context

Step 2: let url-context read only the changelog pages

This is stage 1. We hand the official URLs from watch_pages to url-context and ask it to extract only the text about deprecations and end-of-life, as plain bullets.

from google import genai
from google.genai import types
 
client = genai.Client(api_key="YOUR_API_KEY")
 
def fetch_deprecation_notes(pages: list[str]) -> tuple[str, list[dict]]:
    url_list = "\n".join(f"- {u}" for u in pages)
    prompt = (
        "Read the following official pages and extract only statements about "
        "models or features being deprecated, retired, removed, or requiring "
        "migration. Always include the date and the target name, as bullets. "
        "If there is nothing relevant, reply with only 'none'.\n"
        f"{url_list}"
    )
    resp = client.models.generate_content(
        model="gemini-flash-latest",
        contents=prompt,
        config=types.GenerateContentConfig(
            tools=[types.Tool(url_context=types.UrlContext())],
            temperature=0,
        ),
    )
    # Check retrieval status (do not swallow failures)
    meta = []
    cand = resp.candidates[0]
    if cand.url_context_metadata:
        for u in cand.url_context_metadata.url_metadata:
            meta.append({
                "url": u.retrieved_url,
                "status": str(u.url_retrieval_status),
            })
    return resp.text, meta

The easily missed part is checking url_context_metadata. url-context can fail to fetch a page and still return a plausible-sounding answer. Trust the body without looking at retrieval status, and you get handed a false sense of "nothing today." I always log each URL's url_retrieval_status, and if any run contains something other than SUCCESS, I hold the radar's verdict. I wrote up why this swallowing is dangerous, and the verification pattern for it, in a gate that verifies retrieval status before trusting the answer.

I set temperature=0 because extraction needs no creativity. The same page should yield the same result. If this wobbles, the next delta check misfires every time.

Step 3: cross-reference the manifest and receive only the impact as JSON

This is stage 2. We pass both the stage-1 text and the step-1 manifest, and ask for structure covering only the surfaces I use. No tools — just response_schema.

from pydantic import BaseModel
 
class Affected(BaseModel):
    used_id: str          # must match an id in the manifest
    change_type: str      # deprecation / removal / migration, etc.
    deadline: str         # deadline ("unknown" if not readable)
    summary: str          # one line on what happens
    action: str           # what I should do
 
class Radar(BaseModel):
    affected: list[Affected]
 
def diff_against_manifest(notes: str, manifest_yaml: str) -> Radar:
    prompt = (
        "Below are statements extracted from official pages about "
        "deprecations and migrations.\n"
        f"--- notices ---\n{notes}\n\n"
        "Below is the list of models and features I actually use.\n"
        f"--- usage (YAML) ---\n{manifest_yaml}\n\n"
        "Extract only changes related to an id in the usage list. Ignore "
        "deprecations that are unrelated. used_id must match an id in the "
        "usage list exactly; use 'unknown' if the deadline cannot be read."
    )
    resp = client.models.generate_content(
        model="gemini-flash-latest",
        contents=prompt,
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=Radar,
            temperature=0,
        ),
    )
    return Radar.model_validate_json(resp.text)

The constraint that used_id must match a manifest id pays off quietly. With it, the next delta check can decide "is this the same item?" mechanically. Try to diff on free-form summaries alone and a slightly reworded notice looks like a brand-new item, so the alert fires twice.

Because structuring is a separate call, this stage stays protected by its schema even if the entity gemini-flash-latest points to is silently promoted. If aliases make you nervous, pair this with something that catches them ahead of time in CI. I split the roles with a setup that stops non-recommended models in CI before they bite: this radar is the "notice it" half, CI is the "block it" half.

Step 4: alert only on the delta from last time

At this point you know the impact in effect right now. But if the same deprecation notice fires every run, people learn to skip it. The radar's value is delivering only what changed since last time.

import json, hashlib
from pathlib import Path
 
STATE = Path("radar_state.json")
 
def _key(a) -> str:
    raw = f"{a.used_id}|{a.change_type}|{a.deadline}"
    return hashlib.sha1(raw.encode()).hexdigest()[:12]
 
def new_items(radar: Radar) -> list[Affected]:
    prev = json.loads(STATE.read_text()) if STATE.exists() else {}
    now, fresh = {}, []
    for a in radar.affected:
        k = _key(a)
        now[k] = a.model_dump()
        if k not in prev:
            fresh.append(a)
    STATE.write_text(json.dumps(now, ensure_ascii=False, indent=2))
    return fresh

I make the delta key the combination of used_id, change_type, and deadline because I want to be re-alerted if the deadline moves earlier. Same target, but a moving deadline is an important change — it shifts the priority of the work. I keep the summary out of the key so wording drift does not misfire it.

After that, you just alert when new_items() returns something non-empty. I post to a chat channel I own, but anything works. What matters is that on quiet days, genuinely nothing arrives. Being able to trust that "nothing arrived" is, to me, the finished form of the radar.

Over-alerting and blind spots I only found by running it

Building it once was not the end. Run it for real and some days are noisy, while others stay silent when you wish they had not. Here are the fixes that worked.

Absorb alias drift

An alias like gemini-flash-latest and a concrete version like gemini-3.1-flash-image-preview show up mixed together inside the same notice. If your manifest id is written as the alias, you miss the concrete version's deprecation. I add "the concrete version this alias currently points to" to the item's note, and I tell the stage-1 extraction prompt to keep statements about both the alias and the concrete version. Blind spots dropped visibly.

Separate "announced" from "already done"

A changelog carries both upcoming shutdowns and reports of things already shut down. Giving the stage-2 schema a change_type and splitting removal (done) from deprecation (announced) lets me color-code urgency on the notification side. If a removal shows up on a surface I use, that is already an incident.

Do not let a fetch failure read as "none"

In the first version, runs where url-context failed to fetch a page passed silently as "none." Before I added the url_retrieval_status check in step 2, this was the scariest hole. On a failed fetch, I now hold the verdict and carry it to the next run. That single move brought the frequency of grabbing a false sense of safety close to zero.

Before and after these adjustments, superfluous notifications dropped by roughly 90% in my setup. More than the number itself, what mattered was being able to trust that "if an alert arrives, it really is mine to deal with."

Wrapping up

You do not need to build a large monitoring platform. There is only one thing to do first: right now, write out the model and feature names your apps and sites are calling into the step-1 YAML. That alone gives you the foundation to mechanically check, the next time a deprecation appears, whether the impact reaches you.

What I find compelling about url-context is that it lets you ground on the "most correct source" — the official page — directly, without detours. Since I started running this, I have been freed from the daily tension of opening the changelog. If it brings a similar quiet reassurance to anyone else carrying several products on their own, I would be glad. Thank you for reading.