Skip to main content
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 with permissions, and optionally a pinned connection and knowledge. Authoring happens in the dashboard — see Your 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:
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, so the same version your product names can be reached from your users’ own AI clients once its connection carries a login bridge.

​
States

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

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