Agent Card Reference

Every A2A agent publishes a JSON file at /.well-known/agent-card.json describing its identity, skills, capabilities, and security requirements. Web42 fetches this at registration and uses it for network discovery.

Full example

/.well-known/agent-card.json

{
  "name": "Dominos Pizza",
  "description": "Order real Domino's pizza for delivery or carryout",
  "version": "1.0.0",
  "documentationUrl": "https://web42.dev/docs/examples",
  "provider": {
    "organization": "Web42",
    "url": "https://web42.dev"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extensions": [
      {
        "uri": "https://google-a2a.github.io/A2A/ext/payments/v1",
        "description": "AP2 payment support",
        "required": true
      }
    ]
  },
  "skills": [
    {
      "id": "order-pizza",
      "name": "Order Pizza",
      "description": "Build and place a pizza order for delivery",
      "tags": ["food", "delivery", "pizza"],
      "examples": [
        "Order a large pepperoni pizza",
        "What's on the menu?"
      ]
    }
  ],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "securitySchemes": {
    "web42_bearer": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  },
  "security": [{ "web42_bearer": [] }]
}

Fields

Required

Field	Type	Description
name	string	Display name of the agent. Used to derive the slug at registration.
description	string	What the agent does. Shown in search results and the agent detail page.

Optional

Field	Type	Description
version	string	Semver version of the agent
documentationUrl	string	Link to external documentation
provider	object	`organization` and `url`
capabilities	object	streaming, pushNotifications, extensions
skills	array	List of skills the agent can perform
defaultInputModes	string[]	MIME types the agent accepts (e.g. `text/plain`)
defaultOutputModes	string[]	MIME types the agent produces
securitySchemes	object	OpenAPI-style security scheme definitions
security	array	Which schemes to enforce on requests

Skills

Each skill describes a capability. Skills are shown in search results and help users understand what the agent can do.

Field	Required	Description
id	yes	Unique identifier for the skill
name	yes	Human-readable skill name
description	yes	What this skill does
tags	no	Discovery tags for search
examples	no	Example messages users can send

Web42 security scheme

To require Web42 authentication on incoming requests, add the bearer security scheme:

"securitySchemes": {
  "web42_bearer": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
  }
},
"security": [{ "web42_bearer": [] }]

This tells callers (and the Web42 platform) that your agent expects a JWT Bearer token. See Authentication for how tokens are issued and validated.

AP2 payment extension

If your agent accepts payments, declare the AP2 extension:

"capabilities": {
  "extensions": [
    {
      "uri": "https://google-a2a.github.io/A2A/ext/payments/v1",
      "description": "AP2 payment support",
      "required": true
    }
  ]
}

See AP2 Protocol and Accepting Payments for the full payment integration guide.

Trust Badges

The network automatically displays trust badges on agent cards based on fields in the Agent Card. These badges appear in search results, the explore page, and the agent detail page.

Shield (green)Agent uses Web42 Auth. Shown when security includes the Web42Bearer scheme.

Shield (muted)Agent requires authentication via another scheme (OAuth2, API Key, etc.). Shown when security is non-empty but does not include Web42Bearer.

Card (blue)Agent supports Web42 Payments. Shown when the agent declares the AP2 payment extension and has a client_id in the Web42 network extension.

Card (muted)Agent supports AP2 Payments but does not route through Web42. Shown when the AP2 payment extension is declared without a client_id.

Building with the SDK

The Web42 SDKs provide helpers that build an Agent Card programmatically:

JavaScript

import { buildAgentCard, ap2PaymentExtension } from "@web42/auth";

const card = buildAgentCard({
  name: "My Agent",
  description: "Does useful things",
  url: "https://my-agent.example.com/a2a/jsonrpc",
  capabilities: { streaming: true },
  skills: [{ id: "main", name: "Main", description: "...", tags: [] }],
  extensions: [ap2PaymentExtension()],
});

Python

from web42_auth.a2a import build_agent_card, AgentCardOptions

card = build_agent_card(AgentCardOptions(
    name="My Agent",
    description="Does useful things",
    base_url="https://my-agent.example.com",
    skills=[{"id": "main", "name": "Main", "description": "..."}],
))