---
title: AgentDefinition
description: "An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace."
---

# `AgentDefinition`

Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.

```ts
type AgentDefinition = {
  model: string;
  instructions: string;
  description?: string;
  thinkingLevel?: ThinkingLevel;
  workspace?: WorkspaceAccess;
};
```

An Agent's definition: which model it runs, its instructions, and what it may do to the
Workspace. Give it to `agent()` to get the Agent's actor slot. It is plain data that can be
written as JSON.

It holds who the Agent is, not what one Turn does. The prompt of a Turn and the directory it
works in are the Frame. The state that invokes the Agent sets the Frame in the invoke's
`input`. That `input` can also set `model` and `thinkingLevel` for one Turn: the Dials. It
cannot change `instructions` or `workspace`.

**Fields**

- `model`: `string`

  The model, as `<provider>/<modelId>`: for example `anthropic/claude-haiku-5-5`. The
  provider must be one that `jr2.config.ts` can reach. Here it is always a string: an `open`
  model of `agent()` must be bound before a Turn starts. One Turn may set another model in the
  invoke's `input`.
- `instructions`: `string`

  The Agent's instructions: the text that tells the model who it is and how to work. The same
  on every Turn.
- `description` (optional): `string`

  A short description, for people who read the Machine. The model never reads it.
- `thinkingLevel` (optional): [`ThinkingLevel`](type-thinkinglevel.md)

  How hard the model thinks: one of [`ThinkingLevel`](type-thinkinglevel.md). Absent: `"off"`. A model with no
  `"off"` runs at another level, and the printed conversation names it. One Turn may set another
  level in the invoke's `input`.
- `workspace` (optional): [`WorkspaceAccess`](type-workspaceaccess.md)

  What the Agent may do to the Workspace. Default: `"write"`.
  - `"write"`: all the Working tools (read, write, edit, bash, grep, glob).
  - `"read"`: no write or edit tool. The Agent keeps bash, so `"read"` does not stop a command
    that writes. To keep the Agent from changing the branch, frame its Turn in the review
    Worktree: `reviewSha` in the spec, then `cwd: context.workspace.review?.<slot>`.
  - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
    runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it.

**Example**

```ts
import { agent, type AgentDefinition } from "@jr2/orchestrator";

const definition: AgentDefinition = {
  model: "anthropic/claude-haiku-5-5",
  instructions: "You fix the failing test, and you change nothing else.",
  description: "Fixes one failing test",
  thinkingLevel: "medium",
  workspace: "write",
};

export const coder = agent(definition);
```

**See also**

- [Agents and Turns](../../concepts/agents-and-turns.md)
- [Set an Agent's access and Dials](../../guides/set-an-agents-access-and-dials.md)
- [ADR-0018: The instance authors Agent definitions; jr2 assembles the Harness](../decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)
- [ADR-0028: What an Agent may do to the Workspace is part of its definition](../decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)