AI エージェントワークフロー:実際に動くものを作るステップバイステップガイド

AI エージェントワークフロー:実際に動くものを作るステップバイステップガイド

2026年5月25日
228 回閲覧
ai-agent workflow agentic-workflows llm tutorial best-practices validation

こんにちは、Lena です。AI エージェントワークフローというのは、LLM が推論し、ツールを呼び出し、結果を観察し、次に何をするかを決める——という構造化されたループで、タスクが完了するまで繰り返すものです。agentic workflows について読んだことがあれば、概念自体はすでにご存じだと思います。この記事で書きたいのは、誰もちゃんと説明してくれない部分——実際に動くものをどう作るか、です。

ここ数週間、私は「考え方は理解している」状態から、「3 回に 1 回壊れたりしない何かが動いている」状態まで進みました。その間の距離は予想よりずっと大きかったです。これから書くのは、私が実際に通ったプロセス——理論版ではなく、本物の失敗に当たってもなお生き残ったバージョンです。

始める前に:ワークフロー契約を決める

入力、出力、成功基準、責任者、失敗状態

このステップを最初の時に飛ばして、一日のうちに後悔しました。

どんなフレームワークに触れる前にも、まず五つのことを書き出してください:何が入力で、何が出力で、「完了」とはどう見えるもので、結果に対して誰が責任を持ち、失敗したらどうなるか。 これがあなたのワークフロー契約です。最もよくある間違い——「何かをやっている」けれど、それが正しいことをやっているのかどうか誰も言えない、というエージェントを作ってしまうこと——を防いでくれます。

私のサポートチケット振り分けの場合は、こんな感じでした:

  • 入力: 顧客メッセージ(テキスト、2000 文字以内)
  • 出力: 分類されたカテゴリ + 起草された返信
  • 成功基準: カテゴリが正しい確率 90% 以上、返信が人間のレビューを通過する
  • 責任者: サポートチームリードが毎日レビューする
  • 失敗状態: 分類の信頼度が閾値を下回ったら、人間にエスカレーション——推測はしない

最後のひとつは、多くの人が思っている以上に重要です。失敗状態が定義されていないエージェントは、静かにゴミを出力し続け、顧客が苦情を言うまで誰も気付かないエージェントになります。

Step 1:プロダクトではなく、ひとつのワークフローを選ぶ

……ここで多くの人が躓きます。

私もあやうく「すべてのカスタマーサポートを処理する AI を作ろう」と始めるところでした。それはワークフローではありません。プロダクトのロードマップです。Anthropic の building effective agents ガイドはこう明言しています:可能な限りシンプルな解決策から始め、必要なときだけ複雑度を上げる、と。

ひとつのワークフローを選びます。 境界がはっきりした、繰り返し実行できるタスクをひとつ。「入ってきたチケットを分類して返信を起草する」——これはワークフローです。「すべての顧客対応を自律的にこなす」——これは初月には到達できない幻想です。

そのワークフローが何かを新しいチームメンバーに 2 分以内で説明できないなら、範囲が広すぎます。説明できるところまで狭めましょう。

Step 2:ワークフロー図を描く

タスクノード、ツール呼び出し、判断ポイント、レビュー関門

最初は図を描くのを嫌がっていました。そして図なしでワークフローを作って、自分が存在を知らなかったループのデバッグに 2 時間を費やしました。

AI エージェントワークフロー図は派手である必要はありません。紙の上の四角と矢印で十分です。重要なのは、4 種類の要素をマッピングすることです:

タスクノード——LLM が実際の仕事をする場所(このテキストを分類する、要約を生成する、返信を起草する)。各ノードはひとつのことをやります。

ツール呼び出し——エージェントが自分の外側に手を伸ばす場所(データベースを照会する、API を呼ぶ、ドキュメントを検索する)。すべてのツール呼び出しは潜在的な失敗ポイントなので、印を付けましょう。

判断ポイント——条件によって経路が分岐する場所(カテゴリ = 課金なら左、カテゴリ = 技術なら右)。これらは明示的でなければならず、モデルの判断に任せてはいけません。

レビュー関門——人間が出力をチェックしてから、ワークフローが続行する場所。最初は入れていませんでした。その代償については Step 5 で触れます。

