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

# AI Harnesses

> Hand a live chat or SMS conversation from your Flowyte agent to your own operator agent — Hermes, OpenClaw, or any runtime — which talks back and forth with the customer, then resolves or returns to the AI.

An **AI Harness** lets your Flowyte agent hand a live conversation to your **own** operator agent.
When a chat or SMS conversation meets a rule you set, Flowyte opens a durable **escalation** and
notifies your harness (Hermes, OpenClaw, or any runtime you build). Your harness **claims** the
conversation and talks back and forth with the customer **in the same thread**, then **resolves** it,
**returns** control to the Flowyte AI, or **asks for a human**.

Flowyte owns the conversation record and keeps enforcing compliance; your harness is a participant.
It reaches the customer in their original thread — a chat widget shows a "specialist has joined"
divider; an SMS thread continues as a normal text.

## Set it up

<Steps>
  <Step title="Connect your harness">
    In **Integrations**, connect your AI Harness provider (`hermes` or `openclaw`). The escalation
    surface stays hidden until at least one harness is connected.
  </Step>

  <Step title="Create a connector key">
    Mint a scoped API key for your harness in the dashboard's **Developer** page, granting only the
    `escalations:*` scopes it needs (see the [connector reference](/integrations/ai-harness-connector)).
    A connector key can work conversations but can't edit your destinations or agents.
  </Step>

  <Step title="Add a destination">
    Register where conversations go: `POST /escalation-destinations` with your harness's `endpoint_url`
    and the channels it handles (`chat`, `sms`, or both). The response returns a **signing secret**
    (`whsec_…`) **once** — store it; your harness verifies webhook signatures with it. The destination
    starts `unverified`.
  </Step>

  <Step title="Run the handshake test">
    `POST /escalation-destinations/{id}/test` opens a sandbox escalation and calls your endpoint.
    Your harness must **receive → claim → reply → resolve** within the window. Only a green run flips
    the destination to `active`; the response reports a step-by-step ledger with a hint on failure.
  </Step>

  <Step title="Set the agent's escalation policy">
    `PUT /agents/{id}/escalation-policy` sets an ordered list of rules — *when* to escalate and *where*
    to route. Rules match on deterministic conditions (an explicit request for a person, a human
    request, business hours, channel, a failed tool or knowledge lookup) and route to an `active`
    destination, an email fallback, or a queue.
  </Step>

  <Step title="Publish the agent">
    The policy edits the agent **draft**. [Publish](/get-started/draft-vs-published) so live phone and
    chat traffic use it.
  </Step>
</Steps>

<Note>
  The policy is **per agent** — two agents in one organization can route to entirely different harness
  destinations. Destinations are shared organization-level infrastructure; the policy decides which
  agent uses which.
</Note>

## What runs a conversation

Once a destination is `active` and a policy rule matches, a live conversation follows this loop:

1. Flowyte opens an escalation and sends your harness a **signed webhook** naming the `channel` and a
   short reason.
2. Your harness **claims** the escalation, reads the handoff context (a transcript window plus the
   escalation reason and any verified identifiers), and starts replying.
3. Each reply reaches the customer in their original thread; each customer message is forwarded to
   your harness. While your harness owns the thread, the Flowyte AI stays silent.
4. Your harness ends the conversation — **resolve** (done), **return** (hand back to the AI, which
   resumes on the next customer message), or **request a human** (routes to your human fallback).

Building the harness side? See the [connector reference](/integrations/ai-harness-connector) for the
signed-webhook, claim, reply, and resolve contract.

## Rules to know

<Warning>
  **SMS is customer-initiated only.** Your harness can reply inside an SMS conversation the customer
  started, but it **cannot open one**. Outbound initiation is coming soon, tied to Flowyte's outbound
  campaign rules.
</Warning>

<Note>
  * **SMS requires registration.** Enabling the `sms` channel on a destination requires your
    organization's completed **A2P 10DLC (TCR) registration** — the same registration your inbound SMS
    number already needs. See [SMS](/channels/sms).
  * **Plan.** Harness conversations are included on **Starter and above**. Setting up destinations and
    running the handshake test work on any plan, so you can wire everything up before you upgrade.
  * **Compliance stays with Flowyte.** Opt-out, quiet hours, and consent are enforced on your harness's
    replies exactly as they are on the AI's — a reply to an opted-out recipient is suppressed, and a
    quiet-hours send is held.
  * **One owner per thread.** A conversation has at most one non-AI owner at a time, so a harness and a
    human seat can never both hold the same thread.
</Note>

## In the API

The escalation endpoints are in the [API Reference](/api-reference/introduction). Configuration
endpoints (destinations, policy) work on any plan; the runtime endpoints are what your connector uses.

| Action                                | Endpoint                                                        | Scope                                     |
| ------------------------------------- | --------------------------------------------------------------- | ----------------------------------------- |
| List / register destinations          | `GET` · `POST /escalation-destinations`                         | `escalation_destinations:read` / `:write` |
| Update a destination                  | `PATCH /escalation-destinations/{id}`                           | `escalation_destinations:write`           |
| Run the handshake test                | `POST /escalation-destinations/{id}/test`                       | `escalation_destinations:write`           |
| Rotate a destination's signing secret | `POST /escalation-destinations/{id}/rotate-secret`              | `escalation_destinations:write`           |
| Read / set an agent's policy          | `GET` · `PUT /agents/{id}/escalation-policy`                    | `escalation_policies:read` / `:write`     |
| List / read escalations               | `GET /escalations` · `GET /escalations/{id}`                    | `escalations:read`                        |
| Claim an escalation                   | `POST /escalations/{id}/claim`                                  | `escalations:claim`                       |
| Reply to the customer                 | `POST /escalations/{id}/messages`                               | `escalations:respond`                     |
| Resolve / return / request human      | `POST /escalations/{id}/resolve` · `/return` · `/request-human` | `escalations:resolve`                     |

Authenticate every call with `Authorization: Bearer flowyte_sk_…`. You can also drive the same
surface over the [MCP gateway](/get-started/mcp-gateway) — the escalation tools map one-to-one onto
these endpoints.

Next: the [connector reference](/integrations/ai-harness-connector) for building the harness side.