Agent Cards (A2A)

Agent Cards are standardized specifications that define how AI agents discover, understand, and interact with each other using the Agent-to-Agent (A2A) protocol.

What are Agent Cards?

Agent Cards provide a machine-readable description of an AI agent’s capabilities, making it possible for agents to:

• Discover other agents and their skills
• Understand what capabilities are available
• Invoke other agents programmatically
• Collaborate to solve complex problems

Think of an Agent Card as a resume for AI agents - it describes what the agent can do, how to interact with it, and what to expect.

The A2A Protocol

The Agent-to-Agent (A2A) protocol is an emerging standard for agent interoperability:

Key Principles

1. Discoverability - Agents publish cards to be found
2. Self-Describing - Cards document capabilities clearly
3. Standard Format - JSON-based specification
4. Composability - Agents can combine skills

Agent Card Structure

An Agent Card consists of several key components:

Basic Information

{
  "name": "weather-assistant",
  "version": "1.0.0",
  "description": "AI assistant providing real-time weather data and forecasts",
  "author": "Acme Weather Corp",
  "license": "Apache-2.0"
}

Fields:

• name - Unique identifier for the agent
• version - Semantic versioning (e.g., 1.0.0)
• description - Clear explanation of agent purpose
• author - Creator or organization
• license - Usage terms

Skills

Skills define what the agent can do:

{
  "skills": [
    {
      "name": "get_weather",
      "description": "Get current weather conditions for a city",
      "parameters": {
        "city": "string",
        "units": "celsius | fahrenheit"
      },
      "returns": "Weather data object",
      "mcp_server": "weather-api",
      "mcp_tool": "get_current_weather"
    },
    {
      "name": "get_forecast",
      "description": "Get 7-day weather forecast",
      "parameters": {
        "city": "string",
        "days": "number (1-7)"
      },
      "returns": "Forecast array",
      "mcp_server": "weather-api",
      "mcp_tool": "get_forecast"
    }
  ]
}

Skill Properties:

• name - Skill identifier
• description - What the skill does
• parameters - Required inputs
• returns - Expected output format
• mcp_server - Linked MCP server (optional)
• mcp_tool - Specific MCP tool (optional)

Capabilities

Technical capabilities the agent supports:

{
  "capabilities": {
    "languages": ["en", "es", "fr"],
    "domains": ["weather", "meteorology", "climate"],
    "input_modes": ["text", "voice"],
    "output_modes": ["text", "json", "speech"],
    "streaming": true,
    "async": true,
    "rate_limit": "100 requests/minute"
  }
}

Common Capabilities:

• languages - Supported natural languages
• domains - Subject matter expertise
• input_modes - How agent accepts requests
• output_modes - How agent returns results
• streaming - Supports real-time streaming
• async - Supports asynchronous operations
• rate_limit - Usage restrictions

Invocation

How to call the agent:

{
  "invocation": {
    "protocol": "mcp",
    "endpoint": "https://api.example.com/agents/weather",
    "authentication": {
      "type": "bearer",
      "required": true
    },
    "method": "POST",
    "format": "json-rpc"
  }
}

Invocation Properties:

• protocol - Communication protocol (mcp, rest, grpc)
• endpoint - Agent’s API endpoint
• authentication - Security requirements
• method - HTTP method if applicable
• format - Request/response format

Examples

Sample interactions help other agents understand usage:

{
  "examples": [
    {
      "skill": "get_weather",
      "description": "Get weather for San Francisco",
      "input": {
        "city": "San Francisco",
        "units": "fahrenheit"
      },
      "output": {
        "temperature": 65,
        "conditions": "Partly cloudy",
        "humidity": 72,
        "wind_speed": 12
      }
    }
  ]
}

Complete Agent Card Example

Here’s a full Agent Card specification:

{
  "name": "weather-assistant",
  "version": "1.0.0",
  "description": "Intelligent weather assistant providing real-time weather data, forecasts, and historical weather information for cities worldwide",
  "author": "Acme Weather Corp",
  "license": "Apache-2.0",
  
  "skills": [
    {
      "name": "get_weather",
      "description": "Get current weather conditions including temperature, humidity, wind, and precipitation",
      "parameters": {
        "city": "string - City name",
        "units": "string - celsius or fahrenheit (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, and conditions",
      "parameters": {
        "city": "string - City name",
        "days": "number - Forecast days (1-7)"
      },
      "returns": "Array of daily forecast objects",
      "mcp_server": "weather-api",
      "mcp_tool": "get_forecast"
    }
  ],
  
  "capabilities": {
    "languages": ["en", "es", "fr"],
    "domains": ["weather", "meteorology"],
    "input_modes": ["text"],
    "output_modes": ["text", "json"],
    "streaming": false,
    "async": false,
    "rate_limit": "100 requests/minute"
  },
  
  "invocation": {
    "protocol": "mcp",
    "endpoint": "https://api.example.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": {
        "temperature": 65,
        "conditions": "Partly cloudy",
        "humidity": 72,
        "wind_speed": 12
      }
    }
  ]
}

Integration with MCP Servers

Agent Cards and MCP servers work together:

Mapping Skills to Tools

Agent Card skills reference MCP server tools:

Agent Card:

