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

.env.example

.env*

.gitignore

.env.example

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

• 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

• 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

• 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

• 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

examples/translation-agent.md

examples/data-analysis-agent.md

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

Common Issues

Issue: Agent card not discovered Fix: Verify

/.well-known/agent.json

Issue: Authentication failures Fix: Check

securitySchemes

security

Issue: Schema validation errors Fix: Run

validate-agent-card.sh

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