Designing an Agent Card for Your Support Organisation

Your support organisation has a phone number, a support@ address, and a help centre. Soon it will also need a JSON file. That file is the Agent Card, and it decides whether another company's AI agent can find you, understand what you handle, and hand you work.

The business card almost nobody has written yet

An Agent Card is a machine-readable JSON document served at /.well-known/agent-card.json. It belongs to the A2A (Agent2Agent) protocol, which reached v1.0 under Linux Foundation governance in April 2026 with more than 150 production organisations behind it. Any A2A client fetches your card before it sends you anything at all. It reads the card, checks whether your declared skills match the task in hand, works out how to authenticate, and only then makes a call.

The rough consensus that settled during 2026 is worth remembering: MCP connects an agent to its own tools, A2A connects agents across organisational boundaries. Your internal stack of write-access integrations is the MCP side of the house. The Agent Card is the other side, the part that faces outward.

Here's the thing most teams get wrong about ownership. The card looks like an infrastructure artefact, so it gets handed to platform engineering, who fill it in from the API docs. But almost every meaningful decision on the card is a support policy decision. Which requests will you complete without a human? What's the refund ceiling? Which categories always route to a person? Engineering can serve the file. Support has to write it.

The eight fields the spec insists on

A compliant v1.0 card needs eight top-level fields, and validators will fail you on any that are missing:

• name: the human-readable label routers display when comparing candidates. “Acme Customer Support Agent”, not “AI Assistant”
• description: free text describing what you do and when another agent should call you
• version: semantic version of the agent itself, not the protocol
• supportedInterfaces: an array, each entry carrying url, protocolBinding (JSONRPC, GRPC or HTTP+JSON) and protocolVersion
• capabilities: what the transport supports, including streaming and push notifications
• defaultInputModes and defaultOutputModes: the content types you accept and return
• skills: the discrete things you can actually do

If you built a card during the v0.x era, three things moved. Top-level url and preferredTransport collapsed into supportedInterfaces, and provider.name became provider.organization. Cards written against the old shape don't fail loudly. They just quietly stop matching what current clients expect.

Spend real time on description. It's the main free-text signal an LLM-based router uses to decide whether you're the right agent for a task, and a vague one costs you volume you'll never see. “Handles customer support” tells a router nothing. “Handles post-purchase order, delivery and returns queries for Acme retail customers in the UK and EU” tells it everything.

Skills are the part support actually owns

A skill is one thing another agent can ask you to do. Each needs an id, a name, a description and tags, with examples and per-skill input and output modes where they differ from your defaults. Tags became required in v1.0, and a surprising number of published cards still omit them.

The most common failure is granularity. Teams mirror their internal ticket taxonomy onto the card and publish forty skills, because that's how the helpdesk is organised. Nobody can route to forty skills. The taxonomy that works for queue management is the wrong shape for discovery.

The right unit is an action a foreign agent can request and you can complete end to end. Something like order-status-lookup, return-label-issue, invoice-copy-request. Three to eight of these covers most retail and SaaS support organisations. If a skill can't be finished without a human deciding something, it probably isn't a skill yet.

Examples do more routing work than the description

The examples field on each skill is where the actual matching happens. Put three to five real phrasings in, pulled from your queue rather than invented. If a customer's agent is trying to work out whether “where is my parcel” maps to your order-status-lookup skill, the example strings are what it compares against. This is one of those places where reading a hundred real tickets beats an hour of design discussion.

What to hold back

A public card is a promise, and it's readable by anyone with curl. Some things simply don't belong on it.

• Skills you can't finish autonomously. Publishing a refund skill that declines four requests in ten is worse than not publishing it
• Internal-only capabilities like fraud review, chargeback strategy or VIP routing rules
• Anything resembling a credential. Validators actively scan for embedded API keys and JWTs, which tells you how often it happens
• Org structure. Team names, headcount and shift patterns are reconnaissance, not metadata
• Skills backed by a flaky or heavily rate-limited integration

We've watched teams publish an ambitious card in week one and then spend a month explaining to partners why half the declared skills return errors. Ship the three you'd bet money on. Add the fourth when it earns it.

Declaring where your agent's authority ends

Production-grade cards state constraints explicitly: spend caps, rate limits, and the boundary between what the agent does alone and what needs human approval. This isn't a formal field in the schema so much as a discipline applied across your descriptions.

Write it plainly in the skill description. “Issues refunds up to GBP 100 against orders under 30 days old; anything above either threshold is routed to a human reviewer and answered within one business day.” A client agent reading that can set its own expectations rather than discovering your limits through failed calls. The same thinking that goes into your escalation rules for email applies here, except the audience is a machine that will retry.