図を描くと、コードでは見えないものが見えてきます。私のワークフローには、エージェントが 2 つのノードの間で無限にループしうる分岐がありました——紙上ではすぐ気付くけれど、コードの中では、API 予算を燃やし尽くすまで見えなかったのです。

Step 3:ツールとデータアクセスを追加する

API、データベース、ドキュメント、ファイルシステム、ブラウザ

ツールはエージェントとチャットボットを分ける境界線です。しかし、痛い目を見て学んだことがあります:ツールは多ければいいわけではありません。 Anthropic のエンジニアリングチームも、ツールが多すぎたり、重複したツールがあったりすると、エージェントは効率的な戦略から逸れてしまう と書いています。

私のチケット振り分けは、6 つのツールから始めて、最終的に 3 つになりました。生き残ったのは:

  • ナレッジ検索——社内ドキュメントから関連する回答を探す
  • チケットシステム API——チケットのメタデータ(優先度、顧客ランク、履歴)を読む
  • 返信起草ツール——検索したコンテキストに基づいて返信を生成する

削った 3 つは何でしょうか? Web 検索ツール(社内チケットには不要)、感情分析ツール(LLM 自身が十分にうまく処理する)、通知ツール(エージェントループの外で扱うほうがよい)。

各ツールには、モデルに何をするかだけでなく いつ使うかを伝える明確な説明文が必要です。「請求関連の質問のときにこのツールを使う」のほうが「請求データベースに問い合わせる」よりはるかに役に立ちます。

ツールの説明をちゃんと書けているか、私はまだ自信がありません。この部分はずっと後になるまで気付かない形で間違っている、そんな気がしています。

Step 4:本当に役立つところにだけメモリを足す

何を覚えるか、何を再計算するか、何を捨てるか

メモリはエージェント設計のなかで最も過剰に使われている機能です。どのワークフローにも必要なわけではありません。Anthropic のエンジニアリングチームは コンテキストを「重要だが有限なリソース」と表現しています——課題は、何を残し、何を捨てるかを最適化することです。

私のチケット振り分けは単発のワークフローとして動いています——メッセージが入ってきて、処理され、結果が出ていく。メモリは要りません。各実行が新規に始まるので、デバッグが簡単で、振る舞いが予測可能です。

しかし、もし顧客の継続中の問題を追跡する複数ターンのアシスタントを作るなら、メモリは必須になります。問うべきは「メモリを追加すべきか?」ではなく、「エージェントが忘れたら出力が悪くなる具体的な情報は何か?」 です。

判断を助けてくれた 3 つの分類があります:

覚えるもの: 顧客 ID、継続中の問題の会話履歴、過去の解決試行。これらがないと、エージェントは同じ診断質問を 2 度も訊くことになります。

再計算するもの: 現在のチケット状態、最新のナレッジベース検索結果。これらはセッションをまたいで変わるので、キャッシュすると古いコンテキストの問題を生みます。

捨てるもの: 途中の推論ステップ、失敗したツール呼び出し、デバッグログ。これらをコンテキストに残しておくとトークンを浪費し、後続の実行でモデルを混乱させる可能性があります。

Step 5:検証と人間のレビューを追加する

テストケース、チェックリスト、引き継ぎポイント

人間のレビューを追加したのはかなり遅くなってからでした——「動いている」バージョンをすでにデプロイした後です。よく考えると、「動いている」とは「出力を生み出している」という意味で、「正しい出力を生み出している」ではありませんでした。

検証には 2 層あります:自動と人間。

自動テストケースは、モデルが常に正解すべきものをチェックします。私は既知の正解分類が付いたテスト入力を 30 件ほど書きました。エージェントが 27 件未満しか正解しなければ、何かが壊れている、というサインです。これはデプロイのたびに走ります。

人間のレビューは、自動テストでは捉えられないもの——トーン、ニュアンス、起草された返信がこの顧客にとって本当に意味を成すか——をカバーします。私はシンプルな引き継ぎを設定しました:起草された返信はすべてキューに入り、人間が承認または編集し、その編集結果がプロンプト改善へフィードバックされます。

引き継ぎポイントの位置が重要です。 人間のレビューを 15 ステップのパイプラインの最後に置いてはいけません。エージェントの判断が誤りうる最も早い時点 に置いてください。私の場合、それは分類のすぐ後でした——カテゴリが間違っていたら、下流のすべてが無駄になります。

