Verifying an Agent Card Locally
Quick answer: Verify an agent card locally before you send a task. Discovery uses an explicit URL, normally /.well-known/agent-card.json, sends no credentials, refuses redirects, and caps the response at 1 MiB. The desktop then checks the card's structure and security fields, and unsigned or unverified cards are labeled rather than trusted by default.
Why the card is checked first
The card is the basis for everything that follows. It names the skills, endpoints, and security the agent offers, and a caller that skips verification builds on claims it never confirmed. A malformed card, a redirect that points elsewhere, or an oversized response can all change what the caller ends up talking to.
Verifying the card up front keeps those risks out of the later task calls.
Consider a card that responds with a redirect to a host on a different domain. A fetch that follows it would let the original URL decide where the caller actually connects, and the caller might send tasks to a service it never intended to trust. Refusing the redirect surfaces that move instead of hiding it, and the caller can decide whether the new host is acceptable rather than discovering it after tasks are sent. The same logic applies to an oversized response: a document far above the cap is rejected as a card rather than parsed, which keeps a large or hostile payload from being treated as a valid description.
The discovery rules
Discovery is deliberately constrained rather than a free-form fetch.
| Rule | Setting |
|---|---|
| URL | Explicit, normally /.well-known/agent-card.json |
| Credentials | None sent |
| Redirects | Refused |
| Response size | Capped at 1 MiB |
Sending no credentials keeps the discovery from leaking identity, and refusing redirects stops a card from silently pointing the caller at a different host. The size cap prevents a large response from being treated as a valid card.
What the local check covers
Once the card is fetched, the desktop reads it locally rather than trusting a remote label.
- Confirm the card is fetched from the explicit URL and is within the size cap.
- Check the structure and the required fields.
- Read the security fields and the declared skills.
- Label unsigned or unverified cards rather than accepting them.
- Save a snapshot without treating it as a trust decision.
A saved snapshot is a record of the card at a point in time, not a decision that the card is trusted. The distinction matters because the card can change later, and a snapshot does not update on its own.
Re-verify the card when the integration changes rather than relying on an old snapshot. A card is a live document, and the skills or security can change between runs, so a snapshot that was valid last week may not match what the host serves today. Treat each fetch as a fresh check, and keep the old snapshot only as a record rather than a current decision.
How trust stays separate from structure
A structurally valid card is not the same as a trusted one. The check can confirm the fields are present and well-formed while still leaving the identity question open, and an unsigned card is labeled as such rather than promoted.
When the card carries a signature, the JWS check verifies the standard fields against the supplied key, but it does not prove the key belongs to the claimed organization. Keep that boundary in mind, because a card that parses cleanly can still come from an unverified source.
Powerduck keeps the discovery limits and the labeling in the desktop, so a card is verified before it drives any task.
Frequently asked questions
Where is the agent card fetched from? An explicit URL, normally /.well-known/agent-card.json, with no credentials and no redirects.
Why is the response capped at 1 MiB? To keep an oversized payload from being treated as a valid card and to bound the discovery.
Does saving a card snapshot mean I trust it? No. The snapshot is a record, and unsigned or unverified cards stay labeled rather than trusted.
The bottom line
Treat the agent card as a claim to verify, not a fact to accept. Fetch it from an explicit URL with no credentials, refuse redirects, cap the response at 1 MiB, and check the structure and security fields locally. A well-formed card can still be unverified, and a snapshot is not a trust decision. Doing this before any task leaves the caller is what keeps A2A work grounded. Read more in the A2A guide.