Refund and billing authority is about to get more contested, not less. AP2, the agentic payments protocol that shipped alongside A2A v1.0, exists precisely so that agents can carry payment authorisation across organisational lines. Decide your position before a partner asks.

Sign the card, or don't bother publishing it

An unsigned Agent Card is a claim with nothing behind it. Anyone can stand up a lookalike domain, serve a card naming your company, and collect whatever a trusting client sends.

The spec handles this with an AgentCardSignature: a JSON Web Signature (RFC 7515) computed over a canonicalised form of the card using the JSON Canonicalization Scheme (RFC 8785), so the signature stays stable no matter which serialiser produced the JSON. Clients verify the signatures field against your public key before trusting anything in the document.

Separately, securitySchemes declares how a client should authenticate. OAuth 2.0 with client credentials is the usual enterprise answer because it plugs into identity infrastructure you already run and scopes cleanly at the skill level. API keys are easier to stand up and harder to rotate at scale. OpenID Connect is the right choice when the agent needs to act for a specific named user rather than an organisation. Whatever you choose, the card declares the scheme and never carries the secret.

Two cards: the public one and the partner one

Set capabilities.extendedAgentCard to true and authenticated clients can request a richer card through GetExtendedAgentCard. This is the shape most support organisations should aim for.

The public card stays thin. A few read-oriented skills, clear scope, honest limits. The extended card, visible only to partners who've authenticated, carries the write actions, the higher spend caps, the skills tied to contractual relationships. It's the difference between what you tell a stranger at the door and what you tell a supplier with a signed agreement.

A first card worth shipping

Imagine a mid-sized UK retailer doing roughly 40,000 support emails a month, mostly delivery and returns. Their first card has three skills and takes an afternoon to specify.

1. order-status-lookup: takes an order number and a verified email address, returns current status, carrier, tracking reference and expected delivery date. Read-only. Tagged orders, delivery, tracking
2. return-eligibility-check: takes an order number and item SKU, returns whether the item is inside the returns window, whether it's excluded by category, and what the customer would get back. Read-only, and it says nothing about initiating the return
3. invoice-copy-request: takes an order number, sends a VAT invoice to the address on the account. Write, but the blast radius is one email

Notice what isn't there. No refunds, no address changes, no cancellations. Read-first skills fail safely: the worst outcome is a stale answer, not money moving to the wrong place. Once those three run clean for a quarter, the retailer knows its integration latency, its error rates and its real authentication load, and adding return-initiate becomes an informed decision rather than a hopeful one.

The read-only ones also happen to cover the highest-volume queries in almost every consumer business. Delivery status alone is often 30–40% of the inbound queue, which is why WISMO automation is where most teams see the first real dent in workload.

The operational details that decide whether any of it works

• Serve at /.well-known/agent-card.json over HTTPS, publicly reachable, with CORS headers set
• Prefer Content-Type: application/a2a+json; application/json is accepted
• Keep the legacy /.well-known/agent.json path alive while older clients still check it
• Validate the card in CI against the v1.0 schema so a bad deploy can't make you undiscoverable
• Use semantic versioning and keep a lastUpdated timestamp current, since orchestrators poll for changes

Log every fetch of the card and every skill invocation with the same rigour you'd apply to audit trails on human-facing support. When a partner asks why their agent got a rejection in March, the card version they read is part of the answer.

Where this is still immature

Being honest about the gaps matters more than sounding confident. There is no universal registry yet, so discovery in practice is still mostly out-of-band: a partner sends you a URL, or you send them one. A valid signature proves who served the card, not that the agent behind it behaves well. And liability when a foreign agent acts on your published skill and something goes wrong is genuinely unsettled.

Volume is the other open question. One human sends one email; their agent might send ten structured queries to get the same answer, which has consequences for both your infrastructure and your pricing model. Worth modelling before you publish, not after.

None of that is a reason to wait. It's a reason to publish a small, honest, signed card and grow it.

Where Robylon fits

Robylon runs the agent side of this: 60+ write-access integrations so an agent can complete an action rather than describe one, human-in-the-loop escalation with tone-shift detection for anything past its authority, and 60–80% autonomous resolution on email validated against historical tickets during onboarding. The card describes what your support agent can do. The integrations decide whether that description is true. Teams building toward cross-boundary agent traffic usually start with multi-agent workflows inside their own system before opening a door outward, and that's the right order.

Ready to make your support agent something another agent can actually call? Robylon AI resolves 60–80% of customer emails autonomously with agents that take action across Zendesk, Shopify, Stripe, Salesforce and 60+ other integrations. Start free at robylon.ai