> ## Documentation Index > Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt > Use this file to discover all available pages before exploring further. # Agents > Author a mutable Workspace-scoped Agent and run its immutable AgentVersions. An **Agent** is the mutable, Workspace-scoped resource you author. It has a stable `agent_…` ID and contains the configuration that defines its behavior: its name, model selection, system instructions, tools, MCP servers, Skills, and metadata. An Agent is not a process, a sandbox, or a Session. An **AgentVersion** is one immutable snapshot of that authored configuration. AgentVersions are immutable configuration history used to reproduce execution, not intermediate promotion artifacts. The Session event log remains durable execution truth. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Agent agent_… mutable head ├── AgentVersion 1 immutable ├── AgentVersion 2 immutable └── AgentVersion 3 immutable, current ``` ## Versions are automatic Creating an Agent creates AgentVersion 1. A material update to the Agent creates the next AgentVersion automatically. An update whose effective configuration is unchanged returns the current Version instead of creating duplicate history. There is no separate draft or publish step. The stable Agent identity stays the same while its immutable Version history grows. ## Compose capabilities in the console The console's Create Agent and Edit Agent dialogs configure the same fields the API accepts: * **Built-in tools** — the tools the Agent runtime provides. Leave the scope untouched for the platform default (every built-in tool enabled), or scope it per tool with an approval policy and optional web domain bounds. * **MCP servers** — named remote MCP endpoints with a default approval policy and optional per-tool overrides. * **Skills** — Skills from the Workspace catalog. Session admission freezes the Agent's references; eligible context selection resolves each reference and records its exact version and digest. An exact reference stays pinned; `latest` can select a newer version for a later accepted input. Retries retain the original selection. If its catalog row disappears, the Agent detail page flags it as unavailable until you remove or restore it. * **Selectable Skills** — Skills the agent may find and activate during a Session beyond the ones it starts with. `skill_selection` is either `listed` (up to 100 Skills, each at an exact version such as `"2"`, or `"latest"`) or `workspace` (any active Skill in the Workspace). An activation pins one exact version, and a listed exact version admits that version only: asking for a newer one is refused as not selectable, and a Skill that is not listed is refused. A Skill activated mid-turn becomes eligible for read-only staging from the next user-driven turn, never in the same turn. Missing, archived or mismatched activations can be withheld before selection; see the [Skill selection and retry boundaries](/concepts/skills#discover-relevant-skills) for availability and exact-input rules. Activation never grants tools, credentials, or egress. Saving an Agent with the key omitted keeps the stored selection, and `null` removes it. In the dashboard, **Create Agent** and **Edit Agent** list these under **Skills**, separately from the skills loaded at start: choose none, a list with a version for each, or any Workspace skill. Each version is picked from the Skill's published versions or left at latest. The Agent page shows the saved choice. Editing something else never restates it, and removing it sends the explicit `null`. * **Custom tools** — inline tool definitions with a JSON Schema input. Selecting a capability on the Agent scopes what the Agent may call. It never grants account access. Connection access is a separate grant: assign a Connection to the Agent on its detail page, which mints an ordinary `use_connection` PermissionAssignment. An authenticated call without that grant is denied even when the capability is selected. Use the [Create and version an Agent](/guides/create-and-version-an-agent) guide for current CLI, cURL, and TypeScript examples. ## What a Session runs A Session selects an Agent in one of two ways: * selecting only the Agent ID resolves its current Version at admission; * selecting the Agent ID and a Version pins that exact immutable Version. Admission records the resolved AgentVersion and freezes it for the Session. Updating the Agent later affects future Sessions that select the current Version. It never changes a Session that has already been admitted. The [Environment](/concepts/work-environments) is selected separately. It is the reusable execution environment for the Session, while the AgentVersion is the immutable authored configuration. Models and harnesses remain replaceable execution lanes inside that shared Agent, Environment, and Session model. ## Browser The `browser` field is optional when creating or updating an Agent. Omit it or set it to `null` for no browser. Set it to `{ "tier": "isolate" }` or `{ "tier": "chromium" }` to declare a per-Session browser MCP server at that tier. The browser credential stays on the platform; it does not enter the sandbox, event log, or model context. Browser access is not yet generally available. It requires a configured browser deployment, refuses ZDR Workspaces, and never silently substitutes a different tier when the requested one is unavailable. ## Update semantics Agent updates are declarative: * omitted fields preserve their current value; * array fields replace the whole array; * metadata merges by key; * `system` and `description` can be cleared with `null` or an empty string; * an optional `version` rejects a stale write instead of overwriting a newer AgentVersion. The `version` guard controls concurrency; it does not choose an authoring owner. UI, HTTP, SDK, CLI, and MCP are interfaces over the same Agent operations, not independent owners. An Agent has zero or one active desired-state owner. Direct writes are available while it is unclaimed; a Git- or YAML-backed source that actively reconciles it must be the sole owner and use an explicit, audited handoff before ownership changes. See [Author an Agent project](/guides/author-an-agent-project) for the current source-authoring workflow. Do not run two active reconcilers against the same Agent. ## Inspect history Retrieving an Agent without a Version returns its current head. Retrieving an exact Version returns that immutable historical configuration. Listing Versions returns the Agent's ordered configuration history. Earlier Versions remain unchanged when the Agent advances. ## Archive Archiving an Agent makes its authored head read-only. Existing immutable AgentVersions remain retrievable. List operations omit archived Agents unless you request them explicitly. Create Version 1, update the Agent, and retrieve exact history. Change instructions while existing Sessions keep their frozen AgentVersion. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.