文件建構工作流程Agent 配置

Agent 配置詳解

preset、模型選擇、tool_set、max_iterations、system prompt overrides —— 把 LLM 會話寫得既可讀又可維護。

Agent 是對「一次 LLM 會話 + 它能用的工具 + 它的執行策略」的封裝。在 Braidrun 裡你幾乎不需要手寫 system prompt —— 選一個 preset、必要時 overrides 幾個欄位就夠了。

preset：從場景出發選基線

preset 是平台內建的 Agent 範本，把「模型、預設工具集、system prompt、執行策略」一起打包，按業務場景命名。目前共 19 個內建預設：

preset	分類	擅長什麼
`universal`	一般	全能預設選擇：帶子 Agent、技能、知識記憶、資料轉換等全套工具。不確定用哪個就選它。
`universal_reasoning`	一般	universal 的推理版，執行時保留可見推理步驟，適合複雜分析。
`lightweight`	一般	極簡單輪策略，只帶 shell 與檔案工具，適合簡單任務與低開銷執行。
`chat`	對話	多輪對話與上下文保持，適合會話式任務。
`coder`	代碼	程式碼分析、生成、重構與測試，帶 shell / Git / 程式碼執行工具。
`devops`	代碼	系統與維運任務：shell 指令碼、Git、資料庫操作、部署自動化。
`researcher`	研究	搜尋、瀏覽、多來源資訊綜合，研究結論可跨執行沉入知識記憶。
`data_analyst`	數據	CSV 處理、SQL 查詢、程式碼執行與格式轉換，產出分析結論。
`web_scraper`	數據	瀏覽器自動化 + HTTP 抓取 + OCR 的結構化資料擷取。
`marketing`	營銷	市場調研、投放分析、受眾洞察與最佳化建議。
`communication`	溝通	郵件（SMTP / IMAP）收發與多平台 IM 訊息撰寫、傳送。
`writer`	寫作	文章、文案與商務寫作，能直接產出排版好的文件。
`word_document`	文件	Word 專精：報告、手冊、方案類 .docx 的生成與修改。
`excel_workbook`	文件	Excel 專精：表格建模、看板、公式驅動的報表。
`powerpoint_presentation`	文件	PPT 投影片：培訓教材、路演與匯報簡報。
`office_document`	文件	Word / Excel / PPT 混合的 Office 文件任務。
`pdf_processor`	文件	PDF 解析、內容擷取、格式轉換與 OCR。
`multimedia_creator`	多媒體	AI 影像 / 音訊生成與影像處理。
`computer_operator`	自動化	瀏覽器控制、shell、檔案、資料庫串起來的多步操作自動化。

方案限制

Free 方案只能選 universal / lightweight / chat 三個預設；其餘預設需要 Pro 及以上方案。

preset 列表以執行中執行個體為準

在工作流編輯器裡設定 Agent 時選「預設範本」，可以按分類瀏覽完整列表與每個 preset 的說明；管理員也可以在內建預設之外註冊自訂預設。

最小聲明

yaml

agents:
  analyst:
    preset: universal

這樣就夠了 —— 模型、工具、system prompt 全部走 preset 預設。

overrides：按需覆蓋

yaml

agents:
  analyst:
    preset: universal
    overrides:
      system_prompt: |
        你是公司的风控分析师。所有输出用中文。
      llm_config:
        models:
          - model: anthropic/claude-sonnet-4-20250514
            provider: openrouter
        temperature: 0.2
      tool_set:
        - file_system
        - web
        - data_transform

常用 overrides 字段

system_prompt — 整段替換 preset 的 system prompt（不是追加）。
llm_config — 模型設定：models 列表（每項 model + provider）、fallback、temperature。同一條工作流裡每個 Agent 可以用不同模型。
tool_set — 工具集名稱的列表，整體替換 preset 預設（不做合併）。
max_iterations — Agent 內部「思考 + 工具呼叫」輪次的硬上限，到達後強制停止。內建預設的預設值給得很寬。
strategy — just_work_parallel（多數預設預設）/ just_work_parallel_reasoning（保留可見推理步驟）/ single_run（單輪直出，lightweight 用它）。
mcp_servers — 註冊外部 MCP Server，其暴露的工具併入該 Agent 的工具集。
retry_max_attempts / retry_initial_delay / retry_max_delay — LLM 呼叫失敗時的退避重試策略。

