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

# The Agent object

> What you authored. You reference it by public id; you do not create it over the public API.

Agents are authored and published in the dashboard — see [Your first agent](/first-agent). Over the public API you only ever name one, and read a small embedded form of it.

## The id

```
agent_4f3ca81b9d2e7f60…
```

`agent_` plus 32 hex characters. It names **one exact published version** — an exact lookup, scoped to your workspace, with no latest-resolution. Publishing a new version mints a new id.

Pass it when creating a thread:

```json theme={null}
{ "agent": "agent_4f3ca81b9d2e7f60…" }
```

A published agent also carries an `mcp_url` built from the same id — the address a user's own AI client connects to. See [MCP export](/guides/mcp).

```
https://api.usepatchwork.co/mcp/agents/agent_4f3ca81b9d2e7f60…
```

The URL exists for every published version, but the door only opens once the agent's connection has a login bridge.

## As embedded in a thread

```json theme={null}
{ "agent": { "name": "Support assistant" } }
```

<ResponseField name="name" type="string">
  The agent's name, as authored.
</ResponseField>

## As embedded in a trace

`GET /v1/loom/runs/:id/trace` returns `agent_snapshot` — the complete spec that was in force when the run started, including instructions, model class, and wired patches with their permissions.

Editing an agent does not rewrite history: an old trace shows the agent as it ran, not as it stands now.

## Errors

| Code | Status | When |
| - | - | - |
| `unknown_agent` | `404` | No published agent in this workspace with that id. |
| `agent_required` | `422` | Thread created without an `agent`. |


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