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

# Agents

> What you authored — instructions, a model, patches, and guardrails. Named by a public id that pins one exact version.

An agent is the unit you publish and your users talk to. It carries a system prompt, a model class, a set of wired [patches](/guides/patches) with permissions, and optionally a pinned [connection](/guides/connections) and knowledge.

Authoring happens in the dashboard — see [Your first agent](/first-agent). This page is about how an agent behaves once published.

## Public ids pin a version

Every published agent version gets its own id:

```
agent_4f3ca81b9d2e7f60...
```

That id names **one exact version**. There is no latest-resolution and no aliasing — the lookup is exact, scoped to your workspace. Publishing a new version mints a new id, and your integration keeps running the old one until you change the string in your code.

This is deliberate. A prompt change cannot alter the behaviour of a running integration without someone opting in.

Publishing also opens the agent's [MCP URL](/guides/mcp), so the same version your product names can be reached from your users' own AI clients once its connection carries a login bridge.

## States

| State | Meaning |
| - | - |
| `draft` | Being authored. Cannot be named by a thread. |
| `published` | Live. Has a public id and can run. |
| `archived` | Retired. Existing threads keep their history; new threads are refused. |

Naming an unknown, unpublished, or archived agent returns `404 unknown_agent`.

## What every agent can do

Four primitives are injected automatically, whether or not you wire anything:

* `ask_user` — ask a free-text question and pause
* `ask_choice` — offer options and pause
* `confirm` — ask for a yes or no
* `handoff` — hand the conversation back to your app

Three more appear conditionally: `load_knowledge` when the agent can reach an indexed knowledge block, and `remember` and `recall` when the run has a [subject](/guides/subjects) with memory available.

So an agent with an empty patch list is still conversational. It just cannot act.

## Linking knowledge and tools

Inside a knowledge block's body, or in an agent's system prompt, typing `@` links to a patch or to another knowledge block. A link is stored as ordinary markdown — `[Refund policy](knowledge:refund-policy)` or `[Issue refund](patch:issue_refund@1.0.0)`.

At run time the agent never sees that syntax. It reads `Refund policy (load with load_knowledge("refund-policy"))` for a block it can reach, and `Issue refund (tool: issue_refund)` for a tool it wires. If it does not wire that tool, it is told the tool is not available and to tell the user the step needs a person, rather than improvise.

A block mentioned by the agent's instructions, or by a block it already has, becomes reachable too — it joins the knowledge index without being wired directly, whatever its own mode. That is why `load_knowledge` can appear for an agent with no knowledge wired at all.

Reach is followed two links deep from the instructions or from a wired block, and stops at 20 extra blocks per agent. A mention inside a code span or a fenced block is left alone, so a block can document this syntax without the example becoming a live reference.

**A mention never grants a tool.** Naming a patch declares that a procedure depends on it; wiring it in the agent is still what allows the call.

## Model class

`Fast`, `Standard`, or `Frontier`. The class sets the trade-off between latency, capability, and credits burned per turn. Standard is the right default; move up when the agent has to reason over many tools or long context, down when it is doing something narrow and high-volume.

The class used on each model call is recorded per turn in the [trace](/guides/traces).

## Connections

If an agent wires a patch that calls your backend and that patch has no connection pinned to it, the agent needs a connection resolved at request time — from `Patchwork-Connection` in relay, or the `conn` claim in direct. Without one you get `422 connection_required`.

An agent built only from primitives and workbench products never needs one.

## Snapshots

Every run records an `agent_snapshot` — the exact spec that was in force when the run started. Change the agent afterwards and old traces still show what actually ran. When you are debugging a run from last week, that snapshot is the truth, not the agent as it stands now.


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