Making your customer service agent-ready: a checklist

To make customer service agent-ready, give customers’ AI agents a direct, structured way to reach you. Publish an A2A Agent Card that lists the service tasks you accept. Define exact inputs for each task. Require authentication, check authorization per customer and per action, and hand hard cases to people with the full context attached. Keep records, rate-limit every operation, and test the whole path as an unknown client before you announce it.

The checklist below is in the order we suggest working through it. It assumes you already run some service systems, such as an order database, a booking tool or a help desk, and want agents to use them without going through your phone line or chat widget.

The checklist at a glance

#	Step	Done when
1	Choose the tasks	You have a short list, ranked by risk
2	Publish an Agent Card	The card validates and is served at the well-known path
3	Map tasks to skills	Each skill has a concrete description and examples
4	Define structured inputs	Every field is documented and validated
5	Authenticate clients	The card declares schemes; the server enforces them
6	Authorize per customer and action	Each task checks what this client may do for this customer
7	Plan human handoff	Out-of-policy tasks reach a person with context
8	Keep records	You can reconstruct any task later
9	Set limits	Every operation is rate-limited and size-limited
10	Test as a stranger	Conformance, errors and access checks pass for a fresh client

1. Choose the tasks

Start from requests you already handle every day, and sort them by what goes wrong if an agent gets them wrong.

Task type	Examples	Risk	Start here?
Read-only lookup	Order status, store hours, appointment availability	Low	Yes
Reversible change	Book or move an appointment, update a delivery window	Medium	Second
Money or account change	Refund, cancellation, address or payment change	High	Later, with strong authorization
Judgment call	Policy exceptions, disputes, complaints	High	Route to people

A first release with one or two read-only tasks is enough to prove the whole path.

2. Publish an Agent Card

The Agent Card is the JSON document that tells other agents who you are, where your endpoint is, what you can do, and how to authenticate. Serve it at https://your-domain/.well-known/agent-card.json with Content-Type: application/json, a Cache-Control max-age and an ETag.

Required fields in A2A v1.0: name, description, version, supportedInterfaces, capabilities, defaultInputModes, defaultOutputModes and skills. Declare only the optional capabilities you implement. If streaming is false or missing, the specification requires you to refuse streaming calls with UnsupportedOperationError, and the same pattern applies to push notifications and the extended card.

Tutorial: publish your first Agent Card walks through a minimal card, and the Agent Card validator checks yours against the specification. Agent Cards explained covers every field.

3. Map tasks to skills

Each entry in skills describes one family of tasks. A2A requests don’t name a skill: the client sends a message and your agent decides how to handle it. Skills tell the client, and the model inside it, what you do well and how to phrase a request.

Good skills are narrow and concrete. State the inputs, the limits, and what happens when something is missing. Include an example that shows a structured request.

Illustrative skill for returns:

{
  "id": "start-return",
  "name": "Start a return",
  "description": "Opens a return for one item from an order placed in the last 30 days. Send a data part with orderId, sku and reason (wrong_size, damaged, not_as_described, other). Returns a case ID and a prepaid label. If refundMethod is missing, the task asks for it.",
  "tags": ["returns", "orders", "support"],
  "examples": [
    "Start a return for order A-1001, item BOOT-42-BLK, wrong size.",
    "{\"orderId\":\"A-1001\",\"sku\":\"BOOT-42-BLK\",\"reason\":\"wrong_size\",\"refundMethod\":\"store_credit\"}"
  ],
  "inputModes": ["application/json", "text/plain"],
  "outputModes": ["application/json", "text/plain"],
  "securityRequirements": [
    { "schemes": { "partnerOAuth": { "list": ["returns:write"] } } }
  ]
}

The per-skill securityRequirements says this skill needs a narrower OAuth scope than read-only skills. The scheme name refers to an entry in the card’s securitySchemes (step 5).

4. Define structured inputs

Free text works for questions. For actions, ask for data parts with named fields, because a field can be validated and a sentence has to be interpreted.

• Document each field in the skill description: name, type, allowed values.
• Validate every input before acting. The specification says agents must validate all input parameters.
• Reject malformed requests with -32602 (invalid params), and say which field failed.
• Reject part types you don’t accept with -32005 (ContentTypeNotSupportedError).
• When a request is valid but incomplete, don’t fail it. Move the task to TASK_STATE_INPUT_REQUIRED and ask for exactly what is missing. The client answers on the same taskId.

Illustrative request from a customer’s agent:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-2c81",
      "role": "ROLE_USER",
      "parts": [
        { "text": "Start a return for the boots in this order." },
        {
          "data": { "orderId": "A-1001", "sku": "BOOT-42-BLK", "reason": "wrong_size" },
          "mediaType": "application/json"
        }
      ]
    }
  }
}

Illustrative response asking for the missing field, in both text and structured form:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "task": {
      "id": "task-77b2",
      "contextId": "ctx-4e19",
      "status": {
        "state": "TASK_STATE_INPUT_REQUIRED",
        "message": {
          "messageId": "msg-a310",
          "role": "ROLE_AGENT",
          "taskId": "task-77b2",
          "contextId": "ctx-4e19",
          "parts": [
            { "text": "Choose a refund method: original_payment or store_credit." },
            {
              "data": { "missingFields": ["refundMethod"], "allowed": { "refundMethod": ["original_payment", "store_credit"] } },
              "mediaType": "application/json"
            }
          ]
        },
        "timestamp": "2026-09-26T16:20:00Z"
      }
    }
  }
}

