Agent Card

/.well-known/agent-card.json

The Agent Card is the primary A2A discovery mechanism. Any calling agent or directory fetches /.well-known/agent-card.json to learn what the agent does, how to call it, what auth it requires, and what output formats it supports.

Complete Example

/.well-known/agent-card.json

http

// /.well-known/agent-card.json (A2A v1.0)
{
  "name": "ResearchAgent",
  "description": "Searches the web and produces structured research summaries. Supports streaming for long tasks.",
  "url": "https://agent.example.com/a2a",
  "iconUrl": "https://agent.example.com/icon.png",
  "version": "1.0.2",

  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },

  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text", "data"],

  "skills": [
    {
      "id": "web-research",
      "name": "Web Research",
      "description": "Search the web and return a structured summary with sources. Provide a research question.",
      "tags": ["research", "web", "summarization"],
      "examples": ["Research the current state of quantum computing"],
      "inputModes": ["text"],
      "outputModes": ["text"]
    },
    {
      "id": "academic-search",
      "name": "Academic Paper Search",
      "description": "Search arXiv and Semantic Scholar for papers on a topic. Returns citation data.",
      "tags": ["research", "academic", "citations"],
      "inputModes": ["text"],
      "outputModes": ["text", "data"]
    }
  ],

  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  },

  "security": [{"bearerAuth": []}]
}

Fields

Field	Required	Description
`name`	Required	Human-readable agent name. Shown in directories and calling agent UIs.
`description`	Required	What the agent does. Calling agents use this to decide whether to delegate tasks.
`url`	Required	JSON-RPC 2.0 endpoint. Calling agents POST tasks/send requests here.
`version`	Optional	Semantic version of the agent.
`iconUrl`	Optional	URL to an icon image for directory listings.
`capabilities`	Optional	Declared features: streaming (SSE), pushNotifications (webhook), stateTransitionHistory.
`defaultInputModes`	Optional	Content types accepted: text, data, file. Defaults to [text].
`defaultOutputModes`	Optional	Content types produced: text, data, file. Defaults to [text].
`skills`	Optional	Specific capabilities the agent offers. Each has id, name, description, tags, examples, I/O modes.
`securitySchemes`	Optional	OpenAPI-style security scheme definitions (Bearer, API key, OAuth 2.0).
`security`	Optional	Which securitySchemes apply. Empty array = no authentication required.

Agent Card

Complete Example

Fields

See Also