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

# Loom

> The operated agent platform — connections, patches, agents, and runs.

Loom is the product. You author an agent in the dashboard, then your users talk to it through your app.

A **run** is one conversation turn. The agent may ask a question, call a tool, or wait for you to confirm that a side effect happened. Every run has a **trace** — what the agent did, in order.

## Two integration modes

<CardGroup cols={2}>
  <Card title="Direct" icon="key" href="/guides/loom-direct">
    The browser talks to Patchwork. You mint a short-lived session token on your backend. Best when the agent is in your product UI.
  </Card>

  <Card title="Relay" icon="server" href="/guides/loom-relay">
    Your backend talks to Patchwork with a workspace API key. Best for Slack, WhatsApp, email, or any channel you already own.
  </Card>
</CardGroup>

Same agents. Same traces. Same patches. Different caller.

## Objects

| Object         | What it is                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------ |
| **Connection** | A named egress host — where Patchwork calls *your* tools. Created in the dashboard.              |
| **Agent**      | The operated assistant you authored — model, patches, tools, guardrails. Public id is `agent_…`. |
| **Thread**     | One conversation. Belongs to a subject (your user). Id is a UUID.                                |
| **Run**        | One turn of that conversation. Has a state and a trace. Id is a UUID.                            |
| **Patch**      | A capability the agent can use — a catalog tool, or a tool you host.                             |

## Run states

| State              | Meaning                                                               |
| ------------------ | --------------------------------------------------------------------- |
| `running`          | The agent is working.                                                 |
| `awaiting_input`   | The agent asked a question. Post the next message on the same thread. |
| `awaiting_outcome` | The agent called a tool you host. Confirm what happened.              |
| `closed`           | The turn finished.                                                    |
| `failed`           | The turn failed.                                                      |

## React SDK

If the agent lives in a React app, start with [`@usepatchwork/react`](https://www.npmjs.com/package/@usepatchwork/react):

```tsx theme={null}
import { PatchworkProvider, useAgent } from "@usepatchwork/react";

<PatchworkProvider
  url="https://api.usepatchwork.co"
  mint={async () => {
    const res = await fetch("/patchwork/mint", { method: "POST" });
    const { data } = await res.json();
    return data.token;
  }}
>
  <Chat />
</PatchworkProvider>
```

`useAgent` opens a thread, posts messages, and streams the run over Pusher. You still mint the session token on your backend — the SDK does not hold a workspace key.

<Note>
  The SDK is the fastest path for a product UI. [Direct](/guides/loom-direct) and [relay](/guides/loom-relay) are the HTTP contracts if you are not on React, or if you need a channel Patchwork does not render.
</Note>