Repository navigation
Description
Summary
On 8.0.0, get_properties_by_agent / resolve_properties_for_agent match agents through adcp.adagents.normalize_url. That function drops the scheme and trailing slash but keeps host case and explicit default ports. The SDK already has a stricter canonicalizer, adcp.canonical_formats.identity.canonicalize_agent_url, which lowercases the host and strips :443/:80; the adagents helpers just don't use it.
Two related gaps in the same code path:
- one
authorized_agentsentry with a non-stringurlraisesAttributeErrorfor every lookup in the file; - the resolvers return
[]both when the agent is listed with a selector that matches nothing and when the agent isn't listed at all.
Reproduction (adcp 8.0.0)
from adcp import get_properties_by_agent
from adcp.adagents import normalize_url
from adcp.canonical_formats.identity import canonicalize_agent_url
AGENT = "https://sales.example.com/mcp"
PROPS = [{"property_id": "site", "property_type": "website", "name": "Site",
"identifiers": [{"type": "domain", "value": "pub.example"}], "tags": ["all"]}]
def entry(url, tags):
return {"url": url, "authorized_for": "x", "authorization_type": "property_tags", "property_tags": tags}
# 1. URL equivalence
for url in ("https://Sales.Example.com/mcp", "https://sales.example.com:443/mcp"):
print(f"normalize_url={normalize_url(url)!r} canonicalize_agent_url={canonicalize_agent_url(url)!r}")
listed = {"authorized_agents": [entry(AGENT, ["all"])], "properties": PROPS}
print("same agent, host case + :443 ->", len(get_properties_by_agent(listed, "https://SALES.example.com:443/mcp")), "properties")
# 2. Listed but unbound vs not listed
unbound = {"authorized_agents": [entry(AGENT, ["no-such-tag"])], "properties": PROPS}
unlisted = {"authorized_agents": [entry("https://other.example/mcp", ["all"])], "properties": PROPS}
print("listed but unbound ->", get_properties_by_agent(unbound, AGENT))
print("not listed ->", get_properties_by_agent(unlisted, AGENT))
# 3. One malformed sibling entry breaks resolution for every agent
bad = {"authorized_agents": [entry(["https://oops.example"], ["all"]), entry(AGENT, ["all"])], "properties": PROPS}
try:
get_properties_by_agent(bad, AGENT)
except Exception as exc:
print("non-string sibling url ->", type(exc).__name__, "|", exc)Output:
normalize_url='Sales.Example.com/mcp' canonicalize_agent_url='https://sales.example.com/mcp'
normalize_url='sales.example.com:443/mcp' canonicalize_agent_url='https://sales.example.com/mcp'
same agent, host case + :443 -> 0 properties
listed but unbound -> []
not listed -> []
non-string sibling url -> AttributeError | 'list' object has no attribute 'decode'
fetch_adagents accepts a file like bad, because validate_adagents (adcp/validation/legacy.py:264) never checks the url type. The crash therefore reaches callers through the normal fetch-then-resolve path.
Code: normalize_url (adcp/adagents.py:420-431); matching loop in _resolve_properties_for_agent (adagents.py:1902-1917); the same normalize_url comparison in verify_agent_authorization (adagents.py:558-570).
Why an adopter hits this
Embedded Sales Agent keeps src/services/_adagents_shapes.py (206 LOC) in front of the SDK resolver:
normalize_agent_url_for_comparelowercases the host and strips default ports, because tenant-configured agent URLs and storefront-canonicalized URLs differ only in those ways;find_agent_entrydrives a separate "listed but not bound" state in the publisher-partner UI. That state needs different publisher outreach from "not listed"._adagents_with_string_agent_urlsdeep-copies the file and drops entries whoseurlisn't a string, so one bad row doesn't take down every lookup.
Without these, a publisher that authorized ESA shows as unauthorized, and a single typo in someone else's entry makes the whole file unusable.
Ask
- Match agent URLs with RFC 3986 equivalence (host case, default port) in the adagents resolvers, e.g. by reusing
canonicalize_agent_url's rules insidenormalize_url. - Skip, or report through
validate_adagents_structure, entries whoseurlisn't a non-empty string, rather than raisingAttributeError. - Add a public lookup that returns the matching entry or entries for an agent (e.g.
find_authorized_agent_entries(adagents, agent_url)), or a resolution result carryinglisted: boolalongside the properties.
Activity
bokelley commentedon Oct 2, 2026
Triage
Classification: Bug
Bucket(s): client (note:
clientandvalidationlabels don't exist in this repo — gap noted in run summary)Status: ready-to-implement
Milestone: omitted (no target version specified)
What the experts said:
canonicalize_agent_urlreturns a full URL with scheme, but the existing protocol-agnostic matching (http://…matcheshttps://…) depends onnormalize_urlstripping the scheme. A naive replacement breakstest_get_properties_by_agent_protocol_agnostic. Also notes zero direct unit tests fornormalize_urlitself, and no lookup-path tests for Bug 2.My take: The report is precise and well-scoped. Bugs 1 and 2 share the same two loop sites and should ship together. Bug 3 (new
find_authorized_agent_entrieshelper) can ride the same PR or follow independently.Implementation brief:
Bug 1 — RFC 3986 host/port normalization in matching loops. In both
verify_agent_authorization(line 570) and_resolve_properties_for_agent(line 1915), replacenormalize_url(agent_url_from_json) != normalized_agent_urlwith a comparison overcanonicalize_agent_url— but preserve scheme-stripping for protocol-agnostic matching. Correct pattern:canonicalize_agent_url(url)then re-extractnetloc + path(i.e., the existingurlparsestep applied to the canonical URL, not the raw one). Thenormalize_urlhelper can stay for display/redirect paths; only the comparison call sites need updating. Required checks: add tests fornormalize_url("https://SALES.Example.com:443/mcp") == normalize_url("https://sales.example.com/mcp")and forget_properties_by_agentwith an uppercase-host entry matched by a lowercase-host caller URL.Bug 2 — Guard non-string
urlin both loops. Afteragent_url_from_json = agent.get("url", ""), addif not isinstance(agent_url_from_json, str) or not agent_url_from_json: continueat both sites (adagents.py:565andadagents.py:1911). Optionally add aurltype check tovalidate_adagentsinadcp/validation/legacy.py:264to surface the structural error before lookup. Required: add a test that a non-stringurlentry does not crashget_properties_by_agentorresolve_properties_for_agent.Bug 3 — New public
find_authorized_agent_entriesfunction. Addfind_authorized_agent_entries(adagents_data, agent_url) -> list[dict]toadcp/adagents.py(and re-export fromadcp/__init__.py). Extract the URL-matching loop from_resolve_properties_for_agentinto this new function and have the private helper call it. Purely additive — no changes to any existing signature. Add to the public-API test matrix.All three items are non-breaking at the patch level. Suggested PR title:
fix(adagents): RFC 3986 URL equivalence, non-string url guard, find_authorized_agent_entries.Triaged by Claude Code. Session: https://claude.ai/code/session_01W1gD2yJUiXqcTUqXnkoFrp