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

# Connectors & Capabilities

> The ConnectorCapability model, risk tiers that drive the review gate, and what the engine can do across marketing, service, operations, and finance.

# Connectors & Capabilities

Every action the agent can call is a **`ConnectorCapability`** — a
`(connector_type, connector_action, activity_name, risk)` tuple in the registry, exposed at:

```
GET /v1/connectors/capabilities
```

A brand's `AutomationConfig.tool_definitions` selects which capabilities that brand's agent may
call, with per-tool params, idempotency keys, and policy caps.

At runtime the LLM emits a tool call → generic connector dispatch routes it to the activity →
the result re-enters the deterministic workflow.

<Note>
  Adding a system is **data, not code**: one connector plus N capability rows. Dispatch,
  idempotency, the review gate, and spend caps all apply automatically by risk tier — so breadth
  doesn't erode safety.
</Note>

## Risk tiers

Risk tier is the mechanism that connects capability breadth to the review gate and policy
controls.

| Tier               | Meaning                                           | Default handling                          |
| ------------------ | ------------------------------------------------- | ----------------------------------------- |
| `Read`             | No side effects                                   | Auto-allowed                              |
| `Write`            | Non-destructive write, e.g. a portal link         | Auto-allowed                              |
| `OperationalWrite` | Changes order, subscription, or fulfillment state | Review-gateable, idempotency-keyed        |
| `FinancialWrite`   | Moves money — refund, invoice, payment            | **Review gate plus spend cap by default** |

<Warning>
  A new `FinancialWrite` or `OperationalWrite` capability inherits gate and cap behavior
  automatically — but only if the tier is set correctly. Mis-tiering a money-moving action as
  `Write` silently removes both protections.
</Warning>

## Coverage

**99 agent-callable capabilities** in the registry.

| Domain               | Actions today                                                                                                | Maturity                |
| -------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------- |
| **Customer service** | Gorgias and Zendesk as agent tools — get, reply, tag, status, update — plus lookups                          | Strong                  |
| **Operations**       | Orders, subscriptions (Recharge, Stay, Skio), returns, ERP, and five shipping/3PL providers (status, cancel) | Strong                  |
| **Finance**          | Refunds (Shopify, Stripe), NetSuite, Xero                                                                    | Strong                  |
| **Marketing**        | Klaviyo (profile, list add/remove) plus KB search                                                            | Live, thinnest coverage |

The engine covers the **highest-risk, highest-value commerce and finance actions** — the ones
that move money or order state. The breadth gaps are in marketing reach and fulfillment
execution.

Remaining build work (not just registration): Klaviyo campaigns and flows, ShipStation label
and rate creation, Amazon SP-API, and Stripe disputes and payouts.

## StateSet-native connectors

The engine drives StateSet's own managed infrastructure as first-class connectors, so a brand
can run these *on the engine*:

| Action                           | System                                           | Risk             | Use                                                                                   |
| -------------------------------- | ------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------- |
| `stateset_mail.send_email`       | [Managed support email](/stateset-mail/overview) | Write            | Agent replies to a customer inquiry through the managed mail backbone, threaded       |
| `inbox.received` → RAv2          | Managed support email                            | —                | `POST /v1/integrations/{brand}/stateset-mail/webhook` starts the agent on a new email |
| `stateset_edi.send_document`     | [EDI (X12)](/stateset-edi/overview)              | OperationalWrite | Send an 855, 856, 810, or 940 to a trading partner mid-workflow                       |
| `stateset_edi.validate_document` | EDI (X12)                                        | Read             | Pre-send X12 validation                                                               |

Together these close the **managed support email loop** — connect a domain, inbound email
arrives, the agent acts, the reply threads back — and add **agentic X12 automation**, both on
the same deterministic engine and risk-gated dispatch.

## Adding capabilities

1. **Register the connector and its capability rows.** The deterministic engine, dispatch,
   idempotency, review gate, and spend caps apply automatically by risk tier.
2. **Set the risk tier honestly.** This is the only place the safety behavior is decided.
3. **Measure with the scorecard.** Every capability's outcomes flow into per-brand and fleet
   quality scorecards, so expansion stays evidence-driven.

## Related

* [ResponseAutomationV2](/next-temporal/workflow) — the tool-use loop that calls these
* [Policy Engine & Decision Gate](/next-temporal/policy-engine) — what authorizes a mutating action
* [Configuration](/next-temporal/configuration) — `tool_definitions` and policy controls