Agent Ready
a2a.proto v1.0.0

A2A agent card generator

An agent card is how other agents discover and call yours. Build one that matches a2a.proto v1.0.0 by construction — no broken rows, no missing fields.

Identity
Capabilities
Supported interfaces

Each interface is one endpoint an A2A client can call. The url must be an absolute http(s) URL; the protocolBinding is one of JSONRPC, GRPC, or HTTP+JSON. A2A SDK clients can only dial JSONRPC or GRPC, so including one makes the card callable, not merely discoverable.

Default input / output modes

Comma-separated MIME types. Left blank, the card defaults to application/json.

Skills

Callable capabilities the agent exposes. Each needs an id, name, and description; tags are comma-separated.

Your agent-card.json
{
  "name": "My Agent",
  "description": "Describe what your agent does for AI clients.",
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "supportedInterfaces": [
    {
      "url": "https://example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "defaultInputModes": [
    "application/json",
    "text/plain"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "example-skill",
      "name": "Example Skill",
      "description": "What this skill does when an agent invokes it.",
      "tags": [
        "example"
      ],
      "inputModes": [
        "application/json",
        "text/plain"
      ],
      "outputModes": [
        "application/json"
      ]
    }
  ],
  "url": "https://example.com/a2a",
  "preferredTransport": "JSONRPC",
  "protocolVersion": "1.0"
}

Next steps

Save this as /.well-known/agent-card.json (served as application/a2a+json, or application/json), then validate it — and run a full agent-readability scan.

Last updated

What an A2A agent card is — and where it lives

The A2A agent card is a JSON document published at /.well-known/agent-card.json that lets agents discover each other’s capabilities without prior configuration. It advertises the agent’s name, version, supported interfaces (JSON-RPC, gRPC, or HTTP+JSON), input/output modalities, and callable skills. The /.well-known/ path is reserved by RFC 8615 for machine-readable discovery, so a client knows exactly where to look.

The required fields and the supportedInterfaces / skills shape

Per a2a.proto v1.0.0, eight top-level fields are required: name, description, version, capabilities, supportedInterfaces, defaultInputModes, defaultOutputModes, and skills. Empty arrays and objects are allowed but the fields must exist. The scanner’s C5 check fails a card whose supportedInterfaces is empty — so this generator never emits an incomplete interface row (a blank-url entry is dropped rather than serialised broken).

  • supportedInterfaces[] — each entry needs url, protocolBinding (JSONRPC, GRPC, or HTTP+JSON), and protocolVersion.
  • skills[] — each entry needs id, name, and description; tags is an array of strings.

Why the superset transport fields matter — discoverable vs callable

Beyond the eight required fields, a2a.proto v1.0.0 defines a mainline transport superset: a top-level url, preferredTransport, and protocolVersion that point at the agent’s primary callable endpoint. They make the card both discoverable and callable — the url tells a client where to connect without depending on the card’s own origin. This generator fills them from the first SDK-connectable interface you declare, falling back to the first interface when no JSONRPC/GRPC entries exist, and omitting them entirely only when no interface survives.

The SDK-connectable-transport gotcha

The mainline A2A SDK connects over JSONRPC or GRPC, not plain HTTP+JSON. A card that advertises only HTTP+JSON is discoverable — a registry like a2aregistry.org can list it — but an SDK client cannot open a session to it. If every interface you declare is HTTP+JSON, the generator warns you to add a JSONRPC or GRPC interface (or set a preferredTransport) so agents can actually dial the endpoint. HTTP+JSON is spec-valid, but it is discoverable-only unless you also publish a connectable transport.

Frequently asked questions

What is an A2A agent card?
An A2A agent card is a JSON document published at /.well-known/agent-card.json that declares an agent's name, version, supported interfaces (JSONRPC, GRPC, or HTTP+JSON), input/output modalities, and callable skills. Per a2a.proto v1.0.0 it lets other agents (travel planners, orchestrators, concierges) discover what your agent can do and how to call it.
Which fields are required in an A2A agent card?
Per a2a.proto v1.0.0, eight top-level fields are required: name, description, version, capabilities, supportedInterfaces, defaultInputModes, defaultOutputModes, and skills. Each supportedInterfaces entry also needs url, protocolBinding (JSONRPC, GRPC, or HTTP+JSON), and protocolVersion. Empty arrays and objects are allowed but the fields must exist — C5 fails a card with an empty supportedInterfaces, so this generator refuses to emit a broken row.
Where should I publish my A2A agent card?
Serve it at /.well-known/agent-card.json on your agent's domain. Content-Type application/a2a+json is preferred; application/json is also accepted. The /.well-known/ path is reserved by RFC 8615 for machine-readable discovery.
What do the superset url and preferredTransport fields do?
Beyond the eight required fields, a2a.proto v1.0.0 defines a mainline transport superset: a top-level url, preferredTransport, and protocolVersion that point at the agent's primary callable endpoint. They make the card both discoverable and callable — the url tells a client where to connect without depending on the card's own origin. This generator fills them from the first SDK-connectable interface you declare.
Why can't HTTP+JSON-only cards be dialed by A2A SDK clients?
The mainline A2A SDK connects over JSONRPC or GRPC, not plain HTTP+JSON. A card that advertises only HTTP+JSON is discoverable — a registry like a2aregistry.org can list it — but an SDK client cannot open a session to it. If every interface you declare is HTTP+JSON, the generator warns you to add a JSONRPC or GRPC interface (or set a preferredTransport) so agents can actually call the endpoint.
How is the generated card kept valid by construction?
The generator only emits the fields a2a.proto v1.0.0 defines, and it drops incomplete rows rather than serialising them — a supportedInterfaces entry with no url, or a skill missing id/name/description, is omitted instead of written as broken. The output therefore always carries the eight required top-level fields, and once you provide at least one interface with a url it is valid by construction against the field-shape checks. The one case it can still fail is an empty supportedInterfaces (when you provide no interface with a url at all) — the generator flags that with a no-interfaces warning telling you the card would be rejected by C5.

Related tools