How to Write an Agent Card
Practical Tutorial

An Agent Card is the "business card" of an agent in the A2A Protocol. It describes the information that other agents need to discover your agent and understand its capabilities. For the basic concepts, see "What is an A2A Agent Card? Complete Guide". This article walks through how to actually write an Agent Card.

Minimal Agent Card

Here are the minimum required fields for a working Agent Card. Start with this structure.

{
  "name": "my_first_agent",
  "description": "My first A2A agent",
  "version": "1.0.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "supportedInterfaces": [
    {
      "url": "https://example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "hello",
      "name": "Greet",
      "description": "Return a greeting to the user",
      "tags": ["greeting", "basic"]
    }
  ]
}

Field Guide with Examples

name / description

name is the unique identifier for the agent. snake_case or kebab-case is recommended.

version

Use semantic versioning (semver) format: MAJOR.MINOR.PATCH — three numbers.

"1.0.0"  // Initial release
"1.1.0"  // Backward-compatible feature addition
"2.0.0"  // Breaking change (e.g. skill ID change)

supportedInterfaces

Defines how to connect to the agent. Choose from three protocol bindings.

capabilities

Declares the agent's communication capabilities.

"capabilities": {
  "streaming": true,        // Can respond in real-time
  "pushNotifications": true, // Async task completion notifications
  "extendedAgentCard": false // Support for extended spec
}

• streaming: Set to true for chatbots or interactive agents
• pushNotifications: Set to true for long-running tasks (e.g. report generation)

skills

Defines the skills (actions) the agent offers.

"skills": [
  {
    "id": "search_products",
    "name": "Product Search",
    "description": "Search products by keyword or condition",
    "tags": ["search", "product", "e-commerce"],
    "examples": [
      "Find red sneakers",
      "Wireless earphones under $100"
    ]
  }
]

Use Presets to Get Started Quickly

The AgentJUKU Generator provides 5 preset templates. Instead of writing from scratch, pick the closest preset and customize it — the fastest approach.

• Booking Agent — Specialized in reservations and schedule management
• Customer Support — 2-skill structure: FAQ answers and ticket management
• Sales & Quotes — Quote generation and product recommendations
• Data Analysis — Report generation and query execution
• Empty Template — For when you want to fill in everything manually

Deployment

Place your Agent Card at /.well-known/agent-card.json. Here are instructions per platform.

Vercel

// Just place it in the public/.well-known/ directory
// Vercel automatically serves it as a static file

project/
  public/
    .well-known/
      agent-card.json  ← place here

Nginx

location /.well-known/agent-card.json {
    alias /var/www/html/agent-card.json;
    default_type application/json;
    add_header Access-Control-Allow-Origin "*";
}

Express

const express = require('express');
const app = express();

app.get('/.well-known/agent-card.json', (req, res) => {
  res.json(require('./agent-card.json'));
});

Common Mistakes

Summary

Creating an Agent Card is not difficult once you understand the naming conventions and field structure. Start from the minimal config, use presets, and add fields as needed — the most efficient approach.