DocsBuild WorkflowAgent Configuration

Agent Configuration Guide

Presets, model selection, tool_set, max_iterations, and system prompt overrides for readable, maintainable LLM sessions.

An Agent wraps "one LLM session + the tools it can use + its run policy." In Braidrun you almost never need to hand-write a system prompt — pick a preset and, if needed, override a few fields.

preset: Choose a Baseline for the Use Case

A preset is a built-in Agent template that bundles the model, default tool set, system prompt, and run policy together, named by use case. There are 19 built-in presets today:

preset	Classification	Best At
`universal`	General	The all-around default: comes with the full tool set — sub-Agents, skills, knowledge memory, data transforms, and more. When in doubt, pick this.
`universal_reasoning`	General	The reasoning version of universal; keeps visible reasoning steps at run time, good for complex analysis.
`lightweight`	General	A minimal single-round policy with only shell and file tools, good for simple tasks and low-overhead runs.
`chat`	Chat	Multi-turn conversation with context retention, good for conversational tasks.
`coder`	Code	Code analysis, generation, refactoring, and testing, with shell / Git / code-execution tools.
`devops`	Code	System and ops tasks: shell scripts, Git, database operations, and deployment automation.
`researcher`	Research	Search, browsing, and multi-source synthesis; research findings can settle into knowledge memory across executions.
`data_analyst`	Data	CSV processing, SQL queries, code execution, and format conversion, producing analytical conclusions.
`web_scraper`	Data	Structured data extraction combining browser automation, HTTP scraping, and OCR.
`marketing`	Marketing	Market research, ad-spend analysis, audience insights, and optimization recommendations.
`communication`	Communication	Sending and receiving email (SMTP / IMAP) and composing and sending IM messages across platforms.
`writer`	Writing	Articles, copywriting, and business writing, producing well-formatted documents directly.
`word_document`	Docs	Word specialist: generating and editing reports, manuals, and proposal-style .docx files.
`excel_workbook`	Docs	Excel specialist: spreadsheet modeling, dashboards, and formula-driven reports.
`powerpoint_presentation`	Docs	PowerPoint slides: training materials, pitch decks, and reporting presentations.
`office_document`	Docs	Mixed Office document tasks across Word, Excel, and PowerPoint.
`pdf_processor`	Docs	PDF parsing, content extraction, format conversion, and OCR.
`multimedia_creator`	Multimedia	AI image / audio generation and image processing.
`computer_operator`	Automation	Multi-step operational automation stringing together browser control, shell, files, and databases.

Plan Limits

The Free plan can only use the universal, lightweight, and chat presets; the rest require Pro or higher.

The preset list reflects your running instance

When configuring an Agent in the workflow editor, choose "Preset template" to browse the full list by category with a description of each preset; admins can also register custom presets beyond the built-in ones.

Minimal Configuration

yaml

agents:
  analyst:
    preset: universal

That's all it takes — model, tools, and system prompt all fall back to the preset defaults.

overrides: Override Only What You Need

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

Common Override Fields

system_prompt — Replaces the preset's system prompt wholesale (not appended).
llm_config — Model configuration: the models list (each entry a model + provider), fallback, and temperature. Each Agent in a workflow can use a different model.
tool_set — A list of tool-set names that replaces the preset default wholesale (no merge).
max_iterations — A hard cap on the Agent's internal "think + call tools" rounds; it's forced to stop when reached. The built-in presets set this generously.
strategy — just_work_parallel（Default for most presets）/ just_work_parallel_reasoning（Keeps visible reasoning steps）/ single_run（Single-round, direct output; used by lightweight）。
mcp_servers — Register an external MCP Server, merging the tools it exposes into this Agent's tool set.
retry_max_attempts / retry_initial_delay / retry_max_delay — The backoff-and-retry policy for failed LLM calls.

overrides is a deep merge

Nested objects merge field by field, while scalars and lists are replaced wholesale. So overriding only llm_config.temperature won't drop the preset's models; but once tool_set appears, it fully replaces the default with whatever you write.

Reuse an Agent Across Steps

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]

The same Agent can be referenced by multiple steps. Each step run opens a fresh session instance — memory never carries over. To pass data between steps, use template variables to reference upstream output; to keep context across rounds, use state_machine or group_chat.

Toolset (tool_set)

Built-in tools are grouped by name. The common ones are:

file_system — Read and write files in the working directory.
shell — Run shell commands.
web — HTTP requests, web scraping, and search.
browser — Browser automation: dynamic pages, forms, screenshots.
code_execution — Run code snippets.
csv · database · data_transform — CSV tables, SQL databases, and JSON/YAML/XML format conversion.
email · im — Sending and receiving email, and IM messaging (Slack, Telegram, DingTalk, WeCom, Feishu, and more).
word · excel · powerpoint · pdf · ocr — Document generation and parsing.
image_processing · multimedia — Image processing and AI image / audio generation.
git — Version control operations.
knowledge_memory — Knowledge memory that persists across executions.
sub_agent — Spawn sub-Agents to break down a task.
skill_tools — Load and invoke skills.

Every preset's definition ships with a default tool_set; on top of that, any Agent can pull in tools exposed by an MCP Server through the mcp_servers config.

Less Is More

The larger the tool_set, the larger the Agent's decision-making space, but the easier it is to be biased by secondary tools. In production practice, if you cut the tool_set to the ones that are "really used in this step", the success rate and speed will increase.

Model Selection Recommendations

For correctness-sensitive tasks (review, reasoning, code generation): use each provider's flagship or reasoning model.
For latency-sensitive tasks with simple output (classifier, short summary): use a lightweight model — fast and cheap.
You can mix them within one workflow: a cheap model for high-volume analysis, a stronger one for the critical final review.

All models are BYOK: 15+ providers are supported (OpenAI, Anthropic, Google, DeepSeek, Kimi, MiniMax, Zhipu, xAI, Mistral, Qwen, and more, plus local Ollama / LM Studio). Usage is billed to your own account, and credentials are stored encrypted with AES-256-GCM. Claude Pro / ChatGPT subscriptions can also connect via login, so an API Key isn't strictly required.

FAQ

If Multiple steps reuse the same Agent, how is the quota calculated?

Each step run is an independent LLM session, and token usage is recorded per call in the execution details. Plan quotas limit platform resources like workflow count, schedule count, and concurrency; LLM tokens run on your own Key, and the platform sets no token cap.

What Should I Do If an Agent Enters an Infinite Loop?

max_iterations is a hard cap; the run is forced to stop when it's reached. When troubleshooting, start with each round of tool calls in the execution timeline; on Pro and above you can also use the breakpoint debugger to pause and inspect inside a step.

I want to add my own tool?

We recommend packaging it as an MCP server and pulling it in via the mcp_servers config — no platform changes needed. See Built-In Module Library with AI assistant documentation In the MCP chapter.