The task lifecycle guide covers the states and how multi-turn exchanges continue.

5. Authenticate clients

Authentication answers: which client agent is this? Declare your schemes in the card’s securitySchemes and list what callers must satisfy in securityRequirements. A2A v1.0 supports API keys, HTTP authentication such as bearer tokens, OAuth 2.0, OpenID Connect and mutual TLS.

For agents run by other companies, OAuth 2.0 with the client credentials grant (RFC 6749, section 4.4) is a common fit: each partner gets its own client ID, and you issue tokens with scopes such as orders:read or returns:write. Mutual TLS suits fixed B2B partners.

Rules that apply whatever you choose:

• The card must never contain a secret. It says which credentials to present; clients get them out of band.
• Servers must reject requests with missing or invalid credentials.
• Anything you want to show only to known partners, such as extra skills or per-partner limits, belongs in an extended Agent Card behind authentication.
• If callers need to verify that your card really came from you, sign it. See Signed Agent Cards.

6. Authorize per customer and per action

Authentication tells you the client. Authorization decides what that client may do, for which customer, right now. The specification requires authorization checks on every operation, and requires that task reads and lists return only what the caller may see. It also says you must not reveal that a resource exists to a caller who can’t access it, so answer requests for other clients’ tasks with “task not found” (-32001).

For actions on a customer’s account, you need evidence that the customer approved this action. A2A gives you the signal: move the task to TASK_STATE_AUTH_REQUIRED and explain what is needed. It does not give you the credential. Section 7.6.4 leaves the scope, format, validity and revocation of that credential to implementations or extensions, and says the state change itself must not be treated as authorization. Decide your own method, for example a one-time approval the customer confirms in your app, and document it.

Apply least privilege everywhere: narrow scopes per skill, short-lived tokens, and limits on amounts.

7. Plan human handoff

Some requests need a person: policy exceptions, disputes, emotionally difficult situations, and anything above the limits you set for automation. A2A has no dedicated handoff state, so design the handoff with the states it does have.

Situation	Suggested handling
A person will finish the task soon	Keep the task in TASK_STATE_WORKING, say so in the status message, and let the client poll with GetTask or receive push notifications if you support them
A person needs something from the customer	TASK_STATE_INPUT_REQUIRED with a clear message
The request is outside policy and won’t proceed	TASK_STATE_REJECTED with the reason and a human contact route

Whatever the state, open the case in your help desk with the full task history attached, so the person handling it never starts from zero. When the person decides, update the task so the client agent learns the outcome.

8. Keep records

When a customer disputes an outcome, you need to reconstruct what happened. For each task, keep:

• the client identity and the credential or scope it used;
• the customer authorization evidence, if any;
• the request, the messages exchanged, the artifacts returned, and the final state;
• timestamps for each state change.

The specification recommends audit trails for sensitive operations, and says logs must not include credentials or personal data unless required and protected. Set a retention period and enforce it. A2A itself defines no receipt that both sides sign; if you need one, it has to come from an extension or your own design.

9. Set limits

An open endpoint attracts automated abuse. OWASP lists unrestricted resource consumption as API4 in its 2023 API Security Top 10, and the A2A specification says agents should rate-limit all operations and limit message sizes.

• Rate-limit per authenticated client, and separately per IP for unauthenticated calls such as fetching the card.
• Cap body size, the number of parts, and text length per part.
• When a client exceeds a limit, respond with HTTP 429 Too Many Requests (RFC 6585) and a Retry-After header. The specification treats rate limiting as a system error and allows retry guidance.
• Monitor for unusual patterns, such as rapid task creation or excessive cancellations, and log authentication failures. The specification recommends both.

10. Test as a stranger

Test from outside, with the tools and credentials a new partner would have.

1. Card. Run the card through the Agent Card validator, by domain once it is live so the HTTP headers are checked too.
2. Conformance. Run the A2A Technology Compatibility Kit (a2aproject/a2a-tck), a test suite that checks implementations across the JSON-RPC, gRPC and HTTP+JSON bindings.
3. Manual walk-through. The A2A Inspector (a2aproject/a2a-inspector) connects to an agent, displays its card, and shows the raw JSON-RPC messages as you chat with it.
4. Access. With a fresh client that has no special grants, try to read another client’s task, call a write skill with a read scope, and skip the customer approval step. Each must fail.
5. Errors. Send malformed JSON, an unknown method, a bad historyLength, an oversized body, and a message to a finished task. Check each error code against the specification.
6. Multi-turn. Complete a task that goes through TASK_STATE_INPUT_REQUIRED, and one that goes through TASK_STATE_AUTH_REQUIRED.

To see a working server end to end, Tutorial: build an A2A server on Cloudflare Workers builds one with a real multi-turn task and every error path exercised with curl.

After launch

Keep your phone line and chat for people. Watch which skills agents actually call, where tasks stall in INPUT_REQUIRED, and which requests end in handoff. Those are the places to improve skill descriptions, add fields, or expose the next task on your list.