Designing an Agent Card for Your Support Organisation

An agent card is a JSON file at a well-known path on your domain that tells any other AI agent what yours can do and how to reach it. It is maybe forty lines long. It is also the most consequential forty lines your support organisation will publish this decade, because it is a public specification of what a stranger's software can make your systems do.

Almost nobody has written about how to design one for support. So here is the practical version.

What is actually in the file

A2A cards live at /.well-known/agent-card.json, which follows the same convention as robots.txt or security.txt. If you have ever published an OpenAPI spec, the instinct transfers cleanly.

The card carries five things that matter:

• Identity. Who you are, what the agent is called, and a URL that resolves back to your organisation.
• Skills. The discrete capabilities you are advertising, each with a name, a description, and enough detail that a stranger's agent can decide whether to call it.
• Endpoint. Where tasks get submitted, and which transport bindings you support.
• Authentication. What credential scheme you expect, and how a counterparty obtains one.
• Signature. Since v1.0, cards can be cryptographically signed so the other side can verify the card belongs to you.

Worth knowing before you start: a review of publicly discoverable cards in mid 2026 found that a large share of files calling themselves agent cards were not valid A2A at all. Broken paths, missing required fields, made-up schemas. The bar for being in the top decile here is genuinely low, which is good news if you are starting now.

Step 1: Inventory what your agent can already do

Before deciding what to publish, write down every action your support automation can currently take. Not what the vendor brochure says. What it does in production, today, against real accounts.

For most teams running action-taking automation the list looks something like: read order status, read account and subscription state, look up a shipment, cancel an order inside a window, issue a refund up to some limit, update a delivery address, apply a credit, create or update a ticket, escalate to a human queue.

Sort that list into three buckets by blast radius:

1. Read-only. Nothing changes. Worst case is disclosing information to someone who should not have it, which is a real risk but a bounded one.
2. Reversible writes. Address changes, ticket creation, appointment rescheduling. Wrong outcomes are annoying and fixable.
3. Irreversible or financial. Refunds, cancellations, credits, anything touching payment instruments. Wrong outcomes cost money and sometimes cost the relationship.

This sort is the whole design exercise. Everything after it follows.

Step 2: Decide the public and gated split

Here is the recommendation, stated plainly because hedging helps nobody: publish bucket one openly, gate bucket two, and keep bucket three off the card entirely for your first version.

Read operations can be advertised to anyone, because the authentication layer still governs whether a given caller sees a given account. Reversible writes go behind an authenticated relationship, meaning a counterparty you have onboarded rather than any agent that finds your domain. Financial actions stay out of the manifest at first, not because they can never be automated, but because publishing them turns your refund threshold into a documented target.

There is a real cost to this conservatism. A customer's agent that could have resolved a refund in one exchange now waits for a human. You are trading resolution speed for a smaller attack surface, and for the first year of this technology that is the right trade. Revisit it when you have logged six months of counterparty behaviour and know what normal looks like.

What you should not do is publish a permissive card because a competitor did. Being first to expose a capability is not an advantage if the capability was not ready.

Step 3: Write skills a stranger can act on

Skill descriptions are the part teams rush and then regret. The reader is another company's agent, which has no context about your business, your product names, or your internal jargon.

Bad: Handles WISMO queries via the OMS. That is three pieces of internal shorthand in six words.

Better: Returns current fulfilment status and expected delivery window for an order, given an order reference and the account email associated with it.

The pattern that works: say what comes back, say what you need to be given, and say the boundary. A few rules that hold up in practice:

• Name the inputs precisely. If you need an order reference in a specific format, say so in the description rather than letting the caller discover it through failed attempts.
• State what you will not do. A skill that reads order status but cannot modify it should say that. Explicit limits prevent a caller from constructing a plan around a capability you do not have.
• Keep skills narrow. One skill that does five things is harder to reason about, harder to rate-limit, and impossible to withdraw selectively when one part breaks.
• Avoid marketing language. Nothing in a card should read like a landing page. The audience cannot be persuaded and will not be impressed.

Narrow skills also give you a per-skill kill switch, which is the single most useful operational property of a well-designed card. If one capability turns out to be exploitable, you withdraw that skill and leave the rest running.

Step 4: Sign it, and mean it

Signed cards were the headline addition in v1.0, and they exist because an unsigned card is just a file on a domain making claims. Signing lets a counterparty verify cryptographically that the card is yours.

Two obligations come with this. Your signing key needs the same handling as any other production secret, which means rotation, restricted access, and an owner. And you need to decide what your own agent does when it encounters an unsigned or unverifiable card from someone else. The safe default is to treat an unverifiable card as an untrusted claim and refuse to act on anything beyond read operations.