Step 6:自動化の前に失敗テストを走らせる

ツール失敗、悪い入力、古いコンテキスト、誤った出力

このステップが、エージェントワークフローについての考え方を変えました。

ワークフローを本物のトラフィックに触れさせる前に、ありうるすべての失敗ケースに対して走らせました:

ツール失敗: ナレッジベース API がタイムアウトしたら? 最初のバージョンはハングしました。今は 1 回リトライし、それでもダメなら汎用的な返信にフォールバックして人間にフラグを立てます。

悪い入力: 空のメッセージ、想定外の言語、実は画像だったメッセージが来たら? エージェントはどれもクラッシュせずに処理できなければなりません。

古いコンテキスト: ナレッジベースが更新されていないのに、プロダクトは変わっていたら? エージェントは自信満々に古い情報を引用します。タイムスタンプチェックを足しました——ドキュメントが 30 日より古ければ、返信に注意書きを入れます。

誤った出力: エージェントは正しく分類したけど、ひどい返信を書いてしまったら? これは自動テストが一番難しい部分です。私は 2 回目の LLM 呼び出しを評価役として使いました——スタイルガイドと照合して、おかしいところに印を付けます。

失敗テストが捕まえた問題は、ハッピーパステストでは絶対に見つけられなかったものでした。このステップは絶対に飛ばさないでください。

FAQ

動く AI エージェントワークフローを作るのにどれくらいかかりますか?

基本的な単一タスクのワークフローなら、数日で動かせます。本番運用に耐えうる信頼性——検証、失敗処理、人間のレビューを含む——に達するには 2〜4 週間かかります。

完全な AI エージェントワークフローをゼロから作るには?

まずワークフロー契約を定義します。狭いタスクをひとつ選びます。視覚的にマップします。エージェントが本当に必要とするツールだけを追加します。デプロイ前に検証と失敗テストを組みます。

エージェントワークフローの設計で外せないステップは?

契約定義、タスク範囲、視覚的な作図、ツール選択、メモリの判断、検証層、失敗テスト。どれかを飛ばすと、後で複利的に大きくなる問題を生みます。

ずっと頭から離れない考えがあります:AI エージェントワークフローを作る上でいちばん難しいのは、作ること自体ではなく、自分が作ったものが本当に動いているかを知ること、そして先週入れた修正が来月もまだ通用するかを知ること、なのです。 生き残るワークフローは、検証され、バージョン管理され、エンジニアリング資産として扱われます。

これが、私が EvoMap を見始めたきっかけでもあります。成功したワークフロー——あるエージェントが問題を解決するために通った経路——を捕捉し、検証し、別のエージェントがゼロから作り直さずに継承できる、という発想です。実務で具体的にどう機能するかはまだよく分かりません。ただ、問いの方向は正しいと感じます:ワークフローは、成功した後どうなるのか?

……このあたりの技術がどう進化していくか、引き続き見ていこうと思います。

過去の記事

  • 実装の詳細に入る前にワークフローアーキテクチャの全体像を見たい方は、What Are Agentic Workflows? Types, Examples, and Production Reality が主要なワークフローパターンと、それぞれが本番でうまくいきやすい場所・失敗しやすい場所を整理しています。
  • 「ワークフロー vs 自律的推論」という問いは、Dify Agent vs Workflow: What's the Difference? に直接つながります。とくに、構造化されたパイプラインとエージェント駆動の振る舞いをいつ使い分けるかで迷っているときに役に立ちます。
  • 外部アクションを足し始めるとツール選択が一気に重要になります。What Is MCP? The AI Tool Connection Standard Explained は、現代のエージェントが共通インターフェース経由で API、ツール、データソースにどう接続するかを説明しています。
  • 複数ステップのシステム内部での実行挙動をより深く見たい方には、Agent Hooks: How AI Execution Chains Actually Work が、アクション、イベント、ワークフローチェーンが裏側でどう協調しているかを掘り下げています。
  • 本記事の最後の問い——ワークフローが一度成功した後はどうなるのか——は自然と EvoSkills: Self-Evolving Skills Proved につながります。成功したエージェントの振る舞いがどう一度きりの実行を超えて再利用可能なケイパビリティへと進化していくかを扱っています。

関連記事