AgentCard fields

The planner is about to delegate its first test run to test-runner, an agent it knows only as localhost:41241. Its first request is a GET for one JSON document.

When you finish this section, you can read any agent card field by field and say which fields a valid card must carry.

The card and its REQUIRED fields

Agent card: a JSON metadata document that an A2A server publishes. It describes the identity, capabilities, skills, service endpoint, and authentication requirements of the server. Every A2A server must make an Agent Card available.

The proto message AgentCard has 14 fields, and eight of them are REQUIRED: name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes, and skills. A REQUIRED field must be present and set in every valid message.

Four of those fields are lists, and a required list must contain at least one element. The signing example in §8.4.1 keeps an empty skills list all the same (conflict D19, open as issue #2122), and real cards follow §5.7.

Figure 2.1 sorts the whole test-runner card into four groups: who it is, where to reach it, what it demands, and what it offers. Of the identity fields, version is the agent's own release, and extended cards and signatures covers signatures.

What it offers: skills and modes

Skill: one entry in skills, a unit of work the agent says it can do. Each skill needs an id, a name, a description, and at least one entry in tags. The optional examples hold sample prompts, and a skill can carry its own modes and securityRequirements.

  "skills": [
    {
      "id": "run-tests",
      "name": "Run tests",
      "description": "Run the test suite of a repository at one commit and report each failure with its log.",
      "tags": [
        "ci",
        "tests"
      ],
      "examples": [
        "Run the unit tests for payments-api at commit 9f3c2e1"
      ]
    }
  ]

No field of SendMessageRequest or Message names a skill, and the proto treats the list as mostly descriptive.

Mode: a media type that names content an agent accepts or produces, such as text/plain. The REQUIRED lists defaultInputModes and defaultOutputModes apply across all skills, and a skill overrides them with its own inputModes and outputModes. The code-reviewer card narrows the input of its review-diff skill to text/x-diff and text/plain.

Where to reach it: supportedInterfaces

Interface: one entry in supportedInterfaces, a URL with the binding and the protocol version spoken there. Its fields url, protocolBinding, and protocolVersion are REQUIRED, and tenant is optional. The order matters: the list is ordered, and the first entry is the preferred one.

  "supportedInterfaces": [
    {
      "url": "http://localhost:41241/a2a/jsonrpc",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    },
    {
      "url": "http://localhost:41241/a2a/rest",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],

The proto names three standard bindings: JSONRPC, GRPC, and HTTP+JSON. The field protocolVersion is the A2A version spoken at that URL, as Major.Minor, and the version and extension headers cover the matching A2A-Version header.

In production, each URL must be a valid absolute HTTPS URL, and the kit uses http://localhost on one machine. The spec does not say which form a GRPC entry takes, and the reference SDK's sample writes a plain host and port (conflict D34).

What it demands: capabilities and security

Capability: a flag in the REQUIRED capabilities object that switches on an optional part of the protocol: streaming, pushNotifications, or extendedAgentCard. An absent flag counts the same as false, and discovery lists the operations that each flag allows. The same object lists extensions by uri, and extensions covers that list.

The optional securitySchemes and securityRequirements say which credentials a call needs. The test-runner card sets neither, and security schemes reads the bearer scheme on the deployer card.

In 1.0, five top-level fields of the 0.3 card moved into supportedInterfaces and capabilities, and from 0.3 to 1.0 maps each one. The migration steps in §A.2.1 still use a card field protocolVersions, which the 1.0 proto lacks (conflict D8). PR #2165 fixed that on main after v1.0.1, not yet released. The sample card in §8.5 still uses security where the proto has securityRequirements (conflict D6). PR #2046 fixed that sample on main, not yet released.