If you want peer agents to consult our deliverability service, the entry point is one file: the Agent Card at /.well-known/agent.json. That single JSON document is what every A2A-capable peer fetches first. It tells them who we are, what we can do, how to authenticate, and where to POST tasks. This article walks through the actual card we publish, the choices behind each field, and a full example peer-task flow.
What an Agent Card is
In the A2A spec, an Agent Card is a JSON document that lives at a predictable URL on the agent's HTTPS host. The spec fixes only a small set of required fields: name, version, protocols, capabilities, auth, and endpoint. Everything else is optional enrichment. The philosophy is the same as robots.txt or security.txt: make the minimum discoverable so machines can act on it without human negotiation.
Our Agent Card JSON in full
Here is the card we publish today. You can fetch it yourself — it is a public document.
{
"schemaVersion": "a2a/1.0",
"name": "Inbox Check Deliverability Agent",
"description": "Email deliverability capabilities: seed-list placement tests, DNS authentication audits, blacklist lookups.",
"version": "1.0.0",
"homepage": "https://check.live-direct-marketing.online",
"provider": {
"name": "Live Direct Marketing",
"url": "https://live-direct-marketing.online"
},
"protocols": ["a2a/1.0"],
"endpoint": "https://check.live-direct-marketing.online/a2a/tasks",
"capabilities": [
{
"id": "inbox-placement-test",
"description": "Run a seed-list placement test across 20+ mailboxes and return per-provider inbox/spam/missing counts.",
"inputSchema": { "$ref": "https://check.live-direct-marketing.online/schemas/placement-input.json" },
"outputSchema": { "$ref": "https://check.live-direct-marketing.online/schemas/placement-output.json" },
"mode": "async",
"typicalDurationSeconds": 120
},
{
"id": "dns-audit",
"description": "Validate SPF, DKIM, DMARC and BIMI for a sending domain and return a structured verdict.",
"inputSchema": { "$ref": "https://check.live-direct-marketing.online/schemas/dns-audit-input.json" },
"outputSchema": { "$ref": "https://check.live-direct-marketing.online/schemas/dns-audit-output.json" },
"mode": "sync",
"typicalDurationSeconds": 2
},
{
"id": "blacklist-check",
"description": "Check an IP or domain against 50+ DNSBLs including Spamhaus, Barracuda, SORBS, SURBL.",
"inputSchema": { "$ref": "https://check.live-direct-marketing.online/schemas/blacklist-input.json" },
"outputSchema": { "$ref": "https://check.live-direct-marketing.online/schemas/blacklist-output.json" },
"mode": "sync",
"typicalDurationSeconds": 4
}
],
"auth": [
{
"type": "bearer",
"tokenFormat": "ic_live_*",
"obtain": "https://check.live-direct-marketing.online/account/api-keys",
"docs": "https://check.live-direct-marketing.online/docs/api"
}
],
"rateLimit": { "requestsPerMinute": 60, "concurrentTasks": 5 },
"contact": "agents@live-direct-marketing.online"
}Capabilities listed
Three capabilities, each narrow enough to have a stable contract. That is deliberate. Wide, fuzzy capabilities ("check my email") make peer reasoning harder; narrow ones let a peer compose its own workflow.
inbox-placement-test
The heavyweight one. Takes a rendered HTML body plus a sender domain and returns per-provider placement counts. Async because real inbox delivery takes minutes. The task envelope includes a callback URL we POST to when the verdict is ready.
dns-audit
Synchronous. Pass a domain, get back parsed SPF, DKIM selector discovery, DMARC policy, and BIMI status with alignment verdicts. Returns in under two seconds.
blacklist-check
Synchronous. Pass an IP or domain, get back a map of each DNSBL and its listing status. Useful inside larger pipelines that need to gate a send on a clean reputation.
Auth flow for peer agents
A2A doesn't mandate a single auth scheme; it mandates that the Agent Card advertises whatever scheme you use. We use bearer tokens — the same API keys that power our REST and MCP surfaces. A peer agent obtains a key once (manually, by creating an account), stores it, and sends it as Authorization: Bearer ic_live_... on every task POST.
A2A supports OAuth2 flows, and we will add one for high-volume B2B integrations. For the early adopters — individual developers building agent pipelines — a pasted bearer token is faster and good enough. The Agent Card will announce additional auth methods as they ship.
Example peer-agent task request
This is what a reviewer agent sends us when it wants a placement verdict on a draft email. Note the callbackUrl: because placement tests are async, we acknowledge fast and push results later.
POST https://check.live-direct-marketing.online/a2a/tasks
Content-Type: application/json
Authorization: Bearer ic_live_a8f3b2c1d4e5f678
{
"taskId": "task_7f1e9d8c",
"capability": "inbox-placement-test",
"requestedBy": {
"agentName": "ReviewerAgent",
"agentUrl": "https://reviewer.acme.ai/.well-known/agent.json"
},
"input": {
"from": "outreach@news.acme.com",
"subject": "Quick question about your payroll stack",
"html": "<html>...rendered body...</html>",
"providers": ["gmail", "outlook", "yahoo", "mailru", "yandex"]
},
"callbackUrl": "https://reviewer.acme.ai/a2a/callbacks/task_7f1e9d8c"
}Response format
The immediate response for an async capability is a 202 with a minimal envelope:
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"taskId": "task_7f1e9d8c",
"status": "accepted",
"estimatedCompletionSeconds": 120
}When the placement test finishes, we POST the verdict to the peer's callback URL. Same envelope shape, now with status: "completed" and a result matching the capability's output schema. If the test fails (quota exhausted, invalid HTML), the status is "failed" and an error object replaces result.
POST https://reviewer.acme.ai/a2a/callbacks/task_7f1e9d8c
Content-Type: application/json
{
"taskId": "task_7f1e9d8c",
"status": "completed",
"completedAt": "2026-07-19T14:22:18Z",
"result": {
"inboxRate": 0.92,
"spamRate": 0.04,
"missingRate": 0.04,
"perProvider": {
"gmail": { "folder": "inbox", "auth": "pass" },
"outlook": { "folder": "inbox", "auth": "pass" },
"yahoo": { "folder": "inbox", "auth": "pass" },
"mailru": { "folder": "promotions", "auth": "pass" },
"yandex": { "folder": "inbox", "auth": "pass" }
},
"spamAssassinScore": 1.4,
"dmarcAlignment": "pass"
}
}Discovery via DNS or URL
Two ways for a peer to find us. The simple one: a human configures our URL in the peer's settings. The automated one: a peer does a DNS-based lookup. The A2A spec supports _agent._tcp.<domain> SRV records for service discovery; we publish one that points at the well-known URL, which means tools that do domain-to-agent resolution can find us from a From-address domain alone.
Versioning
The Agent Card carries two version fields. schemaVersion identifies the A2A spec revision we speak. version is our own service version — bumped when a capability's schema changes in a breaking way. Capabilities themselves are implicitly versioned through their schema references; if we introduce a breaking change to inbox-placement-test, we publish a new capability ID (inbox-placement-test-v2) and keep the old one alive for a deprecation window.
Best practices for Agent Card design
- Keep capabilities narrow. One card, many small capabilities beats one fat capability with a dozen optional fields.
- Publish real JSON Schemas for inputs and outputs. Peer agents use them for validation and for reasoning about task inputs.
- Declare
modeandtypicalDurationSecondshonestly. Peers use these to decide whether to await or register a callback. - Serve the card with
Content-Type: application/jsonand permissive CORS, or agent runtimes in the browser will silently fail to read it. - Do not version by query string. Cards are cacheable by URL — if a peer caches the wrong card because the URL varies, you get stale capability assumptions.