---
name: a2a-agent-card
description: Publish an A2A Agent Card that accurately describes agent capabilities.
---

# A2A Agent Card

Use this skill when a CanAgentUse report flags `a2a-agent-card`. The goal is to implement the exact public signal the scanner evaluates, not to perform a broad redesign. Treat the report evidence as the failing test case and make the smallest production-quality change that turns that evidence into a pass.

## What This Check Evaluates

This check validates A2A Agent Card discovery across current and legacy A2A paths. The current canonical discovery path is `/.well-known/agent-card.json`. Legacy A2A v0.1 and v0.2 used `/.well-known/agent.json`; this check treats that file only as legacy A2A Agent Card evidence, not as an AWP manifest.

## Pass Criteria

- an A2A Agent Card is found at a recognized current or legacy A2A discovery path.

## Failure And Warning Signals

**Failures usually mean:**

- a published candidate is not parseable JSON.
- the root document is not an object.
- the document is not classifiable as an A2A Agent Card.
- required fields for the detected version are missing or invalid.
- required endpoint/interface URLs are missing or invalid.
- public non-local endpoint/interface URLs use non-HTTPS schemes.
- `capabilities` is missing or not an object.
- `skills` is missing, empty, or not an array.

**Warnings usually mean:**

- no A2A card is found.
- only a legacy or fallback path is found.
- a current-version card is served from the legacy `/.well-known/agent.json` path.
- a legacy-version card is served from the current `/.well-known/agent-card.json` path.
- JSON is parseable but served with a generic or incorrect content type.
- optional provider, documentation, icon, examples, signatures, or cache metadata is absent.
- v0.1 cards omit input/output modes and rely on defaults.
- legacy and current security field names are mixed.

## Implementation Workflow

1. Start from the failed CanAgentUse evidence: URL, status code, content type, parsed fields, and failed criterion ID.
2. Locate the route, static asset, metadata generator, schema component, server config, or API endpoint that owns that public signal.
3. Implement the missing or malformed signal with real production values. Keep it same-origin unless the check explicitly supports external URLs.
4. Validate locally with direct HTTP requests, JSON/XML parsing, schema validation, or header inspection before relying on a full rescan.
5. Re-run the scan and compare the new evidence with the original failed criterion.

## Fix The Reported Criterion

- **A2A Agent Card is missing or discovered at a non-canonical path** (warning): Publish the current A2A Agent Card at `/.well-known/agent-card.json`. Keep legacy or fallback paths only as synchronized compatibility copies.
- **A2A Agent Card version cannot be classified cleanly** (fail): Declare a supported A2A version shape consistently. Use `protocolVersion` for legacy versions or `supportedInterfaces` for current cards, and remove fields from unrelated protocols.
- **A2A Agent Card shape is invalid for its version** (fail): Add the version-required fields: name, description, version, capabilities, skills, modes, URL or supported interfaces as required by the detected A2A version. Fix invalid skill entries.
- **A2A Agent Card HTTP delivery is not standards-aligned** (warning): Serve the card as JSON over HTTPS from the canonical path with stable cache headers. Avoid HTML fallback pages and non-JSON content types.
- **A2A Agent Card exposes unsafe public metadata** (fail): Remove secrets, tokens, private endpoints, and user/session-specific values from the public card. Keep security declarations structurally consistent with the detected A2A version.
- **Advertised same-origin A2A endpoint did not answer a safe probe** (fail): Make the advertised same-origin endpoint answer a bounded A2A probe, or require authentication with a clear challenge instead of returning unrelated HTML or generic errors.

## Implementation Pattern

- Publish machine-readable metadata at the well-known or documented discovery path.
- Include clear names, descriptions, versions, endpoint URLs, auth requirements, and capability boundaries.
- Make every advertised URL resolvable and every advertised action actually supported.
- Document dangerous, paid, authenticated, or state-changing actions explicitly.

## Minimal Example

```json
{
  "name": "Example",
  "description": "Describe the capability in agent-usable language",
  "url": "https://example.com/",
  "version": "1.0.0"
}
```

## Validate Before Rescanning

Validate through the CanAgentUse MCP server when the agent can use MCP tools:

1. Connect to the hosted Streamable HTTP MCP endpoint:

   ```text
   https://canagentuse.com/api/mcp
   ```

   This endpoint uses MCP Streamable HTTP. Configure it in the agent's MCP client as an HTTP/streamable HTTP server.

2. For stdio-based MCP clients, install and run the npm package:

   ```bash
   npx -y @canagentuse/mcp
   ```

3. Use the MCP tools to verify the specific fix.

   - Run `scan_website` with the public production or preview URL.
   - Use `list_checks` to confirm the check id and public docs URL.
   - Use `get_fix_guidance` with `a2a-agent-card` if the scan still reports a failure or warning.
   - Use `get_skill` with `a2a-agent-card` to reload this skill after updates.
   - Compare the new scan evidence for `a2a-agent-card` with the original failed criterion.

Validate through HTTP by creating and reading a hosted scan when MCP is unavailable:

```bash
SCAN_ID=$(curl -sS -X POST https://canagentuse.com/api/scans \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://YOUR-SITE.com"}' | jq -r '.scanId // .id')

curl -sS "https://canagentuse.com/api/scans/$SCAN_ID/result" | jq .
```

After deployment, re-run the same check and verify the report evidence now satisfies the pass criteria.

## Common Mistakes To Avoid

- Do not ship sample domains, placeholder names, fake dates, fake prices, fake reviews, or unsupported capabilities.
- Do not fix a scanner warning by hiding the signal; make the public evidence accurate and parseable.
- Do not change unrelated SEO, auth, security, or commerce behavior just to satisfy this one check.

## Public Check Documentation

- https://canagentuse.com/suites/2026.06.10/checks/a2a-agent-card/1.0.0