{
  "skills": [{
    "name": "analyze_sales",
    "mcp_server": "analytics-server",
    "mcp_tool": "analyze_data"
  }]
}

MCP Server:

{
  "tools": [{
    "name": "analyze_data",
    "description": "Analyze sales data and generate insights",
    "inputSchema": { /* JSON Schema */ }
  }]
}

When an agent invokes the “analyze_sales” skill, it calls the “analyze_data” tool on the “analytics-server” MCP server.

Use Cases

1. Multi-Agent Systems

Build systems where multiple specialized agents collaborate:

• Research Agent - Gathers information
• Analysis Agent - Processes data
• Reporting Agent - Generates reports
• Coordination Agent - Orchestrates workflow

Each agent has a card describing its capabilities.

2. Agent Marketplaces

Publish agents to exchanges where others can discover them:

• Public Exchange - Open marketplace
• Organization Exchange - Internal sharing
• Partner Exchange - B2B collaboration

3. Dynamic Agent Discovery

Agents find other agents at runtime based on capabilities:

Agent A needs "weather data"
  → Searches for agents with weather skills
  → Finds Weather Assistant Agent Card
  → Reads capabilities and invocation info
  → Invokes the weather agent
  → Receives weather data

4. Agent Composition

Combine multiple agents to create complex behaviors:

• Customer Service = Lookup Agent + Knowledge Agent + Action Agent
• Data Pipeline = Extraction Agent + Transform Agent + Load Agent
• Content Creation = Research Agent + Writing Agent + Editing Agent

Creating Agent Cards in MA²D

MA²D provides a visual interface for creating Agent Cards:

Step 1: Basic Information

1. Navigate to Agent Cards
2. Click ”+ New Agent Card”
3. Fill in:
   • Name
   • Version
   • Description
   • Author
   • License

Step 2: Define Skills

1. Click “Add Skill”
2. Enter skill details:
   • Name and description
   • Parameters
   • Return value
3. Link to MCP server (optional)
4. Specify MCP tool (optional)

Step 3: Configure Capabilities

1. Select supported languages
2. Define domains
3. Set input/output modes
4. Configure technical capabilities

Step 4: Set Invocation Details

1. Choose protocol (MCP, REST, etc.)
2. Set endpoint URL
3. Configure authentication
4. Specify format

Step 5: Add Examples

1. Click “Add Example”
2. Select skill
3. Provide sample input
4. Show expected output

Step 6: Test & Publish

1. Validate Agent Card
2. Test with MCP servers
3. Publish to Anypoint Exchange

Best Practices

Clear and Descriptive

✅ Good Description:

“Customer service agent that handles inquiries about orders, shipping, returns, and account management. Supports English and Spanish. Can escalate to human agents when needed.”

❌ Poor Description:

“Customer service agent”

Well-Defined Skills

Each skill should have:

• Specific name - Not vague
• Clear purpose - What it does
• Documented parameters - What inputs are needed
• Expected returns - What comes back
• Use cases - When to use it

Accurate Capabilities

Don’t oversell:

• List only supported languages
• Be honest about limitations
• Specify rate limits
• Document performance characteristics

Comprehensive Examples

Provide multiple examples:

• Simple cases
• Complex scenarios
• Edge cases
• Error handling

Keep Updated

Maintain your Agent Cards:

• Update version when skills change
• Add new skills as capabilities grow
• Remove deprecated skills
• Keep examples current

Schema Validation

Agent Cards should validate against the A2A schema:

interface AgentCard {
  name: string
  version: string
  description: string
  author?: string
  license?: string
  skills: Skill[]
  capabilities?: Capabilities
  invocation: Invocation
  examples?: Example[]
}

MA²D automatically validates your Agent Cards before publishing.

Discovering Agent Cards

Agents can discover other agents via:

Well-Known Endpoint

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

Returns the agent’s card for discovery.

Agent Registries

Centralized directories of Agent Cards:

• Anypoint Exchange
• Public agent marketplaces
• Organization-specific registries

Direct URLs

Agent Cards can be hosted at any URL:

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

Security Considerations

Authentication

Agent Cards should specify auth requirements:

• None - Public access
• API Key - Simple token
• Bearer Token - OAuth 2.0
• mTLS - Mutual TLS certificates

Authorization

Define who can invoke skills:

• Public (anyone)
• Authenticated (valid credentials)
• Authorized (specific permissions)

Rate Limiting

Protect agents with rate limits:

{
  "capabilities": {
    "rate_limit": "100 requests/minute",
    "burst_limit": "10 requests/second"
  }
}

Future of Agent Cards

The A2A protocol and Agent Cards are evolving:

• Standardization - Industry-wide standards
• Enhanced Discovery - Better search and matching
• Versioning - Backward compatibility
• Federation - Cross-organization agent networks
• Governance - Policy-based agent interaction

Next Steps

Learn more about Agent Cards:

• Creating Agent Cards - Step-by-step guide
• Agent Cards Feature - Detailed feature docs
• Agent Card Specification - Complete schema reference
• Publishing - Share on Anypoint Exchange

Or explore related concepts:

• MCP Protocol - Understand MCP integration
• MCP Servers - Create underlying servers
• API Reference - Technical documentation

Ready to create an Agent Card? Follow the Creating Agent Cards guide to build your first card!