Skip to content

[FEATURE] Support registering and retrieving the full A2A AgentCard for registered A2A agents #7600

Description

@epostea

Existing issue check

  • I searched the existing issues for this capability

Parent Epic (optional)

Parent Epic:

Problem statement

ContextForge's A2A agent registry cannot store or return an A2A AgentCard. POST /a2a only accepts name, description, endpoint_url, agent_type, protocol_version, capabilities, config, auth, tags and visibility. There is nowhere to put skills, input/output modes, security schemes and the other card fields.

Orchestrator agents use the registry to discover agents and decide which one can handle a request. They need each agent's card, mainly its skills (name, description, tags, examples), and a name and one-line description are not enough. In Instana, our Coordinator agent routes user queries by matching them against each registered agent's skills.

Today the public agent endpoints return only the registered fields, with no card. A consumer has to fetch every agent's /.well-known/agent-card.json itself, which adds one request per agent and slows down discovery as the number of agents grows.

Proposed solution

Let an A2A agent be registered together with its AgentCard, and let consumers read the card back through the existing agent APIs.

1. Get the card into the registry. Either of these would work for us:

  • a. Extend the registration API. POST /a2a (and the update call) accept an optional agent_card, following the A2A AgentCard specification.
  • b. Import the card from the agent. The gateway fetches <agent url>/.well-known/agent-card.json when the agent is registered, and can re-fetch it on demand to refresh it.

2. Return the card from the public API. The get-agent and list-agents APIs return the agent details plus its card, so a consumer can discover agents and their skills with one call.

The new field is optional, so agents registered without a card keep working as they do today.

Story breakdown (optional)

Acceptance criteria

  • An A2A agent can be registered with its AgentCard (supplied directly or imported from the agent's well-known URL)
  • The get-agent and list-agents APIs return the agent details together with the card
  • Agents registered without a card keep working (backward compatible)

MCP standards check (optional)

This feature concerns the A2A protocol, not MCP. The new field is optional and additive.

Alternatives considered (optional)

  • Nest skills in capabilities. capabilities is a free-form dict, so skills can be put there today. It isn't spec-compliant, it doesn't round-trip as an AgentCard, and it covers neither I/O modes nor security schemes.
  • Have consumers fetch each agent's well-known card directly. This bypasses the registry and requires every consumer to have network access and credentials for every agent.

Out of scope (optional)

Additional context (optional)

Activity

  1. added theissue type on Nov 18, 2026
  2. marekdano commented on Nov 18, 2026

    @marekdano
    Collaborator

    Here is the update at the AI gateway:

    Done

    • Registration with a card. POST /a2a accepts card_url. The gateway fetches the card before it writes anything. It tries /.well-known/agent-card.json, then /.well-known/agent.json. It stores the card as fetched, with source_url, etag, max_age, detected_version and a version number (feat(a2a): store the Agent Card as fetched when registering an agent #7378). POST /a2a/fetch-card previews a card before you register (feat(a2a): add POST /a2a/fetch-card to read an Agent Card before registration #7377).
    • Credentials. The gateway sends basic, bearer and custom-header credentials to the card URL only when it shares an origin with endpoint_url.
    • Full card read. GET /a2a/{agent_id}/stored-card returns the card exactly as fetched.
    • Skills in the agent APIs. skills is a first-class field on POST /a2a and PUT /a2a/{agent_id}. GET /a2a, GET /a2a/{agent_id} and GET /a2a/{agent_id}/card return it. Agents without skills fall back to capabilities.skills.
    • Backward compatibility. card_url and skills are optional. Agents registered without them behave as before.

    Decision

    • The gateway does not accept a card that the client supplies (option 1a). It fetches the card itself (option 1b).

    Open

    • skills does not come from the fetched card. POST /a2a stores the card in a separate row and fills the agent's skills only from the request body. GET /a2a, GET /a2a/{agent_id} and GET /a2a/{agent_id}/card read that field, so a request with card_url and no skills returns no skills from any of them. Only GET /a2a/{agent_id}/stored-card returns the skills of the fetched card. The web UI works around this because POST /a2a/fetch-card returns suggested fields, including skills, and the form sends them with the registration.
    • GET /a2a and GET /a2a/{agent_id} do not return the full card. Input and output modes and security schemes need one stored-card call per agent.
    • card_url is not on the update schema. An existing agent cannot attach or refresh a card. On-demand re-fetch is not implemented yet.
  3. a-effort commented on Nov 19, 2026

    @a-effort
    Collaborator

    @epostea , +1 re Marek's summary.

    Small correction to the problem statement about input / output modes and security schemes:
    Modes live in capabilities as defaultInputModes and defaultOutputModes, and security schemes are derived from the agent's auth config. The gap is only that GET /a2a and GET /a2a/{agent_id} return no card.

  4. epostea commented on Nov 19, 2026

    @epostea
    Author

    Thanks for the update. Option 1b (the gateway fetches the card itself) works for us.

    skills on GET /a2a and GET /a2a/{agent_id} is what our coordinator needs to route a query to the right agent. We read the agent list on every query, so returning skills there means one call, not one per agent.

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

Metadata

Metadata

Labels

a2aSupport for A2A protocoltriageIssues / Features awaiting triage

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions