A2A agent framework

Every opted-in published profile serves its Agent Card at:

https://button.contact/{slug}/.well-known/agent-card.json

The card declares an A2A 1.0 JSON-RPC interface, an opaque tenant UUID, public skills, supported media, and no streaming or push capabilities. It uses standard caching headers and an ETag. Send A2A-Version: 1.0 when the client uses version negotiation. Every method must include the opaque tenant value from the selected interface; it routes the shared platform endpoint to the correct profile without creating a separate server process.

Methods

The interface implements SendMessage, GetTask, ListTasks, and CancelTask. Read-profile and knowledge-search tasks can complete immediately. When the page owner enables A2A access and assigns a published Agent, ask-contactbutton-agent answers a read-only question through ContactButton’s server-side runtime. It applies the same ordered behavior rules as hosted chat and REST without publishing the owner-authored rule text. Material skills resolve through the same capability registry and action state machine used by web chat, REST, and MCP:

TASK_STATE_INPUT_REQUIRED returns missing fields and the current input schema.
TASK_STATE_AUTH_REQUIRED returns a ContactButton review URL after a proposal is stored.
TASK_STATE_WORKING means the verified action is being executed.
TASK_STATE_COMPLETED, TASK_STATE_FAILED, and TASK_STATE_CANCELED mirror the linked action result.

An A2A client cannot approve the action or receive an OTP. Poll GetTask after the represented visitor completes the ContactButton review. CancelTask cancels the linked action while it is still mutable.

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "SendMessage",
  "params": {
    "tenant": "<page-uuid>",
    "message": {
      "messageId": "msg-01",
      "role": "ROLE_USER",
      "parts": [{"text": "How can I contact this business?"}]
    },
    "metadata": {"skill": "read-contact-profile"}
  }
}

Message IDs make sends idempotent per profile and link at most one A2A task to one action request. Context IDs are opaque and contain no email address, URL, or free-form user text. Streaming and push notifications remain disabled; use polling. For a server-enforced Agent answer, select the ask-contactbutton-agent skill and optionally pass an assigned Agent public ID:

{
  "jsonrpc": "2.0",
  "id": "request-2",
  "method": "SendMessage",
  "params": {
    "tenant": "<page-uuid>",
    "message": {
      "messageId": "msg-02",
      "role": "ROLE_USER",
      "parts": [{"text": "What is your refund policy?"}]
    },
    "metadata": {
      "skill": "ask-contactbutton-agent",
      "agent_id": "<optional-agent-uuid>"
    }
  }
}

The answer creates one canonical ContactButton conversation for attribution and diagnostics. Mutation tools remain disabled. An owner-configured automation may create a ContactButton-owned proposal, and a handoff rule may offer human help, but the A2A client receives only an authorization-required task and review URL. It cannot approve the proposal, request the handoff on the visitor’s behalf, receive an OTP, or execute an action. The task artifact includes the versioned Agent protocol contract, so clients can map the same lead-capture, handoff, automation, and action states used by hosted web, REST, and MCP.

Agent onboarding

Protocols

Methods

​Methods

Methods