Repository navigation
Labels
1.1-Phase-2Phase 2 Protocol Matching in 1.1 Delivery. No inter protocol connection.Phase 2 Protocol Matching in 1.1 Delivery. No inter protocol connection.SHOULDP2: Important but not vital; high-value items that are not crucial for the immediate releaseP2: Important but not vital; high-value items that are not crucial for the immediate releasea2aSupport for A2A protocolSupport for A2A protocolagentsAgent SamplesAgent SamplesapiREST API Related itemREST API Related itemenhancementNew feature or requestNew feature or requesttriageIssues / Features awaiting triageIssues / Features awaiting triageui-rewriteTasks for the isolated ui rewrite feature branchTasks for the isolated ui rewrite feature branch
Description
Summary
#7378 stores each agent's card with source_url, ETag, max-age, and fetch time, versioned per agent. This route attaches the agent’s first card, which is fetched only at registration (later changes are missed). #7025 needs a route to refresh it.
Proposed work
Add POST /v1/a2a/{agent_id}/card. Require a2a.create (the permission fetch-card requires) because the caller can supply an URL to fetch.
The route selects the first available URL:
base_url, if the caller provides it. Anyheadersfrom the caller apply only to this request.- The stored card's
source_url, with its ETag inIf-None-Match. - The URLs that
build_candidate_urlsderives fromendpoint_url.
Notes:
- Send the agent's credential only when
source_urlmatches the scheme, host, and port ofendpoint_url. Checksource_urlagainst the SSRF policy on each call. Do not write to the agent row. - Add a rate limit or minimum interval per agent, since each call makes an outbound request. [API][UI-REWRITE]: On-demand health re-check for a single MCP server #6842 is a similar on-demand check.
Out of scope:
Scheduled refresh, UI for card differences (#7025), applying a card version to the agent row.
Acceptance criteria
- Users with
a2a.createcan fetch a card. - Users with
a2a.updatecan refresh a card. - An unchanged card adds no version and records the check.
- A changed card is stored as the next version and becomes current.
- The response lists the changed top-level keys.
- The credential is not sent across origins.
- A
source_urlrefused by the SSRF policy stores nothing. - An agent with no stored card gets its first version from this route.
- The agent row is unchanged.
- A failed request leaves the stored card unchanged.
Metadata
Metadata
Assignees
Labels
1.1-Phase-2Phase 2 Protocol Matching in 1.1 Delivery. No inter protocol connection.Phase 2 Protocol Matching in 1.1 Delivery. No inter protocol connection.SHOULDP2: Important but not vital; high-value items that are not crucial for the immediate releaseP2: Important but not vital; high-value items that are not crucial for the immediate releasea2aSupport for A2A protocolSupport for A2A protocolagentsAgent SamplesAgent SamplesapiREST API Related itemREST API Related itemenhancementNew feature or requestNew feature or requesttriageIssues / Features awaiting triageIssues / Features awaiting triageui-rewriteTasks for the isolated ui rewrite feature branchTasks for the isolated ui rewrite feature branch
Activity
a-effort commentedon Nov 19, 2026
Points that need an update:
_store_agent_card()writes a public row at latest+1 and an extended row at latest+2.GET /a2a/{id}/stored-card/extendedrequiresa2a.updateplus ownership (_require_manageable_a2a_agent) and writes an audit entry. A refresh re-fetches with the agent's credential and can store extended content, soa2a.createis not enough. Requirea2a.updatewith the ownership check, and state how the refresh handles the extended card.a2a.create, while the acceptance criteria give fetcha2a.createand refresha2a.update.token_scoping.py:193-213has no POST rule for/a2a/{id}/card: scoped tokens are denied by default until a rule is added in the correct position.fetch_agent_card()builds a card only from a 200 response. On a 304,documentstays None, the search moves to the next candidate, and the call returnsno_card. The criterion "an unchanged card adds no version" requires a change ina2a_card_import.A2AAgentCardstoresfetched_atonly on version rows. Recording a no-change check needs either afetched_atupdate on the current row or a new column and migration.GET /a2a/{id}/cardreturns the card the gateway builds (main.py:4966), not the stored card: POST on that path would mean something different.POST /a2a/{id}/stored-cardmatches the existing stored-card reads.config.pydefines only the global critical/high/medium/low tiers with no per-resource interval, so a per-agent limit is new work.Still correct:
build_candidate_urls()returns a.jsonsource_urlunchanged,same_origin()covers the cross-origin credential rule, and_get_json()re-checks SSRF throughresolve_pinned_targeton every request.