> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# createCodingAgent()

`createCodingAgent()` 會建立一個編程 [`Agent`](https://mastra.zisheng.pro/zh-HK/reference/agents/agent)，並為編程助手必備的部分提供可攜式預設設定：本機 Workspace、任務清單訊號 Provider、網絡重試錯誤 Processor，以及目標評審 prompt。只需提供 `model`、`instructions` 和 `tools` 即可取得可運作的 Agent，亦可覆寫任何預設設定。

傳回值是標準 `Agent`，因此可用於任何接受 `Agent` 的地方，包括作為傳入 [`AgentController`](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/agent-controller-class) 的 Agent。

## 使用範例

傳入模型、指示及 Tool。工廠函數會填入 Workspace、任務訊號、錯誤 Processor 及目標 prompt：

```typescript
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: {},
})
```

## 參數

`createCodingAgent()` 接受 [`AgentConfig`](https://mastra.zisheng.pro/zh-HK/reference/agents/agent) 的所有欄位及以下欄位。你提供的欄位一律優先於工廠函數的預設設定。

**model** (`MastraLanguageModel | DynamicArgument<MastraLanguageModel>`): Agent 使用的語言模型。直接傳遞至 Agent。

**instructions** (`string | DynamicArgument<string>`): Agent 的系統指示。直接傳遞至 Agent。

**tools** (`ToolsInput | DynamicArgument<ToolsInput>`): Agent 可用的 Tool。直接傳遞至 Agent。

**workspace** (`AnyWorkspace | undefined`): 為 Agent 提供支援的 Workspace。省略此 key 時，系統會建立預設的本機 Workspace。明確設為 undefined 時，工廠函數不會建立預設值；如果 Workspace 在其他位置接駁（例如 AgentController 層級），可用此方式停用預設值。

**basePath** (`string`): 省略 workspace 時所建立之預設 Workspace 的基礎路徑。 (Default: `process.cwd()`)

**signals** (`SignalProvider[]`): Agent 的訊號 Provider。省略時，預設使用單一 TaskSignalProvider。

**errorProcessors** (`Processor[]`): Agent 的錯誤 Processor。省略時，預設會針對未知串流錯誤重試，並使用專門的 ECONNRESET 及錯誤請求政策，另外加入 PrefillErrorHandler 及 ProviderHistoryCompat。

**goal** (`AgentGoalConfig`): 目標設定。提供此設定但未有 prompt 時，prompt 預設為 DEFAULT\_GOAL\_JUDGE\_PROMPT。

## 傳回值

**agent** (`Agent`): 已套用解析後 Workspace、訊號、錯誤 Processor 及目標的編程助手。

## 預設設定

只有當你未提供相應欄位時，工廠函數才會填入預設值。呼叫端提供的值一律優先。

| 欄位                | 省略時的預設值                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `workspace`       | 一個以 `LocalFilesystem` 及 `LocalSandbox` 支援的 [`Workspace`](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)，其根目錄設於基礎路徑。 |
| `signals`         | 單一 [`TaskSignalProvider`](https://mastra.zisheng.pro/zh-HK/reference/signals/task-signal-provider)。                                        |
| `errorProcessors` | 針對未知串流錯誤重試，並使用專門的 ECONNRESET 及錯誤請求政策，另外加入 `PrefillErrorHandler` 及 `ProviderHistoryCompat`。                                                 |
| `goal.prompt`     | `DEFAULT_GOAL_JUDGE_PROMPT`（只在已設定 `goal` 時使用）。                                                                                             |

### Workspace

省略 `workspace` key 時，工廠函數會建立一個以 `basePath` 為根目錄的本機 Workspace（預設為 `process.cwd()`）：

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

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

如要停用預設值（例如在 [`AgentController`](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/agent-controller-class) 層級注入 Workspace 時），請明確傳入 `workspace: undefined`：

```typescript
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
})
```

### 錯誤 Processor

預設的 [`StreamErrorRetryProcessor`](https://mastra.zisheng.pro/zh-HK/reference/processors/stream-error-retry-processor) 會套用以下重試政策：

- Provider metadata 或特定 matcher 無法配對的未知錯誤，最多重試兩次，每次延遲 `3000ms`。已知的授權失敗會立即顯示。
- 網絡重設（`ECONNRESET` / `socket hang up`）最多重試兩次，並採用指數退避（`1000ms * 2^retryCount`，上限為 `30000ms`）。
- 錯誤請求會在 `2000ms` 後重試一次。

特定的網絡重設及錯誤請求政策優先於未知錯誤政策。傳入 `errorProcessors` 會取代預設的 Processor stack。當中亦包含 `PrefillErrorHandler` 及 `ProviderHistoryCompat`，以確保與 Provider 相容。

## 相關內容

- [`buildBasePrompt()`](https://mastra.zisheng.pro/zh-HK/reference/coding-agent/build-base-prompt)
- [`Agent`](https://mastra.zisheng.pro/zh-HK/reference/agents/agent)
- [`AgentController`](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/agent-controller-class)