AgentCard Validation

Agent Explorer validates AgentCards against the A2A specification and reports three categories of findings: errors, warnings, and spec violations.

Validation Levels

Errors

Errors indicate invalid AgentCards that violate the spec:

• Missing required fields (name, url, version)
• Invalid field types
• Malformed JSON
• Empty or invalid skills array

Warnings

Warnings highlight potential issues:

• Missing recommended fields (description, skills)
• Empty capabilities object
• Missing input/output modes
• Deprecated fields

Spec violations (A2A 1.0)

When a card declares A2A 1.0, fields that the 1.0 spec requires but that are missing are shown as red Spec violations (A2A 1.0) findings, separate from ordinary warnings. These flag genuine spec non-compliance while still allowing you to connect to the agent.

Validation Process

When you create or refresh an agent:

1. Agent Explorer fetches the AgentCard from {base-url}/.well-known/agent-card.json
2. The JSON is parsed and validated against the A2A Zod schema
3. Errors and warnings are surfaced in the Agent Card tab
4. The AgentCard details are displayed in a structured view

Viewing Validation Results

On the agent's Agent Card tab:

1. Look for the validation status badge (green check or red error count)
2. Expand the validation details panel
3. Review any errors or warnings with descriptions

Protocol versions are normalized to Major.Minor for display, so the chat UI shows them as v1.0 or v0.3 regardless of the exact patch version declared in the AgentCard.

Common Issues

CORS Errors

If the AgentCard cannot be fetched, you may see a CORS error. Solutions:

• Ensure the agent allows cross-origin requests from your Agent Explorer origin
• Use the Proxy API (/api/proxy) to route the request server-side

Invalid JSON

Check for syntax errors, ensure UTF-8 encoding, and validate with a JSON linter.

Missing Capabilities

While not an error, missing capabilities mean streaming, push notifications, and state history won't be available.