You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[FEATURE] Support registering and retrieving the full A2A AgentCard for registered A2A agents #7600
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.
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.
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.
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.
Activity
marekdano commentedon Nov 18, 2026
Here is the update at the AI gateway:
Done
POST /a2aacceptscard_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, withsource_url,etag,max_age,detected_versionand a version number (feat(a2a): store the Agent Card as fetched when registering an agent #7378).POST /a2a/fetch-cardpreviews a card before you register (feat(a2a): add POST /a2a/fetch-card to read an Agent Card before registration #7377).endpoint_url.GET /a2a/{agent_id}/stored-cardreturns the card exactly as fetched.skillsis a first-class field onPOST /a2aandPUT /a2a/{agent_id}.GET /a2a,GET /a2a/{agent_id}andGET /a2a/{agent_id}/cardreturn it. Agents withoutskillsfall back tocapabilities.skills.card_urlandskillsare optional. Agents registered without them behave as before.Decision
Open
skillsdoes not come from the fetched card.POST /a2astores the card in a separate row and fills the agent'sskillsonly from the request body.GET /a2a,GET /a2a/{agent_id}andGET /a2a/{agent_id}/cardread that field, so a request withcard_urland noskillsreturns no skills from any of them. OnlyGET /a2a/{agent_id}/stored-cardreturns the skills of the fetched card. The web UI works around this becausePOST /a2a/fetch-cardreturns suggested fields, includingskills, and the form sends them with the registration.GET /a2aandGET /a2a/{agent_id}do not return the full card. Input and output modes and security schemes need onestored-cardcall per agent.card_urlis not on the update schema. An existing agent cannot attach or refresh a card. On-demand re-fetch is not implemented yet.a-effort commentedon Nov 19, 2026
@epostea , +1 re Marek's summary.
Small correction to the problem statement about input / output modes and security schemes:
Modes live in
capabilitiesasdefaultInputModesanddefaultOutputModes, and security schemes are derived from the agent's auth config. The gap is only thatGET /a2aandGET /a2a/{agent_id}return no card.epostea commentedon Nov 19, 2026
Thanks for the update. Option 1b (the gateway fetches the card itself) works for us.
skillsonGET /a2aandGET /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 returningskillsthere means one call, not one per agent.