overrides 是深度合併

巢狀物件逐欄位合併，純量與列表整體替換。所以只覆寫 llm_config.temperature 不會遺失 preset 裡的 models；但 tool_set 一旦出現，就完全以你寫的為準。

可複用：在 step 裡引用 Agent

yaml

agents:
  analyst: { preset: universal }
  writer:  { preset: writer }

steps:
  - step: plan
    agent: analyst
    input: "拆解下面这个目标为 3~5 个可执行任务：..."

  - step: write
    agent: writer
    input: "把下面的计划改写成给客户的邮件：{{steps.plan.output}}"
    depends_on: [plan]

同一個 Agent 可以被多個 step 引用。每次 step 執行都會開一個新的會話執行個體 —— 不會串記憶。要在 step 之間傳資料，用範本變數引用上游輸出；要跨輪保持上下文，用 state_machine 或 group_chat。

工具集（tool_set）

內建工具按名稱分組，常用的有：

file_system — 讀寫工作目錄內的檔案。
shell — 執行 shell 命令。
web — HTTP 請求、網頁抓取與搜尋。
browser — 瀏覽器自動化：動態頁面、表單、截圖。
code_execution — 執行程式碼片段。
csv · database · data_transform — CSV 表格、SQL 資料庫、JSON/YAML/XML 格式轉換。
email · im — 郵件收發與 IM 訊息（Slack、Telegram、釘釘、企業微信、飛書等）。
word · excel · powerpoint · pdf · ocr — 文件生成與解析。
image_processing · multimedia — 影像處理與 AI 影像 / 音訊生成。
git — 版本控制操作。
knowledge_memory — 跨執行持久化的知識記憶。
sub_agent — 派生子 Agent 分解任務。
skill_tools — 載入與呼叫技能（skills）。

每個 preset 的定義裡帶一份預設 tool_set；此外任何 Agent 都能透過 mcp_servers 設定接入 MCP Server 暴露的工具。

少就是多

tool_set 越大，Agent 的決策空間就越大，但也越容易被次要工具拉偏。生產實踐裡，把 tool_set 裁到"這個步驟真的會用到的"那幾個，成功率和速度都會上來。

模型選擇建議

對正確性敏感的任務（審閱、推理、程式碼生成）：用各家的旗艦或推理模型。
對延遲敏感、輸出格式簡單（classifier、短摘要）：用輕量模型，快且省。
同一條工作流裡可以混用：走量的分析用便宜模型，關鍵的終審換更強的模型。

模型全部 BYOK：支援 15+ 家供應商（OpenAI、Anthropic、Google、DeepSeek、Kimi、MiniMax、智譜、xAI、Mistral、Qwen 等，也支援本地 Ollama / LM Studio），呼叫成本走你自己的帳，憑證以 AES-256-GCM 加密儲存。Claude Pro / ChatGPT 訂閱也可以登入式接入，不一定要 API Key。

常見問題

多個 step 複用同一個 Agent，配額怎麼算？

每次 step 執行是獨立的 LLM 會話，token 消耗在執行詳情裡逐次記錄。方案配額限制的是工作流數、排程數、並行這類平台資源；LLM token 走你自己的 Key，平台不設 token 上限。

Agent 出現無限循環怎麼辦？

max_iterations 是硬上限，到達後執行強制停止。排查時先看執行時間軸裡每一輪工具呼叫；Pro 及以上方案還可以用中斷點偵錯器在步驟內暫停檢查。

我想加自己的 tool？

建議包成 MCP server，用 mcp_servers 設定接進來，不需要改平台。參考內建模組庫與 AI 助手文檔裡 MCP 章節。