---
title: A2A agent card generator — build a spec-valid a2a.proto v1.0.0 card
description: "Free A2A agent card generator: declare your agent's interfaces, skills, and capabilities, valid against a2a.proto v1.0.0 by construction, with no SDK-connectable-transport gotchas."
last_updated: 2026-07-17
canonical_url: https://agent-ready.dev/agent-card-generator
---

# A2A agent card generator

> Free A2A agent card generator: declare your agent's interfaces, skills, and capabilities, valid against a2a.proto v1.0.0 by construction, with no SDK-connectable-transport gotchas.

## What it does

The A2A agent card is the JSON document an agent publishes at `/.well-known/agent-card.json` so other agents can discover it and call it. Pick a starting draft, add supported interfaces (JSONRPC, GRPC, or HTTP+JSON) and skills, toggle capabilities (streaming, pushNotifications, stateTransitionHistory), and the generator emits a card carrying the eight required top-level fields per a2a.proto v1.0.0. Generation runs entirely in your browser — no network call and no broken rows.

## Why generate instead of hand-write

A card whose `supportedInterfaces` is empty fails C5 outright, and C5 surfaces the card as broken. A half-typed interface row (blank url) or a skill missing id/name/description would be worse than omitting it. So the generator drops incomplete rows rather than serialising them: the emitted document always carries name, description, version, capabilities, supportedInterfaces, defaultInputModes, defaultOutputModes, and skills — the exact shape C5 requires.

## The eight required fields (a2a.proto v1.0.0)

- `name`, `description`, `version` — strings
- `capabilities` — an object; `streaming` and `pushNotifications` are booleans, `stateTransitionHistory` is optional
- `supportedInterfaces` — a non-empty array; each entry needs `url` (absolute http(s)), `protocolBinding` (JSONRPC, GRPC, or HTTP+JSON), and `protocolVersion`
- `defaultInputModes` / `defaultOutputModes` — MIME-type arrays; default to `application/json`
- `skills` — each entry needs `id`, `name`, `description`; `tags` is an array of strings

## The superset transport fields

a2a.proto v1.0.0 also defines a mainline transport superset — a top-level `url`, `preferredTransport`, and `protocolVersion` pointing at the agent's primary callable endpoint. They make the card both discoverable and callable. This generator fills them from the first SDK-connectable interface (JSONRPC/GRPC), falling back to the first interface, and omits 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 (registries like a2aregistry.org can list it) but an SDK client cannot open a session to it. If every interface is HTTP+JSON, the generator warns you to add a JSONRPC or GRPC interface so agents can actually dial the endpoint.

## Programmatic use

```bash
curl -X POST https://agent-ready.dev/api/v1/generate/agent-card \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "description": "Describe what your agent does for AI clients.",
    "version": "1.0.0",
    "capabilities": { "streaming": false, "pushNotifications": false },
    "interfaces": [
      { "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.", "tags": "example" }
    ]
  }'
```

Returns the generated document (`cardJson`, `doc`) and draft-level `warnings` (no interfaces, no skills, no SDK-connectable transport, invalid url). No authentication required.

## 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.

## The A2A agent card toolchain

- Generate: [A2A agent card generator](https://agent-ready.dev/agent-card-generator)
- Validate: [A2A agent card validator](https://agent-ready.dev/agent-card-validator)
- Scan: [Agent readability score](https://agent-ready.dev/agent-readability-score)

---

Generate your A2A agent card on the web: <https://agent-ready.dev/agent-card-generator>

## Sitemap

See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.