Agent card
Tell other agents who your store agent is, what it can do, and where to send tasks.
The host-aware /.well-known/agent-card.json document: supported interfaces, auth schemes, capabilities, and skills.
The agent card is the public discovery document at /.well-known/agent-card.json. It tells an external agent which A2A interfaces Aly supports, which auth schemes are accepted, and which commerce skills are available for the current host.
Request
bash
curl https://acme.aly.store/.well-known/agent-card.jsonHost-aware response
- Platform host (
aly.store) returns Aly's platform commerce agent card. - Store host (
<slug>.aly.storeor a verified custom domain) returns a store-scoped card. Skill examples are rewritten to reference that store slug. - Reserved or unknown hosts fall back to platform discovery rather than treating the host as a seller slug.
Shape
json
{ "name": "Acme (aly.store)", "description": "AI shopping agent for Acme.", "supportedInterfaces": [ { "url": "https://aly.store/api/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }, { "url": "https://aly.store/api/a2a", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0" } ], "provider": { "organization": "Acme", "url": "https://acme.aly.store" }, "version": "1.0.0", "documentationUrl": "https://acme.aly.store/llms.txt", "capabilities": { "streaming": true, "pushNotifications": true }, "securitySchemes": { "aly_oauth": { "oauth2SecurityScheme": { "description": "OAuth 2.1 authorization for acting on behalf of users", "oauth2MetadataUrl": "https://aly.store/.well-known/oauth-authorization-server", "flows": { "authorizationCode": { "authorizationUrl": "https://aly.store/oauth/authorize", "tokenUrl": "https://aly.store/oauth/token", "scopes": { "read:sites": "Browse this storefront", "read:orders": "View buyer's order history at this store", "write:orders": "Place orders and manage cart on this store" }, "pkceRequired": true } } } }, "aly_api_key": { "apiKeySecurityScheme": { "description": "API key authentication using Authorization: Bearer aly_*.", "location": "header", "name": "Authorization" } } }, "securityRequirements": [ { "aly_oauth": ["read:sites", "read:orders", "write:orders"] }, { "aly_api_key": [] } ], "security": [ { "aly_oauth": ["read:sites", "read:orders", "write:orders"] }, { "aly_api_key": [] } ], "defaultInputModes": ["text/plain", "application/json"], "defaultOutputModes": ["application/json"], "skills": [ { "id": "product-search", "name": "Product Search", "description": "Search and browse products across published aly.store storefronts.", "tags": ["shopping", "search", "products", "catalog"], "examples": ["Show me all products on this store"], "inputModes": ["text/plain", "application/json"], "outputModes": ["application/json"] } ]}Fields
| Field | Notes |
|---|---|
supportedInterfaces | Aly advertises both JSON-RPC and HTTP+JSON bindings. Store cards point these at the platform A2A route, while the card itself remains store-scoped. Operation-specific HTTP+JSON aliases are also wired under /api/a2a/message:* and /api/a2a/tasks. |
provider | Platform card uses Aly as provider. Store cards use the store title and canonical origin. |
capabilities.streaming | Streaming is supported through /api/a2a/streaming, message:stream, and JSON-RPC SendStreamingMessage. |
capabilities.pushNotifications | Tasks can store push configs and deliver statusUpdate / artifactUpdate payloads to approved URLs. |
securitySchemes | OAuth 2.1 access tokens (aly_oauth_*) and API keys (aly_*) are accepted. Browser session JWTs are not supported on authenticated A2A task routes. |
securityRequirements and security | Both are emitted for client compatibility. Individual skills still enforce their own auth requirements. |
skills[] | The canonical skill list. See Available skills for behavior and auth per skill. |
No endpoint object
The live card does not emit the older
endpoints, auth, or signing objects. Use supportedInterfaces, securitySchemes, andcapabilities instead.No extended card yet
A2A 1.0 defines
GetExtendedAgentCard and the HTTP+JSONGET /extendedAgentCard route for authenticated private discovery. Aly does not currently advertisecapabilities.extendedAgentCard or serve an extended card; use the public host-aware card plus bearer auth on the task routes.Cache and revalidate
Agent cards are served with a one-hour public cache,
Vary: Host, and an ETag. Re-fetch when a skill is missing because the store card can change as Aly rolls out new default skills.Was this page helpful?