> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent protocol parity

> Understand the shared Agent controls, states, safety boundary, scopes, and intentional differences across hosted web, REST, MCP, and A2A.

ContactButton compiles one effective Agent configuration for hosted web chat, REST conversations, public page MCP, and A2A. The profile, enabled ordered rules, approved knowledge, lead-capture policy, handoff policy, and deterministic automations are applied on the ContactButton server for every answer.

## What is equivalent

| Control or outcome                              | Hosted web       | REST                           | Public MCP                       | A2A                                        |
| ----------------------------------------------- | ---------------- | ------------------------------ | -------------------------------- | ------------------------------------------ |
| Profile, tone, role, and answer length          | Applied          | Applied                        | Applied                          | Applied                                    |
| Enabled ordered rules                           | Applied          | Applied                        | Applied; rule text stays private | Applied; rule text stays private           |
| Published tenant-scoped knowledge and citations | Applied          | Applied                        | Applied                          | Applied                                    |
| Lead capture `input_required` state             | Inline UI        | JSON                           | Structured tool result           | `TASK_STATE_INPUT_REQUIRED`                |
| Handoff offer                                   | Inline UI        | JSON                           | ContactButton review URL         | `TASK_STATE_AUTH_REQUIRED` with review URL |
| Automation result                               | Inline card      | JSON                           | Structured tool result           | Task artifact                              |
| Material action review                          | ContactButton UI | ContactButton review lifecycle | Review URL only                  | Review URL only                            |

MCP and A2A never receive owner-authored rule text, an OTP, provider credentials, internal IDs, or approval authority. They receive redacted rule diagnostics and the same observable answer and action outcomes. This keeps configuration private while preserving behavioral parity.

Appearance, placement, sounds, session behavior, Custom CSS, and Custom JS are hosted-web presentation concerns. They are intentionally omitted where they have no meaning to a REST, MCP, or A2A caller. Safe visitor-facing presentation metadata remains available from the public Agent REST manifest.

## Inspect effective controls

An authenticated workspace client with `content:read` can inspect the complete tenant-scoped control manifest:

```http theme={null}
GET /v1/workspaces/{workspace_id}/agents/{agent_id}/controls
Authorization: Bearer <scoped-token>
```

The response combines the profile, ordered rules and version, knowledge readiness, handoff policy, automation rules and version, safe presentation metadata, and the current protocol contract. Use the dedicated write endpoints for updates; the manifest itself is read-only.

Tokens are checked against the selected workspace. Interactive MCP OAuth tokens must also be audience-bound to the Workspace MCP and have an active grant for that workspace. A missing scope returns `403`; a resource outside the workspace returns `404` without disclosing the other tenant.

## Shared states

The protocol contract currently uses version `2026-08-05` and publishes these canonical states:

* Lead capture: `ready`, `optional`, `deferred`, `input_requested`, `input_required`, `complete`
* Handoff: `unavailable`, `available`, `offered`, `waiting_for_human`, `human_joined`
* Action: `proposed`, `awaiting_verification`, `processing`, `completed`, `failed`, `cancelled`, `expired`
* Automation: `matched`, `proposed`, `unavailable`

A2A maps canonical action states to task states: proposals and verification become `TASK_STATE_AUTH_REQUIRED`, processing becomes `TASK_STATE_WORKING`, and terminal action states become their completed, failed, or canceled equivalents.

## Idempotency and errors

All REST action proposal, approval, confirmation, and cancellation mutations require an `Idempotency-Key`. MCP proposal tools require `idempotency_key`; A2A deduplicates `SendMessage` by page plus `messageId`. Repeating the same key and payload returns the existing result. Reusing a key with different input returns a conflict.

Handle errors as follows:

* `401`: authenticate or refresh the token.
* `403`: request the missing scope or workspace grant; do not retry unchanged credentials.
* `404`: the Agent, page, or action is unavailable in the resolved tenant context.
* `409`: refresh capabilities or status; availability, consent, or a version may have changed.
* `422`: correct the input against the current schema.
* `429`: back off using the response headers.

Always refresh capabilities before creating a material proposal. ContactButton revalidates tenant scope, consent, permissions, and live capacity again after human verification.