design-a2a-agent-card

Design A2A Agent Card

Create a standards-compliant A2A Agent Card that advertises an agent's identity, skills, authentication requirements, and capabilities for discovery by other agents.

When to Use

• Building an agent that must be discoverable by other A2A-compliant agents
• Exposing agent capabilities for multi-agent orchestration
• Migrating an existing agent to the A2A (Agent-to-Agent) protocol
• Defining the public contract for an agent before implementation
• Integrating with agent registries or directories that consume Agent Cards

Inputs

• Required: Agent name and description
• Required: List of skills the agent can perform (name, description, input/output schemas)
• Required: Base URL where the agent will be hosted
• Optional: Authentication method (none, oauth2, oidc, api-key)
• Optional: Supported content types beyond text/plain (e.g., image/png, application/json)
• Optional: Capability flags (streaming, push notifications, state transition history)
• Optional: Provider organization name and URL

Procedure

Step 1: Define Agent Identity and Description

1.1. Choose the agent identity fields:

{
  "name": "data-analysis-agent",
  "description": "Performs statistical analysis, data visualization, and report generation on tabular datasets.",
  "url": "https://agent.example.com",
  "provider": {
    "organization": "Example Corp",
    "url": "https://example.com"
  },
  "version": "1.0.0"
}

1.2. Write a clear, actionable description that answers:

• What domains does this agent cover?
• What kinds of tasks can it handle?
• What are its limitations?

1.3. Set the canonical URL where the Agent Card will be served at /.well-known/agent.json.

Got: A complete identity block with name, description, URL, provider, and version.

If fail: If the agent serves multiple domains, consider whether it should be one agent with many skills or multiple agents with focused scopes. A2A favors focused agents with clear boundaries.