Design an Agent-Callable Action: Schema, Idempotency, Scoped Auth and Receipts

#ai #api #architecture

If you want an AI agent to act on your service without driving your web UI, the useful unit is one well-defined action. This is a design note, not a claim about any vendor's product.

Why not just let the agent use the page

A screen has no contract. A change in a button label or a modal can break the flow, and every page the agent reads can contain text written to mislead it. Anthropic's write-up on browser use says prompt injection is a real, unsolved risk for agents that read web pages. A narrow action reduces what an agent reads and what it can do.

Keep a browser path as a fallback for things you cannot expose. Do not pretend it does not exist.

1. Describe the action as a schema

{
  "action": "book_appointment",
  "inputs": {
    "service_id": "string, from /services",
    "start_time": "ISO 8601, must be an open slot",
    "customer_ref": "string, issued by your auth"
  },
  "result": {
    "booking_id": "string",
    "status": "confirmed | rejected",
    "reason": "string, only if rejected"
  }
}

Fixed fields beat free text. The caller cannot invent a service that does not exist, and you can reject bad input with a clear error.

2. Make retries safe with an idempotency key

Agents retry. Networks fail. Ask for a key on every action that changes something.

POST /book
Idempotency-Key: 7f3c-example

If the same key arrives twice, return the first result and do not book twice.

3. Scope the permission

Give the agent a credential that can do only this action, for this customer, for a limited time. Do not hand over a full account login. If the action can spend money or send a message, require the customer to confirm it.

4. Return a receipt

Every successful action returns an ID and a plain summary the agent can show the customer: what was done, when, and how to undo it.

5. Log the call

Record who asked, what was asked, and what you returned. When an agent and a customer disagree, this is the record.

Where it is heading

Google's Universal Commerce Protocol guide describes an open standard for agentic actions, starting with direct buying in AI Mode in Search and Gemini. Whether you use that or your own endpoint, the same four pieces apply.

Limits

Many services have no API today, and for them a browser is the only route. An API with a broad key is also not safe. The design above is a starting point I think is worth testing.

I'm Tej Pandya, founder of GrowEasy.ai.

DEV Community