# Agent Card (A2A)
> How to create an A2A agent.json card: the missing file, invalid JSON, required fields, skills, protocol version, and optional fields.
Diese Prüfung trägt 3 % des Scores.
*Diese Leitfäden zur Behebung sind in englischer Sprache verfasst.*
## agent.json not found
Create a `/.well-known/agent.json` file. In Next.js, place it at `public/.well-known/agent.json`:
```
{
"protocolVersion": "0.2.0",
"name": "Your Site Name",
"description": "What your site does and what AI agents can find here.",
"url": "https://your-site.com",
"version": "1.0.0",
"provider": {
"organization": "Your Company",
"url": "https://your-site.com"
},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["application/json", "text/plain"],
"capabilities": {
"streaming": false,
"pushNotifications": false
},
"authentication": {
"schemes": ["none"]
},
"skills": [
{
"id": "main-feature",
"name": "Your Main Feature",
"description": "What this skill does.",
"tags": ["feature", "category"],
"examples": ["Example query 1", "Example query 2"]
}
],
"documentationUrl": "https://your-site.com/.well-known/openapi.json"
}
```
> **Generated for you**
>
> AX Rush writes this file from your own pages: scan your site, open Optimize, and copy the file it grounds on your templates.
---
## Wrong Content-Type
Serve `/.well-known/agent.json` with `Content-Type: application/json`. Some agents discard responses with the wrong MIME type before parsing.
```
# Nginx
location = /.well-known/agent.json {
default_type application/json;
}
# Express / custom server
res.setHeader('Content-Type', 'application/json; charset=utf-8');
```
---
## Invalid JSON
Your agent.json file exists but contains invalid JSON. Validate it with a JSON linter or `JSON.parse()` in your browser console.
---
## Required field missing
The A2A protocol requires these fields: `name`, `description`, and `url`. Add any that are missing to the root of your agent.json.
---
## url points to a different origin
The `url` field in your agent.json points to a different host than the audited site. Set it to the canonical origin of the site that hosts the agent card:
```
{
"url": "https://your-site.com",
"...": "..."
}
```
If the agent card describes a service hosted on a different subdomain, that subdomain should serve its own `/.well-known/agent.json`.
---
## url is not absolute
Use a fully qualified URL (`https://...`) for the `url` field. Relative paths or hostnames without scheme are ambiguous when the agent card is fetched outside the original page context.
---
## Empty skills array
Your agent.json has a `skills` array but it's empty. Add at least one skill describing what your site or agent can do:
```
"skills": [
{
"id": "data-lookup",
"name": "Data Lookup",
"description": "Look up specific information from our database.",
"tags": ["data", "search"],
"examples": ["Find user by email", "Search products"]
}
]
```
---
## Skills missing id or description
Every entry in the `skills` array needs both an `id` (so agents can address the skill programmatically) and a `description` (so they can decide whether to invoke it).
```
"skills": [
{
"id": "search-products",
"name": "Search products",
"description": "Search the catalog by name, category, or SKU and return matches with price and availability."
}
]
```
---
## No protocol version
Add `"protocolVersion": "0.2.0"` to declare which version of the A2A protocol your agent card follows. This helps AI agents parse your card correctly.
---
## Missing optional fields
The A2A protocol defines optional fields that improve discoverability:
- `capabilities`: what protocols you support (streaming, push notifications)
- `authentication`: auth requirements (none, API key, OAuth)
- `documentationUrl`: link to your OpenAPI spec or API docs
---
## The card is at the old path
A2A moved the card to `/.well-known/agent-card.json` in v0.3.0, and that is the path registered with IANA. A card at `/.well-known/agent.json` is found by this audit and not by a current client, which looks only at the registered one.
Serve it at the new path. Keep the old one as a redirect, or as a second copy, if anything already depends on it.
---
## A card shape from neither generation
A 1.0 card declares `supportedInterfaces[]`. A 0.3 card declares a top-level `url` and `protocolVersion`. Yours has neither, so there is no ruleset to validate it against.
Usually a hand-written card that predates both, or one built from a blog post. Rebuild it against the current specification.
---
## supportedInterfaces is empty
The array exists and lists nothing, so the card describes an agent with no address. Declare at least one:
```
"supportedInterfaces": [
{ "url": "https://example.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
]
```
---
## An interface missing a field
Every entry needs all three: `url`, `protocolBinding` and `protocolVersion`. Together they say where to connect and how to speak, and a client cannot infer either from the other.
---
## An unrecognised protocolBinding
A2A 1.0 defines three: `JSONRPC`, `GRPC` and `HTTP+JSON`. Anything else is skipped, and an interface that is skipped is an interface that is not there.
---
## The card uses authentication
Removed from the specification and replaced by `securitySchemes`, which carries the same information in the OpenAPI vocabulary clients already parse.
If your agent is open, the right move is to declare nothing. An empty `authentication` object says something about authentication rather than nothing, which is why the field went.
---
Markdown-Darstellung von https://axrush.com/guides/agent-card