Step 5: Version before you need to

Cards change. Skills get added, descriptions get corrected, limits get adjusted. The failure mode is a counterparty that cached your card in March and is still constructing requests against a capability you removed in June.

Put a version identifier in the card from day one, log which version was in effect when each inbound task arrived, and give yourself a deprecation window rather than removing a skill the day you decide to. Our guide to audit trails for AI support covers the logging baseline; card version belongs in that record alongside counterparty identity.

A conservative starter card, described

If you want a shape to copy, this is what a sensible first support agent card advertises:

• Order status lookup. Given an order reference and account email, returns fulfilment state, carrier reference, and expected delivery window. Read-only, publicly advertised.
• Policy retrieval. Returns current return windows, warranty terms, and eligibility rules in structured form. Read-only, public, and genuinely useful because it stops agents quoting a cached version of your help centre back at you.
• Ticket creation. Accepts a structured issue description and returns a reference. Authenticated, rate-limited, reversible.
• Escalation request. Routes a case to a human queue with supplied context and returns an expected response window. Authenticated.

Four skills. Nothing that moves money. That card is boring, defensible, and considerably more capable than what most support organisations expose today, which is nothing.

What to withhold, and why

Some things should stay off the card even once you are comfortable with the technology.

Do not advertise your authority thresholds. A skill can exist without the manifest stating that refunds under $200 clear automatically. Do not advertise internal routing structure, queue names, or team topology, because it is reconnaissance value with no caller benefit. Do not expose bulk or enumeration capabilities, meaning any skill that could be used to walk your account space rather than answer about one account.

And be careful with anything that reveals whether an identifier exists. A skill that returns a clean error for an unknown order and a different error for an order that exists but belongs to another account has just become an account enumeration tool. The broader version of this thinking is in our enterprise security checklist for AI email support.

Where this sits relative to everything else

The card is discovery and delegation. It is not how your agent reaches your own systems, which runs over MCP and your own credentials, and it is not a replacement for the email channel that will carry most machine traffic for the next few years. If the protocol split is still fuzzy, the A2A and MCP explainer covers it, and the machine inbox covers what arrives before any of this is standardised.

Robylon's approach here is to hold capability exposure as a customer decision rather than a platform default. The action layer across 60+ write-access integrations is what makes a card worth publishing at all, since an agent that can only answer questions has nothing meaningful to offer a counterparty. What gets advertised, at what limits, behind what authentication, stays configurable rather than shipped on by default.

Start with four read-heavy skills and a signature. You can always add.

Frequently Asked Questions

What is an agent card in the A2A protocol?

An agent card is a JSON manifest published at a well-known path on your domain that advertises an AI agent's identity, its skills, its endpoint, and how to authenticate against it. It works as the discovery layer for agent-to-agent communication, in roughly the way robots.txt or an OpenAPI spec works for other systems. Since A2A v1.0 the card can also be cryptographically signed, letting a counterparty verify the file genuinely belongs to the organisation it names.

What should a support agent card not advertise?

Keep financial and irreversible actions off your first version, including refunds, cancellations, and anything touching payment instruments. Never publish your authority thresholds, since stating that refunds under a certain value clear automatically documents a target for anyone probing the boundary. Also withhold internal queue names and routing structure, and avoid any skill that could be used to enumerate accounts or confirm whether a given identifier exists.

Do agent cards need to be signed?

Signing is optional in the specification but should be treated as mandatory in practice. An unsigned card is an unverified claim that a file on a domain belongs to a particular organisation, which is not a basis for granting access. Signing requires the same key handling as any production secret, including rotation and a named owner. Decide separately what your own agent does with unverifiable inbound cards, with the safe default being read operations only.

How many skills should a first agent card include?

Three to five, all narrow. A useful starter set is order status lookup, structured policy retrieval, ticket creation, and escalation routing. Narrow skills are easier to rate-limit, easier to describe accurately to a stranger's agent, and give you a per-skill kill switch so one exploitable capability can be withdrawn without taking the whole endpoint down. Broad multi-purpose skills fail all three of those tests.

How do you handle changes to a published agent card?

Include a version identifier from the first release and log which version was in effect for every inbound task, alongside the counterparty identity. Counterparties cache cards, so a skill removed today may still be called next month by an agent working from stale discovery data. Give deprecated skills a stated deprecation window rather than removing them immediately, and keep returning a clear structured error afterwards rather than failing silently.

Ready to build a support agent worth publishing a card for? Robylon AI resolves 60-80% of customer emails autonomously with AI agents that take action across Zendesk, Shopify, Salesforce, HubSpot and 60+ other integrations. Start free at robylon.ai