跳至主要內容

createCodingAgent()

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

傳回值是標準 Agent，因此可用於任何接受 Agent 的地方，包括作為傳入 AgentController 的 Agent。

使用範例
使用範例 的直接連結

傳入模型、指示及 Tool。工廠函數會填入 Workspace、任務訊號、錯誤 Processor 及目標 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: {},
})

參數
參數 的直接連結

createCodingAgent() 接受 AgentConfig 的所有欄位及以下欄位。你提供的欄位一律優先於工廠函數的預設設定。

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
= process.cwd()
省略 workspace 時所建立之預設 Workspace 的基礎路徑。

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，其根目錄設於基礎路徑。
signals單一 TaskSignalProvider。
errorProcessors針對未知串流錯誤重試，並使用專門的 ECONNRESET 及錯誤請求政策，另外加入 PrefillErrorHandler 及 ProviderHistoryCompat。
goal.promptDEFAULT_GOAL_JUDGE_PROMPT（只在已設定 goal 時使用）。

Workspace
Workspace 的直接連結

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

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

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

如要停用預設值（例如在 AgentController 層級注入 Workspace 時），請明確傳入 workspace: undefined：

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
錯誤 Processor 的直接連結

預設的 StreamErrorRetryProcessor 會套用以下重試政策：

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

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

On this page