エージェント構成の詳細説明

Agent は「1 回の LLM セッション + それが使えるツール + その実行ポリシー」をカプセル化したものです。Braidrun では system prompt を手書きする必要はほとんどありません。preset を 1 つ選び、必要に応じていくつかのフィールドを overrides するだけで十分です。

プリセット: シーンに基づいてベースラインを選択します

preset はプラットフォーム内蔵の Agent テンプレートで、「モデル、デフォルトのツールセット、system prompt、実行ポリシー」をまとめてパッケージ化し、業務シナリオに応じて命名されています。現在、全 19 種類の内蔵プリセットがあります。

最小限の宣言

agents:
  analyst:
    preset: universal

これで十分です。モデル、ツール、system prompt はすべて preset のデフォルトに従います。

オーバーライド: オンデマンドでオーバーライド

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

よく使用されるオーバーライドフィールド

• 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 呼び出しが失敗した際のバックオフ再試行ポリシーです。

再利用可能: ステップ内の参照エージェント

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 リクエスト、Web ページのスクレイピングと検索。
• browser — ブラウザ自動化: 動的ページ、フォーム、スクリーンショット。
• code_execution — コードスニペットの実行。
• csv · database · data_transform — CSV テーブル、SQL データベース、JSON/YAML/XML 形式の変換。
• email · im — メールの送受信と IM メッセージ（Slack、Telegram、DingTalk、WeChat Work、Feishu など）。
• 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 が公開するツールを利用できます。

モデル選択の推奨事項

• 正確性が重視されるタスク（レビュー、推論、コード生成）: 各社のフラッグシップモデルまたは推論モデルを使用します。
• レイテンシが重視され、出力形式が単純なタスク（classifier、短い要約）: 軽量モデルを使用すると、高速かつ低コストです。
• 同一ワークフロー内で併用できます。大量に処理する分析には安価なモデルを、重要な最終レビューにはより強力なモデルを使い分けます。

モデルはすべて BYOK です。15 社以上のプロバイダー（OpenAI、Anthropic、Google、DeepSeek、Kimi、MiniMax、Zhipu、xAI、Mistral、Qwen など）に対応し、ローカルの Ollama / LM Studio もサポートします。呼び出しコストはお客様自身のアカウントに計上され、認証情報は AES-256-GCM で暗号化して保存されます。Claude Pro / ChatGPT のサブスクリプションもログイン方式で接続でき、必ずしも API Key は必要ありません。

FAQ

複数のステップで同じエージェントを再利用する場合、クォータはどのように計算されますか?

step の実行ごとに独立した LLM セッションとなり、token 消費は実行詳細に都度記録されます。プランのクォータが制限するのはワークフロー数、スケジュール数、並列数といったプラットフォームリソースです。LLM の token はお客様自身の Key を使用するため、プラットフォーム側で token の上限は設けていません。

Agent で無限ループが発生した場合はどうすればよいですか?

max_iterations はハードリミットで、到達すると実行が強制的に停止します。トラブルシューティングの際は、まず実行タイムラインで各ラウンドのツール呼び出しを確認します。Pro 以上のプランでは、ブレークポイントデバッガーを使ってステップ内で一時停止して検査することもできます。

独自のツールを追加したいですか?

MCP server としてパッケージ化し、mcp_servers 設定で接続することを推奨します。プラットフォームを変更する必要はありません。参照: 内蔵モジュールライブラリ と AI アシスタントのドキュメント MCPの章で。