createCodingAgent()

createCodingAgent() builds a coding Agent with portable defaults for the pieces a coding agent always needs: a local workspace, the task-list signal provider, network-retry error processors, and the goal judge prompt. Supply only model, instructions, and tools to get a working agent, or override any default.

The returned value is a standard Agent, so it works anywhere an Agent does — including as the agent passed to an AgentController.

Usage example

Pass a model, instructions, and tools. The factory fills in the workspace, task signal, error processors, and goal prompt:

src/mastra/coding-agent.ts

import { createCodingAgent } from '@mastra/core/coding-agent'

const agent = createCodingAgent({
  id: 'my-coding-agent',
  name: 'My Coding Agent',
  model: 'openai/gpt-5',
  instructions: 'You are a helpful coding assistant.',
  tools: {},
})

Parameters

createCodingAgent() accepts every field of AgentConfig plus the fields below. Fields you provide always take precedence over the factory defaults.

model:

MastraLanguageModel | DynamicArgument<MastraLanguageModel>

The language model the agent uses. Passed straight through to Agent.

instructions:

string | DynamicArgument<string>

System instructions for the agent. Passed straight through to Agent.

tools?:

ToolsInput | DynamicArgument<ToolsInput>

Tools available to the agent. Passed straight through to Agent.

workspace?:

AnyWorkspace | undefined

The workspace backing the agent. When the key is omitted, a default local workspace is built. When set explicitly to undefined, the factory builds no default — opt out when the workspace is wired elsewhere (for example at the AgentController level).

basePath?:

string

= process.cwd()

Base path for the default workspace built when workspace is omitted.

signals?:

SignalProvider[]

Signal providers for the agent. When omitted, defaults to a single TaskSignalProvider.

errorProcessors?:

Processor[]

Error processors for the agent. When omitted, defaults to the ECONNRESET/bad-request retry stack plus PrefillErrorHandler and ProviderHistoryCompat.

goal?:

AgentGoalConfig

Goal configuration. When provided without a prompt, the prompt defaults to DEFAULT_GOAL_JUDGE_PROMPT.

Returns

agent:

Agent

A coding agent with the resolved workspace, signals, error processors, and goal applied.

Defaults

The factory only fills a default when you do not provide the corresponding field. Caller-provided values always win.

Field	Default when omitted
workspace	A Workspace backed by LocalFilesystem and LocalSandbox rooted at the base path.
signals	A single TaskSignalProvider.
errorProcessors	ECONNRESET and bad-request retry processors plus PrefillErrorHandler and ProviderHistoryCompat.
goal.prompt	DEFAULT_GOAL_JUDGE_PROMPT (only when a goal is configured).

Workspace

When the workspace key is omitted, the factory builds a local workspace rooted at basePath (default process.cwd()):

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

new Workspace({
  filesystem: new LocalFilesystem({ basePath }),
  sandbox: new LocalSandbox({ workingDirectory: basePath }),
})

To opt out — for example when the workspace is injected at the AgentController level — pass workspace: undefined explicitly:

const agent = createCodingAgent({
  id: 'my-coding-agent',
  name: 'My Coding Agent',
  model: 'openai/gpt-5',
  instructions: 'You are a helpful coding assistant.',
  tools: {},
  workspace: undefined, // opt out of the default workspace
})

Error processors

The default error processors apply a retry policy for transient failures:

• Network resets (ECONNRESET / socket hang up) retry up to twice with exponential backoff (1000ms * 2^retryCount, capped at 30000ms).
• Bad-request errors retry once after 2000ms.

PrefillErrorHandler and ProviderHistoryCompat are also included for provider compatibility.

Related

• buildBasePrompt()
• Agent
• AgentController