# A2a Agent Card

> Create and configure A2A Agent Cards — the discovery document describing an agent's capabilities, skills, authentication, and endpoint. Use when defining what your agent exposes to other agents.

- **Type:** Skill
- **Install:** `agentstack add skill-orcaqubits-agentic-commerce-skills-plugins-a2a-agent-card`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [OrcaQubits](https://agentstack.voostack.com/s/orcaqubits)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [OrcaQubits](https://github.com/OrcaQubits)
- **Source:** https://github.com/OrcaQubits/agentic-commerce-skills-plugins/tree/main/a2a-multi-agent/skills/a2a-agent-card

## Install

```sh
agentstack add skill-orcaqubits-agentic-commerce-skills-plugins-a2a-agent-card
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# A2A Agent Card

## Before writing code

**Fetch live docs**:
1. Fetch `https://a2a-protocol.org/latest/specification/` and look for the Agent Card schema section
2. Web-search `site:github.com a2aproject A2A agent card schema` for the JSON Schema definition
3. Web-search `site:github.com a2aproject a2a-samples agent-card` for real-world Agent Card examples
4. Fetch SDK docs for Agent Card builder/helper classes

## Conceptual Architecture

### What the Agent Card Is

The Agent Card is a JSON document that describes an A2A agent to potential clients. It's the **discovery and capability advertisement mechanism** — analogous to an OpenAPI spec for REST APIs, but for agent-to-agent communication.

### Hosting

By convention, Agent Cards are served at:
```
{agent_base_url}/.well-known/agent-card.json
```

Agents can also be discovered via:
- Agent registries (centralized directories)
- Direct configuration (hard-coded URLs)
- Referral from other agents

### Key Sections

#### Identity
- **name** — Human-readable name
- **description** — What the agent does
- **url** — The agent's A2A endpoint (where JSON-RPC requests go)
- **version** — Semantic version of the agent
- **protocolVersion** — The A2A protocol version the agent supports (required)
- **provider** — Optional organization/owner information

#### Capabilities
Declares what protocol features the agent supports:
- **streaming** — Can the agent handle `message/stream`?
- **pushNotifications** — Can the agent send push notifications?
- **stateTransitionHistory** — Does the agent maintain full task state history?

#### Skills
Array of skills (capabilities) the agent offers:
- **id** — Unique skill identifier
- **name** — Human-readable skill name
- **description** — What the skill does
- **tags** — Categorization tags
- **examples** — Example inputs/prompts for this skill

Skills help client agents understand what tasks they can delegate.

#### Authentication
Declares required authentication via two top-level fields:
- **securitySchemes** — A map/object of named security scheme definitions (e.g., `apiKey`, `http` with `scheme: bearer`, `oauth2`, `openIdConnect`)
- **security** — An array of required scheme references (e.g., `[{ "schemeName": [] }]`)
- Each scheme has type-specific configuration (header name, OAuth URLs, OIDC discovery URL, etc.)

#### Input/Output Modes
- **defaultInputModes** — MIME types the agent accepts (e.g., `text/plain`, `application/json`, `image/png`)
- **defaultOutputModes** — MIME types the agent can produce

### Agent Card Design Principles

- **Be specific in descriptions** — Other agents (LLMs) will read this to decide whether to delegate tasks
- **Skills should be granular** — Each skill represents one capability, not the entire agent
- **Examples are critical** — They help client agents understand how to formulate requests
- **Declare all required auth** — Clients need to know upfront what credentials they need
- **Version meaningfully** — Update version when skills or capabilities change

### Use Cases

- Public-facing agent discovery (web-crawlable Agent Cards)
- Internal agent registry for enterprise multi-agent systems
- Marketplace listings where agents advertise their skills
- Framework integration points (ADK, LangGraph, CrewAI read Agent Cards)

### Best Practices

- Validate the Agent Card against the official JSON Schema
- Serve with appropriate CORS headers if agents run in browsers
- Include meaningful tags for skill categorization and search
- Keep descriptions concise but informative — they're read by LLMs
- Test that `/.well-known/agent-card.json` is accessible from client agents
- Update the Agent Card when adding/removing skills or changing capabilities

Fetch the specification for the exact Agent Card JSON Schema, all field types, and required vs optional fields before implementing.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [OrcaQubits](https://github.com/OrcaQubits)
- **Source:** [OrcaQubits/agentic-commerce-skills-plugins](https://github.com/OrcaQubits/agentic-commerce-skills-plugins)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-orcaqubits-agentic-commerce-skills-plugins-a2a-agent-card
- Seller: https://agentstack.voostack.com/s/orcaqubits
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.