Agent

Use this page to reference agent prompts, models, tools, budgets, and subagents.

Limits

spec:
  limits:
    maxToolOutputTokens: 8000      # a longer tool output is cut, with a note to the model
    maxSubmitRetries: 2            # corrective messages before the turn fails
    summarizeTokens: 60000         # summarize the context past this many tokens; null turns it off
    summarizeKeepMessages: 20      # the last messages always kept

Fields

AgentSpec (spec)

Field	Type	Default	Meaning
harness	str	basic	The harness that runs the agent: basic, deep, acp or a plugin's.
systemPrompt	str or null	null	The prompt inline, or None when it is a file.
systemPromptFile	str or null	null	The prompt as a file next to the manifest.
writes	str	required	The Schema of the artifact the agent produces.
reads	list[str]	[]	The artifacts the agent reads; a name ending in ? is optional.
budget	Budget	Budget()	The agent's own budget ceilings.
limits	AgentLimits	AgentLimits()	The harness's limits.
model	str or null	null	The model alias to start with, for the basic harness.
tools	list[str]	[]	The tools the agent may call, by name.
workspaceAccess	read or write or null	null	deep: read or write access to the workspace.
execute	bool	False	deep: whether the agent may run commands in the sandbox.
extraTools	list[str]	[]	deep: built-in tools added to the default set.
subagents	list[SubagentSpec]	[]	deep: the subagents the agent may hand work to.
agent	str or null	null	acp: the AcpAgent manifest the agent runs.
permissions	dict[str, allow or deny or ask]	{}	acp: the start permission per tool name.

Budget (spec.budget)

Field	Type	Default	Meaning
tokens	int or null	null	The token ceiling.
toolCalls	int or null	null	The tool-call ceiling.
costUsd	float or null	null	The cost ceiling in US dollars.
wallTime	duration or null	null	The wall-clock ceiling.
maxTurns	int or null	null	The turn ceiling.

AgentLimits (spec.limits)

Field	Type	Default	Meaning
maxToolOutputTokens	int	8000	The tokens of a tool result kept before it is cut.
maxSubmitRetries	int	2	How many times the harness retries a rejected artifact submission.
summarizeTokens	int or null	60000	Summarise the context past this many tokens; null turns it off.
summarizeKeepMessages	int	20	How many recent messages summarization keeps verbatim.

SubagentSpec (spec.subagents)

Field	Type	Default	Meaning
name	str	required	The subagent's name, as the parent refers to it.
description	str	required	What the subagent is for; the parent sees it.
systemPrompt	str or null	null	The prompt inline, or None when it is a file.
systemPromptFile	str or null	null	The prompt as a file next to the manifest.
tools	list[str]	[]	The tools the subagent may call: a subset of the parent's.
model	str or null	null	The model alias; inherited from the parent when absent.

See also

• Built-in tools for access requirements.
• Model for provider and pricing fields.
• Flow for agent nodes.