3. Agent skills and AgentCard

Before an A2A agent can do anything useful, it must define what it can do (skills) and how other agents or clients can learn about those capabilities (the AgentCard).

In this chapter, we use the helloworld sample to understand these concepts.

🎯 Agent skills

Agent skills describe specific capabilities or functions an agent can perform. Skills are the building blocks that tell clients what kinds of tasks an agent is good at.

Core skill fields

An AgentSkill object includes these key fields:

Field	Type	Description	Example
`id`	string	Unique identifier	`"hello_world"`
`name`	string	Human-readable skill name	`"Return Hello World"`
`description`	string	Detailed description	`"A simple greeting skill"`
`tags`	list	Keywords for categorization/discovery	`["greeting", "basic"]`
`examples`	list	Example prompts / use cases	`["say hello", "greet me"]`
`inputModes`	list	Supported input media types	`["text/plain"]`
`outputModes`	list	Supported output media types	`["text/plain"]`

A simple skill example

from a2a.types import AgentSkill

hello_world_skill = AgentSkill(
    id="hello_world",
    name="Return Hello World",
    description="A simple greeting skill that returns a Hello World message",
    tags=["greeting", "basic", "demo"],
    examples=[
        "say hello",
        "greet me",
        "say hi"
    ],
    inputModes=["text/plain"],
    outputModes=["text/plain"]
)

A more advanced skill example

More complex skills can support multiple input/output formats:

advanced_skill = AgentSkill(
    id="data_processor",
    name="Data Processor",
    description="Process and analyze data in various formats",
    tags=["data", "analysis", "processing"],
    examples=[
        "analyze this CSV file",
        "process JSON data",
        "generate a data report"
    ],
    inputModes=[
        "text/plain",
        "application/json",
        "text/csv"
    ],
    outputModes=[
        "application/json",
        "text/html",
        "image/png"
    ]
)

📋 AgentCard

An AgentCard is a JSON document exposed by an A2A server—typically at .well-known/agent-card.json. Think of it as the agent’s digital business card.

Core card fields

An AgentCard includes information such as:

Field	Type	Description
`name`	string	Agent name
`description`	string	Agent description
`version`	string	Version
`url`	string	A2A service endpoint URL
`capabilities`	object	Supported A2A capabilities
`defaultInputModes`	list	Default input media types
`defaultOutputModes`	list	Default output media types
`skills`	list	List of skills
`securitySchemes`	object	Authentication configuration

Basic AgentCard example

from a2a.types import AgentCard

agent_card = AgentCard(
    name="Hello World Agent",
    description="A simple demo agent for learning the A2A protocol",
    version="1.0.0",
    url="http://localhost:9999/",

    capabilities={
        "streaming": True,           # supports streaming
        "pushNotifications": False   # no push notifications
    },

    defaultInputModes=["text/plain"],
    defaultOutputModes=["text/plain"],

    skills=[hello_world_skill],

    securitySchemes={
        "public": {
            "type": "public",
            "description": "Public access without authentication"
        }
    }
)

Enterprise-style AgentCard example

enterprise_agent_card = AgentCard(
    name="Enterprise Data Analysis Agent",
    description="A professional agent for enterprise data analysis and report generation",
    version="2.1.3",
    url="https://api.example.com/a2a/",

    capabilities={
        "streaming": True,
        "pushNotifications": True,
        "longRunningOperations": True
    },

    defaultInputModes=["text/plain", "application/json"],
    defaultOutputModes=["application/json", "text/html"],

    skills=[
        data_analysis_skill,
        report_generation_skill,
        chart_creation_skill
    ],

    securitySchemes={
        "oauth2": {
            "type": "oauth2",
            "flows": {
                "clientCredentials": {
                    "tokenUrl": "https://auth.example.com/token",
                    "scopes": {
                        "read": "Read access",
                        "write": "Write access"
                    }
                }
            }
        }
    }
)

🔍 Skill discovery

Client discovery flow

Fetch the AgentCard

import requests

response = requests.get("http://localhost:9999/.well-known/agent-card.json")
agent_card = response.json()

Inspect skills

for skill in agent_card["skills"]:
    print(f"Skill: {skill['name']}")
    print(f"Description: {skill['description']}")
    print(f"Tags: {skill['tags']}")
    print("---")

Pick the right skill

def find_skills_by_tag(skills, tag):
    return [skill for skill in skills if tag in skill.get("tags", [])]

greeting_skills = find_skills_by_tag(agent_card["skills"], "greeting")

🛠️ Exercises

Exercise 1: Create a custom skill

Create a calculator skill:

calculator_skill = AgentSkill(
    id="calculator",
    name="Math Calculator",
    description="Perform basic math operations",
    tags=["math", "calculation", "utility"],
    examples=[
        "calculate 2 + 3",
        "sqrt of 10",
        "solve x^2 + 2x + 1 = 0"
    ],
    inputModes=["text/plain"],
    outputModes=["text/plain", "application/json"]
)

Exercise 2: Design an AgentCard

Create a full AgentCard for your agent:

my_agent_card = AgentCard(
    name="My first A2A agent",
    description="A hands-on project to learn the A2A protocol",
    version="0.1.0",
    url="http://localhost:8000/",

    capabilities={
        "streaming": False,
        "pushNotifications": False
    },

    defaultInputModes=["text/plain"],
    defaultOutputModes=["text/plain"],

    skills=[
        hello_world_skill,
        calculator_skill
    ],

    securitySchemes={
        "public": {
            "type": "public"
        }
    }
)

📊 Best practices

Skill design principles

Single responsibility - Each skill focuses on one capability
Clear descriptions - Use clear names and descriptions
Rich examples - Provide multiple usage examples
Meaningful tags - Make discovery easier

AgentCard design principles

Complete information - Include endpoint and auth details
Versioning - Use versions to manage compatibility
Capability declarations - Declare supported features accurately
Security configuration - Configure auth based on requirements

🎯 Key takeaways

Skills define what an agent can do
AgentCards publicly declare identity and capabilities
Media types determine input/output formats
Tags enable categorization and discovery
Security schemes control access

Understanding the AgentCard is essential because it’s how clients discover agents and learn how to interact with them.

Next: Agent executor - Learn how to implement the agent’s core execution logic.

Tip: When designing skills, think about real user needs and usage scenarios. Good skill design is the foundation of a successful A2A agent.

2. Environment setup 4. Agent executor