spec/adoption: the profile MUSTs an Agent Card declaration that nothing implements #92

Activity

1. imran-siddique commented on Aug 10, 2026

   

   imran-siddique

   on Aug 10, 2026

   MemberAuthor

   More actions

   Decisions taken 2026-08-10, so this starts from a settled shape.

   Advertise the requirement in the card. The SDK's AgentExtension carries uri, description, required and a params Struct, so the profile declaration has somewhere to state what the callee demands of callers:

   extensions: [{
     uri: "https://agentrust-io.com/extensions/ca2a/v0.1",
     required: false,
     params: { require_caller_attestation: "any" }
   }]

   That closes the discovery gap this issue names. Today the only way for a caller to learn a callee requires attestation is to send a request and be refused, which wastes a round trip on a path that already does a handshake.

   Generate the card from PeerNode state, not from config. Chosen over operator-supplied so the card cannot claim a requirement the node does not enforce. require_caller_attestation and caller_verifier are already on the node after #90, so the value is there to read.

   required: false. The profile is an overlay and a non-cA2A peer must be able to ignore it. Declaring the extension required would break plain-A2A callers, which is the opposite of what this is for.

   What #95 already gives this

   The SDK bridge landed, and two pieces of it are directly reusable:

   • a2a.extensions.common.find_extension_by_uri(card, uri) — the client-side check "does this peer speak cA2A", so discovery needs no new parsing.
   • ca2a_runtime.transport.a2a_sdk.opted_in(header_values) — the A2A-Extensions header half of the opt-in.

   AgentCard.capabilities.extensions is the field to populate.

   Still to decide when this is picked up

   • Whether a peer card that does not declare the extension is a client-side refusal or a recorded warning. Per the pattern used everywhere else in this stack it should be recorded and configurable, defaulting to permissive, since most peers today have no card at all.
   • Whether the reference server publishes at /.well-known/agent-card.json itself or leaves card serving to the SDK and only supplies the AgentExtension to merge in. The second is less code and avoids two card implementations.

   Explicitly still out of scope, and worth its own issue once the card exists: verifying the card's signature and binding a delegation subject or an attestation measurement to it. transport.md claims the card is "the anchor the delegation credential's subject and the peer's attestation measurement are checked against" with the check "not yet wired", and that is a real design question that should not stall publishing a card.
2. imran-siddique commented on Aug 24, 2026

   

   imran-siddique

   on Aug 24, 2026

   MemberAuthor

   More actions

   Implemented on main

   The Agent Card declaration and discovery path landed in #130 and is on main at a921d15. Closing against the code rather than against the changelog entry.

   What exists now, in src/ca2a_runtime/transport/a2a_sdk.py:

   • agent_extension_for_node (line 113) derives the cA2A AgentExtension from a live PeerNode, carrying its require_caller_attestation value, with required=false.
   • merge_agent_card (line 131) contributes that declaration into a copy of an operator-owned card. It does not invent identity, interfaces, skills, a serving URL, or a signature, which was the right call: the card belongs to the operator, not to us.
   • inspect_agent_card (line 166) returns a recordable discovery result for a remote card. A missing or malformed declaration is a warning for deployment policy rather than an implicit trust decision.

   Verified locally on main today: tests/unit/test_a2a_sdk_bridge.py is 34 passed, and the full suite is 540 passed, 2 skipped. The tests use the real a2a-sdk protobuf models and assert that existing card fields and unrelated extensions survive the merge.

   So the specific gap this issue described is closed. An adopter can satisfy the profile's MUST using this runtime, and the reference server is no longer non-conforming by our own spec's wording.

   One thing this deliberately does not do, and it is worth stating so nobody reads more into the fix than is there: cA2A still does not serve a card at /.well-known/agent-card.json on the reference transport. That is correct, because the reference transport is explicitly not part of the profile and the card is the operator's to serve. Discovery in the other direction is covered by inspect_agent_card.
3. imran-siddique

   closed this as completedon Aug 24, 2026