Skip to content

[FEATURE]: Re-fetch a registered agent's Agent Card #7540

Description

@a-effort

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. Any headers from the caller apply only to this request.
  • The stored card's source_url, with its ETag in If-None-Match.
  • The URLs that build_candidate_urls derives from endpoint_url.

Notes:

  • Send the agent's credential only when source_url matches the scheme, host, and port of endpoint_url. Check source_url against 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.create can fetch a card.
  • Users with a2a.update can 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_url refused 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.

Depends on: #7378. Related: #7025, #4734, #7023.

Activity

  1. added
    enhancementNew feature or request
    triageIssues / Features awaiting triage
    agentsAgent Samples
    a2aSupport for A2A protocol
    apiREST API Related item
    SHOULDP2: Important but not vital; high-value items that are not crucial for the immediate release
    ui-rewriteTasks for the isolated ui rewrite feature branch
    2.0CF1.5 with the bolt on external data plane + Redis as a communication channel
    on Nov 14, 2026
  2. added theissue type on Nov 14, 2026
  3. added
    1.1-Phase-2Phase 2 Protocol Matching in 1.1 Delivery. No inter protocol connection.
    and removed
    2.0CF1.5 with the bolt on external data plane + Redis as a communication channel
    on Nov 18, 2026
  4. self-assigned this
    on Nov 19, 2026
  5. a-effort commented on Nov 19, 2026

    @a-effort
    CollaboratorAuthor

    Points that need an update:

    • feat(a2a): fetch and store the authenticated extended Agent Card #7533 added the extended card: _store_agent_card() writes a public row at latest+1 and an extended row at latest+2. GET /a2a/{id}/stored-card/extended requires a2a.update plus ownership (_require_manageable_a2a_agent) and writes an audit entry. A refresh re-fetches with the agent's credential and can store extended content, so a2a.create is not enough. Require a2a.update with the ownership check, and state how the refresh handles the extended card.
    • The permissions conflict: proposed work asks for a2a.create, while the acceptance criteria give fetch a2a.create and refresh a2a.update.
    • token_scoping.py:193-213 has no POST rule for /a2a/{id}/card: scoped tokens are denied by default until a rule is added in the correct position.
    • If-None-Match does not work yet: fetch_agent_card() builds a card only from a 200 response. On a 304, document stays None, the search moves to the next candidate, and the call returns no_card. The criterion "an unchanged card adds no version" requires a change in a2a_card_import.
    • No check is recorded: A2AAgentCard stores fetched_at only on version rows. Recording a no-change check needs either a fetched_at update on the current row or a new column and migration.
    • GET /a2a/{id}/card returns the card the gateway builds (main.py:4966), not the stored card: POST on that path would mean something different. POST /a2a/{id}/stored-card matches the existing stored-card reads.
    • No A2A rate-limit tier exists: config.py defines 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 .json source_url unchanged, same_origin() covers the cross-origin credential rule, and _get_json() re-checks SSRF through resolve_pinned_target on every request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

1.1-Phase-2Phase 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 releasea2aSupport for A2A protocolagentsAgent SamplesapiREST API Related itemenhancementNew feature or requesttriageIssues / Features awaiting triageui-rewriteTasks for the isolated ui rewrite feature branch

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions