Agent Card Specification

Complete schema and field reference for Agent Cards following the Agent-to-Agent (A2A) protocol.

Overview

Agent Cards are JSON documents that describe an AI agent’s capabilities, enabling discovery and invocation by other agents.

Specification Version: A2A 1.0
Content Type: application/json
File Extension: .json

Complete Schema

{
  "name": "string (required)",
  "version": "string (required, semver)",
  "description": "string (required, min 200 chars)",
  "author": "string (optional)",
  "license": "string (optional)",
  "homepage": "string (optional, URL)",
  "repository": "string (optional, URL)",
  
  "skills": [
    {
      "name": "string (required)",
      "description": "string (required)",
      "parameters": "object (optional)",
      "returns": "string (optional)",
      "examples": "array (optional)",
      "mcp_server": "string (optional)",
      "mcp_tool": "string (optional)"
    }
  ],
  
  "capabilities": {
    "languages": ["string"],
    "domains": ["string"],
    "input_modes": ["string"],
    "output_modes": ["string"],
    "streaming": "boolean",
    "async": "boolean",
    "state_management": "boolean",
    "rate_limit": "string"
  },
  
  "invocation": {
    "protocol": "string (required)",
    "endpoint": "string (required, URL)",
    "authentication": {
      "type": "string",
      "required": "boolean"
    },
    "method": "string",
    "format": "string"
  },
  
  "examples": [
    {
      "skill": "string (required)",
      "description": "string (optional)",
      "input": "object (required)",
      "output": "object (required)"
    }
  ],
  
  "metadata": {
    "created_at": "string (ISO 8601)",
    "updated_at": "string (ISO 8601)",
    "tags": ["string"],
    "categories": ["string"]
  }
}

Field Definitions

Basic Information

name

Type: string
Required: Yes
Pattern: ^[a-z0-9-]+$ (lowercase, numbers, hyphens)
Max Length: 50 characters

Agent identifier, must be unique within organization.

Examples:

"name": "weather-assistant"
"name": "customer-service-agent"
"name": "data-analyzer-v2"

version

Type: string
Required: Yes
Format: Semantic versioning (X.Y.Z)

Agent version following semver specification.

Examples:

"version": "1.0.0"
"version": "2.5.1"
"version": "0.1.0-beta"

description

Type: string
Required: Yes
Min Length: 200 characters
Max Length: 2000 characters

Comprehensive description of agent’s purpose and capabilities.

Example:

"description": "Intelligent weather assistant providing real-time weather data, forecasts, and historical weather information for cities worldwide. Supports multiple temperature units (celsius/fahrenheit) and provides detailed conditions including temperature, humidity, wind speed, and precipitation. Integrates with national weather services for accurate, up-to-date information."

author

Type: string
Required: No

Creator or organization name.

Example:

"author": "Acme Weather Corporation"

license

Type: string
Required: No
Common Values: Apache-2.0, MIT, BSD-3-Clause, GPL-3.0

Software license for the agent.

Example:

"license": "Apache-2.0"

homepage

Type: string (URL)
Required: No

Agent’s homepage or documentation site.

Example:

"homepage": "https://weather-assistant.example.com"

repository

Type: string (URL)
Required: No

Source code repository.

Example:

"repository": "https://github.com/example/weather-assistant"

Skills

Array of capabilities the agent provides.

skills[].name

Type: string
Required: Yes
Pattern: ^[a-z0-9_]+$ (snake_case)

Skill identifier.

Example:

"name": "get_weather"

skills[].description

Type: string
Required: Yes
Min Length: 50 characters

What the skill does.

Example:

"description": "Get current weather conditions including temperature, humidity, wind speed, and atmospheric pressure for any city worldwide"

skills[].parameters

Type: object
Required: No

Parameters the skill accepts.

Example:

"parameters": {
  "city": "string - City name",
  "units": "string - celsius or fahrenheit (optional)"
}

skills[].returns

Type: string
Required: No

Description of return value.

Example:

"returns": "Weather object with current conditions"

skills[].mcp_server

Type: string
Required: No

MCP server that implements this skill.

Example:

"mcp_server": "weather-api"

skills[].mcp_tool

Type: string
Required: No

Specific MCP tool name.

Example:

"mcp_tool": "get_current_weather"

Capabilities

Technical capabilities the agent supports.

capabilities.languages

Type: array<string>
Required: No

Supported natural languages (ISO 639-1 codes).

Example:

"languages": ["en", "es", "fr", "de", "ja"]

capabilities.domains

Type: array<string>
Required: No

Subject matter expertise areas.

Example:

"domains": ["weather", "meteorology", "climate"]

capabilities.input_modes

Type: array<string>
Required: No
Valid Values: text, voice, image, video, file

How agent accepts input.

Example:

"input_modes": ["text", "voice"]

capabilities.output_modes

Type: array<string>
Required: No
Valid Values: text, json, speech, image, video, file

How agent returns results.

Example:

"output_modes": ["text", "json", "speech"]

capabilities.streaming

Type: boolean
Required: No
Default: false

Whether agent supports streaming responses.

Example:

"streaming": true

capabilities.async

Type: boolean
Required: No
Default: false

Whether agent supports asynchronous operations.

Example:

"async": true

capabilities.state_management

Type: boolean
Required: No
Default: false

Whether agent maintains conversation state.

Example:

"state_management": true

capabilities.rate_limit

Type: string
Required: No

Usage rate limits.

Example:

"rate_limit": "100 requests per minute"

Invocation

How to call the agent.

invocation.protocol

Type: string
Required: Yes
Valid Values: mcp, rest, grpc, graphql, websocket

Communication protocol.

Example:

"protocol": "mcp"

invocation.endpoint

Type: string (URL)
Required: Yes

Agent’s API endpoint.

Example:

"endpoint": "https://api.example.com/agents/weather"

invocation.authentication.type

Type: string
Required: No
Valid Values: none, bearer, api_key, oauth2, basic, mtls

Authentication method.

Example:

"type": "bearer"

invocation.authentication.required

Type: boolean
Required: No
Default: false

Whether authentication is required.

Example:

"required": true

invocation.method

Type: string
Required: No
Default: POST

HTTP method (if applicable).

Example:

"method": "POST"

invocation.format

Type: string
Required: No
Valid Values: json-rpc, rest, graphql

Request/response format.

Example:

"format": "json-rpc"

Examples

Sample interactions demonstrating usage.

examples[].skill

Type: string
Required: Yes

Which skill the example demonstrates.

Example:

"skill": "get_weather"

examples[].description

Type: string
Required: No

What the example shows.

Example:

"description": "Get weather for San Francisco in Fahrenheit"

examples[].input

Type: object
Required: Yes

Example input parameters.

Example:

"input": {
  "city": "San Francisco",
  "units": "fahrenheit"
}

examples[].output

Type: object
Required: Yes

Expected output.

Example:

"output": {
  "city": "San Francisco",
  "temperature": 65,
  "conditions": "Partly cloudy"
}

Metadata

Additional information (optional).

metadata.created_at

Type: string (ISO 8601)

When agent card was created.

Example:

"created_at": "2026-01-01T00:00:00Z"

metadata.updated_at

Type: string (ISO 8601)

Last update timestamp.

Example:

"updated_at": "2026-01-28T12:00:00Z"

metadata.tags

Type: array<string>

Searchable keywords.

Example:

"tags": ["weather", "forecast", "real-time"]

metadata.categories

Type: array<string>

Classification categories.

Example:

"categories": ["Data", "API", "Weather"]

Complete Example

{
  "name": "weather-assistant",
  "version": "1.0.0",
  "description": "Intelligent weather assistant providing real-time weather data, forecasts, and historical weather information for cities worldwide. Supports multiple temperature units and provides detailed atmospheric conditions. Integrates with national weather services for accurate, up-to-date information with updates every 15 minutes.",
  "author": "Acme Weather Corp",
  "license": "Apache-2.0",
  "homepage": "https://weather-assistant.acme.com",
  "repository": "https://github.com/acme/weather-assistant",
  
  "skills": [
    {
      "name": "get_weather",
      "description": "Get current weather conditions including temperature, humidity, wind speed, precipitation, and atmospheric pressure for any city worldwide",
      "parameters": {
        "city": "string - City name (required)",
        "units": "string - celsius or fahrenheit (optional, default: celsius)"
      },
      "returns": "Weather object with current conditions",
      "mcp_server": "weather-api",
      "mcp_tool": "get_current_weather"
    },
    {
      "name": "get_forecast",
      "description": "Get multi-day weather forecast with daily highs, lows, precipitation chances, and general conditions",
      "parameters": {
        "city": "string - City name (required)",
        "days": "number - Forecast days 1-7 (optional, default: 3)"
      },
      "returns": "Array of daily forecast objects",
      "mcp_server": "weather-api",
      "mcp_tool": "get_forecast"
    }
  ],
  
  "capabilities": {
    "languages": ["en", "es", "fr"],
    "domains": ["weather", "meteorology", "climate"],
    "input_modes": ["text"],
    "output_modes": ["text", "json"],
    "streaming": false,
    "async": false,
    "state_management": false,
    "rate_limit": "100 requests per minute"
  },
  
  "invocation": {
    "protocol": "mcp",
    "endpoint": "https://api.acme.com/mcp/weather",
    "authentication": {
      "type": "bearer",
      "required": false
    },
    "method": "POST",
    "format": "json-rpc"
  },
  
  "examples": [
    {
      "skill": "get_weather",
      "description": "Get current weather for San Francisco",
      "input": {
        "city": "San Francisco",
        "units": "fahrenheit"
      },
      "output": {
        "city": "San Francisco",
        "temperature": 65,
        "units": "fahrenheit",
        "conditions": "Partly cloudy",
        "humidity": 72,
        "wind_speed": 12
      }
    },
    {
      "skill": "get_forecast",
      "description": "Get 5-day forecast for Tokyo",
      "input": {
        "city": "Tokyo",
        "days": 5
      },
      "output": {
        "city": "Tokyo",
        "forecast": [
          {"day": 1, "high": 25, "low": 18, "conditions": "Sunny"},
          {"day": 2, "high": 24, "low": 17, "conditions": "Partly cloudy"}
        ]
      }
    }
  ],
  
  "metadata": {
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-28T12:00:00Z",
    "tags": ["weather", "forecast", "real-time", "global"],
    "categories": ["Data", "API", "Weather Services"]
  }
}

Validation

Agent Cards must pass these validations:

Required Fields

name must be present and valid
version must follow semver
description must be ≥ 200 characters
At least one skill must be defined
invocation.protocol and invocation.endpoint required

Field Formats

URLs must be valid HTTP/HTTPS
Versions must be semver
Language codes must be ISO 639-1
Timestamps must be ISO 8601

Naming Conventions

Agent name: lowercase-with-hyphens
Skill names: snake_case
No special characters except hyphen/underscore

Discovery

Agent Cards can be discovered via:

Well-Known Endpoint

GET https://api.example.com/.well-known/agent-card.json

Returns the agent’s card.

Direct URL

https://agents.example.com/cards/weather-assistant.json

Agent Registry

Centralized directories:

Anypoint Exchange
Public agent marketplaces
Organization registries

Versioning

Follow semantic versioning:

Major (X.0.0): Breaking changes to skills or invocation
Minor (x.Y.0): New skills added, backward compatible
Patch (x.y.Z): Bug fixes, description updates

Next Steps

Agent Cards Concept - A2A protocol overview
Creating Agent Cards - Step-by-step guide
Agent Cards Feature - MA²D implementation

External Resources

A2A Protocol - Official A2A specification
JSON Schema - Schema validation
Semantic Versioning - Version guidelines

Specification Version: A2A 1.0
Last Updated: January 2026

MCP Methods