> ## 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.

# Patches

> A capability an agent can use. One of your endpoints, one of our products, or a built-in primitive.

A patch is not a bare API. It is a declaration: what the capability is called, what it takes, what it returns, how risky it is, and how it behaves when the agent uses it. That declaration is what the model sees, and what the runtime enforces.

Patches are authored under **Patches** in the dashboard, then wired into an [agent](/guides/agents).

## Three kinds of binding

| Binding | What it calls | Needs a connection |
| - | - | - |
| `customer_endpoint` | An endpoint you host | Yes, unless one is pinned on the patch |
| `api_product` | A Patchwork workbench product, like `extract` | No |
| `native_utility` | Something the runtime does itself | No |

Only the first reaches your infrastructure. An agent built entirely from the other two never needs a [connection](/guides/connections) — which is what makes the [Quick start](/quickstart) work with nothing hosted.

## Interaction

How the call behaves in the conversation:

| Interaction | Behaviour |
| - | - |
| `silent` | Runs and returns. The user sees the result in the agent's reply, not the call. |
| `interactive` | Pauses the run and asks the user something. |
| `handoff` | Hands the conversation to your app. |
| `proposed_action` | The agent proposes; **you** perform the action and report back. See [Outcomes](/guides/outcomes). |

`proposed_action` is the one people miss. It is for work Patchwork cannot do — something that must happen in your UI, or on a device, or by a human. The run waits in `awaiting_outcome` until you say what happened.

## Rendering a result

A patch can set **Render as** to a `kind` (e.g. `agents`, `table`, `card`). When it does, the patch's result is emitted as a [rich-message](/guides/messages#rich-messages) data block of that kind — structured data your UI renders — instead of only reaching the model. Leave it blank for a plain-text reply. It's optional and independent of everything else here.

## Risk

Every patch declares a base risk: `low`, `medium`, `high`, or `critical`. An agent can raise it but the effective level is never lower than the declaration.

Risk does not block anything by itself. It is recorded on every [tool call](/guides/tool-calls), surfaced in `pending_confirmation`, and is the natural input to how prominently your UI asks for approval.

## Writes and gates

A `customer_endpoint` patch bound to `POST`, `PUT`, `PATCH`, or `DELETE` is a write. Writes are where the guardrail matters, and the guardrail is the permission you set when wiring the patch to an agent:

| Permission | Behaviour |
| - | - |
| **Always allow** | Called whenever the agent decides to. |
| **Always ask** | Held. The run pauses for a human decision — see [Confirmations](/guides/confirmations). |
| **Always deny** | Visible to the agent, never callable. |

The same patch can be `Always allow` on one agent and `Always ask` on another. The permission belongs to the wiring, not the patch.

The permission is also what decides whether a write leaves the building: only an `Always allow` write is exported to a user's own AI client, because [that door cannot pause to ask](/guides/mcp#writes-export-but-only-deliberately).

## Built-in primitives

Seven patches ship with the platform and cannot be overridden — the keys are reserved:

| Key | Injected |
| - | - |
| `ask_user`, `ask_choice`, `confirm`, `handoff` | Into every agent, always |
| `load_knowledge` | When the agent has an indexed knowledge block |
| `remember`, `recall` | When the run has a [subject](/guides/subjects) with memory available |

Trying to author a patch with one of these keys is rejected.

## Redaction

A patch can declare fields to strip from results before they are stored or shown to the model. Use it for anything your endpoint returns that the agent has no business reasoning over — full card numbers, internal identifiers, tokens. Redaction applies to the stored [trace](/guides/traces) as well as the model's context.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.