`AgentDefinition`

Type, in @jr2/orchestrator/src/agent.ts. It is an export of @jr2/orchestrator, on the Authoring surface page, in Agents.

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
How hard the model thinks: one of ThinkingLevel. 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
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

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

AgentDefinition ​

`AgentDefinition`