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