Learn A2A - Agent Card & Discovery

#Introduction

In episode 2 we described the Agent Card as the discovery gateway — JSON metadata that lets a remote agent be "discovered" and understood. Now it's time to dissect that document field by field.

Episode 3 will give you two abilities: reading another agent's Agent Card with confidence, and writing a correct Agent Card of your own. We'll also explore its discovery side: how a card is published, fetched, and — since v1.0 — how its authenticity is verified through signed security cards.

#Anatomy of the Agent Card

The Agent Card is a JSON document published by the remote agent. When a client wants to collaborate, this is the first thing it reads. The basic fields are simple:

{
  "name": "Agent Analisis Laporan",
  "description": "Membaca laporan keuangan dan merangkum risiko",
  "url": "https://analisis.example.com",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true
  },
  "skills": [],
  "authentication": {}
}

• name — the agent's short name; sometimes written as agentName in early versions.
• description — an explanation of the agent's function, used to match needs.
• url — the endpoint where clients send tasks (the JSON-RPC endpoint).
• version — the version of the Agent Card itself.

#Capabilities: What the Agent Supports

The capabilities section declares the agent's communication capabilities. This matters because the client must adapt how it talks:

{
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "skills": {
      "readReport": true
    }
  }
}

• streaming — whether the agent supports partial responses over SSE. If false, the client can only wait for the final result.
• pushNotifications — whether the agent can receive push notifications to a webhook (we'll practice this in episode 7).
• skills — the list of special capabilities the agent has, with additional properties such as description and input-output examples.

#Skills: Definitions of Supported Tasks

The skills section contains the list of the agent's task capabilities. This is the basis for routing: the client matches its needs against the available skills.

{
  "skills": [
    {
      "id": "summarize-report",
      "name": "Meringkas Laporan",
      "description": "Menerima dokumen dan menghasilkan ringkasan eksekutif",
      "tags": ["keuangan", "riset"],
      "examples": [
        {
          "name": "Ringkas PDF laporan triwulan",
          "description": "Input PDF, output ringkasan dengan poin risiko"
        }
      ]
    }
  ]
}

Each skill has a unique id, a description other agents can understand, and examples — input-output examples that help the client understand how to use the skill. The tags field makes it easier to search capabilities in large registries (the topic of episode 16).

#Authentication: Declaring Access Requirements

The authentication field tells the client which authentication scheme must be satisfied before sending a task. If empty, the endpoint is open to the public:

{
  "authentication": {
    "schemes": ["bearer"],
    "credentials": "client"
  }
}

• schemes — the list of supported schemes, e.g., bearer, oauth2, or apikey.
• credentials — the party that holds the credentials; the value client means the client must provide the token.

We'll dissect the details of OAuth 2.1, API keys, and JWT in episode 9. For now, what matters is: this field is a declaration, and the client is obligated to adapt itself before communicating.

#Signed Security Card: Authenticity in v1.0

Since v1.0, an Agent Card can be signed — the result is called a signed security card. Its purpose is simple but crucial: to ensure that the card you read was truly issued by the agent claiming to issue it.

{
  "security": {
    "jwt": {
      "algorithm": "RS256",
      "issuer": "https://analisis.example.com",
      "subject": "agent-analisis",
      "audience": ["registry-a2a"]
    }
  },
  "signature": {
    "algorithms": ["RS256"]
  }
}

The security.jwt field contains identity claims — issuer, subject, audience — composed as a JWS (JSON Web Signature). A client that receives the card can verify the signature using the issuer's public key. If verification fails, the card is considered untrusted and collaboration is stopped. We'll explore the full security of this mechanism in episodes 9 and 14.

#Discovery: Publication, Fetching, and Verification

#URL Publication

The simplest way to publish an Agent Card is to place it at a stable URL — usually the root endpoint of the agent server:

curl -s https://analisis.example.com/.well-known/agent-card

The standard doesn't mandate a single path, but the .well-known/agent-card convention is widely used. Some agents offer a dedicated card endpoint, e.g., /agent-card, which returns JSON directly — try both with curl -s https://analisis.example.com/.well-known/agent-card.

#Fetching and Caching

After fetching a card, a client usually stores it in a cache so it doesn't refetch every time it wants to communicate. The common pattern:

• Fetch the card when the first connection is initialized.
• Store it together with a time-to-live (TTL).
• Reload it when the TTL expires or when an error related to capability changes occurs.

This caching practice has a big impact on performance when one client communicates with many remote agents — a topic we'll optimize in episode 18.

#Card Verification

Since v1.0, the secure discovery flow is: fetch the card, verify its security card signature, and only then decide to communicate.

1. Fetch the card from the remote agent's URL
2. Check whether the security.jwt field exists
3. Verify the signature with the issuer's public key
4. Match the issuer claim against the host being accessed
5. If valid -> proceed to send the task; if not -> reject

Steps three and four prevent spoofing attacks — situations where an attacker publishes a fake card in another agent's name. We'll discuss spoofing and its mitigations in depth in episode 14.

#Conclusion

Here's the core takeaway:

• The Agent Card is JSON metadata with name, description, url, capabilities, skills, and authentication.
• capabilities declares streaming, push notifications, and communication skills.
• skills describes the tasks an agent can complete, complete with input-output examples.
• authentication declares the security scheme a client must satisfy.
• Signed security cards in v1.0 enable authenticity verification via JWS signatures.
• Discovery flows from URL publication, fetch, cache, to verification before communicating.

In episode 4 we dive into the heart of execution: Task lifecycle & messages — the state machine from submitted to completed/failed, progress and metadata, the roles of user/agent messages, the text/file/structured part types, and streaming deltas. You'll understand how a task is actually "executed" over the protocol. See you there!