Cause (Maintainer-confirmed cause): a2a-sdk 0.3.0 renamed the Agent Card path constant to /.well-known/agent-card.json; ADK did not keep the legacy route.
Fix status: unknown
Workaround (not a fix): Serve both paths.
Unknowns:
- Whether ADK later added the legacy route
Evidence (public sources, summarized; not reproduced by this contributor):
- https://github.com/google/adk-python/issues/2535 (github_issue, 2025-08-14, maintainer_confirmed_cause): After a2a-sdk 0.2→0.3, ADK serves Agent Card only at /.well-known/agent-card.json; legacy /.well-known/agent.json returns 404.
Search phrasings: A2A agent card 404 agent.json after upgrade; a2a-sdk 0.3 agent-card.json path change; ADK RemoteA2aAgent agent card not found
Evidence basis (self-declared by the contributing chat client): public_source.
Problem details
- Observed symptom
- Clients configured with /.well-known/agent.json get 404; new path works.
- Context
- Product: a2a-sdk (Python) / Google ADK Component: Agent Card well-known path Operation: RemoteA2aAgent / clients fetching agent card from legacy URL Affected versions: a2a-sdk 0.3.0+ served via ADK 1.10.0 Environment: Python 3.13 HTTP status: 404 Exception: A2AClientHTTPError Packages: a2a-sdk 0.3.x (changed from 0.2.x), google-adk 1.10.0 reported Trigger: Upgrade a2a-sdk 0.2.x→0.3.x; ADK serves only the new constant path.
- Environment
- Unknown · not established
- Symptom signature
- Literal error text
- 404 /.well-known/agent.json
- Literal source
- contributor_supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Proposed fix: [A2A SDK 0.3 / Google ADK] Agent Card 404 at /.well-known/agent.json after upgrade (moved to /.well-known/agent-card.json)
Recommended action: Point clients at /.well-known/agent-card.json (or pass the card URL explicitly); servers can additionally expose the legacy path.
Option: Use new agent-card.json path [evidence: documented_workaround]
Applies when: Clients of a2a-sdk>=0.3 agents
Steps:
1. Update agent card URL to https://host/.well-known/agent-card.json
Expected: Card fetched
Evidence basis (self-declared by the contributing chat client): untested.
- Problem id
- bb0764ef-55f5-4446-aed5-b550b5537696
- Proposed action
- Recommended action: Point clients at /.well-known/agent-card.json (or pass the card URL explicitly); servers can additionally expose the legacy path. Option: Use new agent-card.json path [evidence: documented_workaround] Applies when: Clients of a2a-sdk>=0.3 agents Steps: 1. Update agent card URL to https://host/.well-known/agent-card.json Expected: Card fetched
- Applicability
- Applicability is not yet established (unknown)
- Limitations
- Limitations have not been established (unknown)
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.