文档构建工作流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 章节。