Agent Card Templates

Purpose: Provide reusable JSON templates for creating A2A (Agent-to-Agent) protocol agent cards following the official specification.

Activation Triggers:

Creating new A2A agent cards
Implementing agent discovery endpoints
Configuring authentication schemes
Defining agent capabilities and skills
Setting up service endpoints
Validating agent card JSON structure

Key Resources:

templates/schema.json - Complete JSON schema for validation
templates/basic-agent-card.json - Simple agent card template
templates/multi-capability-agent-card.json - Agent with multiple skills
templates/authenticated-agent-card.json - Agent with auth requirements
templates/streaming-agent-card.json - Agent with streaming support
examples/ - Real-world agent card examples
scripts/validate-agent-card.sh - Schema validation script
scripts/generate-agent-card.sh - Interactive card generator
scripts/test-agent-card.sh - Format and structure testing

Security: API Key Handling

CRITICAL: When generating any configuration files or code:

❌ NEVER hardcode actual API keys or secrets ❌ NEVER include real credentials in examples ❌ NEVER commit sensitive values to git

✅ ALWAYS use placeholders: your_service_key_here ✅ ALWAYS create .env.example with placeholders only ✅ ALWAYS add .env* to .gitignore (except .env.example) ✅ ALWAYS read from environment variables in code ✅ ALWAYS document where to obtain keys

Placeholder format: {service}_{env}_your_key_here

Agent Card Structure

Required Fields

Basic Identity:

id - Unique identifier (URI or UUID)
name - Human-readable display name
protocolVersion - A2A protocol version (e.g., "0.3")
serviceEndpoint - Base URL for agent's A2A service
provider - Organization information (name, contactEmail, url)

Security:

securitySchemes - Authentication scheme definitions
security - Required auth combinations

Capabilities:

capabilities - Feature flags (streaming, pushNotifications)

Optional Fields

description - Detailed agent purpose explanation
logo - URL to logo image
version - Agent implementation version
skills - Array of agent capabilities with schemas
extensions - Extension support declarations
metadata - Custom key-value pairs

Template Categories

1. Basic Agent Card

Use for: Simple agents with minimal configuration Template: templates/basic-agent-card.json Features:

Required fields only
Simple API key authentication
No streaming or advanced capabilities
Single skill definition

2. Multi-Capability Agent Card

Use for: Agents with multiple skills and capabilities Template: templates/multi-capability-agent-card.json Features:

Multiple skill definitions
Input/output schemas for each skill
Capability flags enabled
Comprehensive metadata

3. Authenticated Agent Card

Use for: Agents with complex authentication requirements Template: templates/authenticated-agent-card.json Features:

Multiple authentication schemes (API Key, Bearer, OAuth2)
Alternative auth combinations
Security scopes and permissions
OpenID Connect support

4. Streaming Agent Card

Use for: Agents supporting real-time updates Template: templates/streaming-agent-card.json Features:

Streaming capability enabled
Push notification support
WebHook configuration
SSE (Server-Sent Events) ready

Authentication Schemes

Supported Types

API Key:

{
  "type": "apiKey",
  "name": "X-API-Key",
  "in": "header"
}

Bearer Token:

{
  "type": "http",
  "scheme": "bearer"
}

OAuth 2.0:

{
  "type": "oauth2",
  "flows": {
    "authorizationCode": {
      "authorizationUrl": "https://provider.example/oauth/authorize",
      "tokenUrl": "https://provider.example/oauth/token",
      "scopes": {
        "read": "Read access",
        "write": "Write access"
      }
    }
  }
}

Basic Auth:

{
  "type": "http",
  "scheme": "basic"
}

Usage Workflow

1. Select Template

Choose template based on agent requirements:

# List available templates
ls templates/

# View template content
cat templates/basic-agent-card.json

2. Generate Agent Card

Use interactive generator:

./scripts/generate-agent-card.sh

# Or specify template directly
./scripts/generate-agent-card.sh --template basic

Generator prompts for:

Agent name and description
Service endpoint URL
Provider information
Authentication scheme
Capabilities and skills

3. Validate Agent Card

Validate against schema:

# Validate structure and required fields
./scripts/validate-agent-card.sh agent-card.json

# Test format and completeness
./scripts/test-agent-card.sh agent-card.json

Validation checks:

Required fields present
Valid JSON syntax
Schema compliance
URL format validation
Authentication scheme correctness

4. Deploy Agent Card

Host at standard location:

https://<base_url>/.well-known/agent.json

Or alternative:

https://<base_url>/.well-known/agent-card.json

Skill Definition

Each skill in the agent card includes:

{
  "name": "skill-identifier",
  "description": "What the skill does",
  "inputSchema": {
    "type": "object",
    "properties": {
      "param1": {"type": "string"}
    },
    "required": ["param1"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "result": {"type": "string"}
    }
  },
  "inputModes": ["text/plain", "application/json"],
  "outputModes": ["application/json"],
  "tags": ["category", "feature"],
  "examples": [
    {
      "input": {"param1": "example"},
      "output": {"result": "example output"}
    }
  ]
}

Scripts Reference

validate-agent-card.sh

Purpose: Validate agent card against JSON schema Usage:

./scripts/validate-agent-card.sh <agent-card.json>

Checks:

JSON syntax validity
Required fields presence
Schema compliance
URL format validation

generate-agent-card.sh

Purpose: Interactive agent card generator Usage:

./scripts/generate-agent-card.sh [--template TEMPLATE]

Options:

--template basic|multi|authenticated|streaming
--output FILE - Output file path
--interactive - Prompt for all values

test-agent-card.sh

Purpose: Test agent card format and structure Usage:

./scripts/test-agent-card.sh <agent-card.json>

Tests:

Well-formed JSON
Required fields present
Valid authentication schemes
Capability flags consistency
Service endpoint accessibility

Examples Reference

examples/calculator-agent.md - Simple math calculation agent examples/translation-agent.md - Multi-language translation service examples/data-analysis-agent.md - Complex data processing agent

Each example includes:

Complete agent card JSON
Authentication configuration
Skill definitions
Usage scenarios
Deployment instructions

Best Practices

✓ Use standard well-known URI - /.well-known/agent.json ✓ Include comprehensive descriptions - Help with discovery ✓ Define clear input/output schemas - Enable validation ✓ Specify authentication requirements - Security first ✓ Version your agent cards - Track changes ✓ Test card accessibility - Ensure HTTP GET works ✓ Document all skills - Include examples ✓ Use placeholder credentials - Never hardcode secrets

Common Issues

Issue: Agent card not discovered Fix: Verify /.well-known/agent.json is accessible via HTTP GET

Issue: Authentication failures Fix: Check securitySchemes and security match implementation

Issue: Schema validation errors Fix: Run validate-agent-card.sh to identify missing/invalid fields

Issue: Skills not recognized Fix: Ensure input/output schemas are valid JSON Schema format

Resources

A2A Protocol Specification: https://a2a-protocol.org/latest/specification/ Agent Card Concepts: https://agent2agent.info/docs/concepts/agentcard/ JSON Schema Reference: https://json-schema.org/

Supported A2A Protocol Version: 0.3+ Template Version: 1.0.0 Last Updated: 2025-12-20

agent-card-templates