Open5

Agent , Workflows 実装調査

knaka Tech-Blogknaka Tech-Blog

概要

  • AI Agent 調査内容、実装等の例になります。
  • Agent系ライブラリ等を調査しましたが。実装例が少ないようで。難航したので
  • 関連記事参考に、実装する事に。しました。
  • 主にWorkflows 、シーケンス実行になります。

[ 公開 2025/06/10 ]


関連

  • anthropic , building-effective-agents

https://www.anthropic.com/engineering/building-effective-agents


  • 上記の要約部分
この文書は、効果的なAIエージェントの構築に関するAnthropic社の考察をまとめたものです。
同社は、大規模言語モデル(LLM)エージェントを開発する多数のチームとの協業を通じて得られた知見を共有しており、
複雑なフレームワークよりもシンプルで構成可能なパターンが最も成功していると強調しています。
ワークフローとエージェントの明確な区別を設け、
それぞれをいつ使用すべきか、そしてプロンプト連鎖、
ルーティング、並列処理、オーケストレーターワーカー、評価者最適化などの具体的なワークフローパターンについて詳しく説明しています。
さらに、
ツール定義の重要性や、顧客サポートやコーディングエージェントといった実際の応用例も提示し、
システムのシンプルさ、透明性、そして綿密なツール設計という3つの核となる原則を提唱しています。


  • エージェントについて( コピー )
タイトル

AIエージェントについて、ソースに基づき説明します。
「エージェント」という言葉は、
さまざまな方法で定義されますが、Anthropic社ではこれらを総称して**「エージェント的システム (agentic systems)」と分類し、その中で「ワークフロー (workflows)」と「エージェント (agents)」
という重要なアーキテクチャ上の区別を設けています。


ワークフローとは、LLM(大規模言語モデル)とツールが事前に定義されたコードパスを通じて調整されるシステムです。

一方、エージェントは、LLMが自身のプロセスとツールの使用を動的に指示し、タスクの実行方法を自律的に制御するシステムです。
エージェント的システムの利用について
LLMでアプリケーションを構築する際には、可能な限りシンプルな解決策を見つけ、必要な場合にのみ複雑さを増すことが推奨されます。エージェント的システムは、タスクパフォーマンスを向上させるために、レイテンシ(遅延)とコストを犠牲にすることが多いため、このトレードオフがいつ意味をなすかを考慮する必要があります。
より複雑なシステムが必要な場合、ワークフローは、明確に定義されたタスクに対して予測可能性と一貫性を提供します。一方、エージェントは、柔軟性とモデル駆動型の意思決定が大規模に必要とされる場合に優れた選択肢となります。しかし、多くのアプリケーションでは、Retrieval(情報検索)やインコンテキストの例を使った単一のLLM呼び出しの最適化で十分な場合が多いです。
フレームワークの活用
LangGraph、Amazon BedrockのAI Agentフレームワーク、Rivet、Vellumなど、エージェント的システムの導入を容易にする多くのフレームワークが存在します。これらは、LLMの呼び出し、ツールの定義と解析、呼び出しの連鎖といった標準的な低レベルのタスクを簡素化することで、迅速な開始を可能にします。
しかし、これらのフレームワークは、根本にあるプロンプトや応答を曖昧にする追加の抽象化レイヤーを作成し、デバッグを困難にすることがあります。また、よりシンプルな設定で十分な場合でも、複雑さを追加したくなる誘惑を生むこともあります。開発者は、LLM APIを直接使用することから始めることを推奨されており、多くのパターンは数行のコードで実装できます。フレームワークを使用する場合は、その根底にあるコードを理解していることを確認することが重要です。
構成要素とワークフローのパターン
エージェント的システムの基本的な構成要素は、情報検索、ツール、メモリなどの機能で
強化されたLLM(拡張LLM)です。
現在のモデルは、これらの能力を積極的に使用し、独自の検索クエリを生成したり、適切なツールを選択したり、保持すべき情報を決定したりすることができます。
Anthropic社がプロダクションで確認した、エージェント的システムの一般的なパターンには以下のようなものがあります。

プロンプト連鎖 (Prompt chaining): タスクを連続するステップに分解し、各LLM呼び出しが前の出力Lを処理します。タスクを固定されたサブタスクに簡単かつ明確に分解できる場合に最適です。例としては、マーケティングコピーの生成とその翻訳、文書のアウトライン作成、チェック、そして文書作成などがあります。

ルーティング (Routing): 入力を分類し、専門的な後続タスクに振り分けます。これは、複雑なタスクで、異なるカテゴリが個別に処理される方が適している場合に効果的です。顧客サービス問い合わせの異なるタイプを振り分けたり、簡単/一般的な質問をより小さいモデルに、難しい/珍しい質問をより高性能なモデルにルーティングしたりする例があります。

並列化 (Parallelization): LLMがタスクを同時に処理し、その出力をプログラムで集約します。これには「セクショニング(独立したサブタスクへの分割)」と「投票(同じタスクを複数回実行して多様な出力を得る)」の2つの主要なバリエーションがあります。速度のためにサブタスクを並列化できる場合や、より高い信頼性のために複数の視点や試行が必要な場合に効果的です。

セクショニングの例:ガードレール(不適切なコンテンツのスクリーニングと応答を別のモデルインスタンスが処理する)や、LLMのパフォーマンス評価の自動化。

投票の例:コードの脆弱性レビューや、コンテンツが不適切かどうかの評価。

オーケストレーター・ワーカー (Orchestrator-workers): 中央のLLMが動的にタスクを分解し、それをワーカーLLMに委任して結果を統合します。必要なステップ数やタスクの内容が予測できない複雑なタスクに適しています。例としては、複数のファイルに複雑な変更を加えるコーディング製品や、複数のソースから情報を収集・分析する検索タスクがあります。

評価者・最適化者 (Evaluator-optimizer): 1つのLLMが応答を生成し、別のLLMがループ内で評価とフィードバックを提供します。明確な評価基準があり、反復的な洗練が測定可能な価値を提供する際に特に効果的です。人間がフィードバックをすることでLLMの応答が明らかに改善される場合や、LLM自体がそのようなフィードバックを提供できる場合が適しています。
エージェントの詳細と利用
エージェントは、複雑な入力の理解、推論と計画、ツールの信頼性のある使用、エラーからの回復といった主要な能力がLLMで成熟するにつれて、実用化されつつあります。エージェントは、人間ユーザーからのコマンドや対話を通じて作業を開始し、タスクが明確になったら独立して計画し、動作します。実行中に環境からの「真実(ツール呼び出しの結果やコード実行など)」を得て進捗を評価することが重要です。エージェントは、チェックポイントで、またはブロックに遭遇したときに人間のフィードバックのために一時停止することができます。
エージェントは高度なタスクを処理できますが、その実装はしばしばシンプルです。通常、これらは環境からのフィードバックに基づいてツールを使用するLLMに過ぎません。したがって、ツールセットとそのドキュメントを明確かつ思慮深く設計することが極めて重要です。
エージェントは、必要なステップ数を予測することが困難または不可能なオープンエンドな問題や、固定されたパスをハードコードできない場合に活用できます。LLMが多くのターンにわたって動作する可能性があり、その意思決定にある程度の信頼を置く必要があります。エージェントの自律性は、信頼できる環境でのタスクのスケーリングに理想的です。
エージェントの自律的な性質は、コストの増加やエラーが複合する可能性を意味します。サンドボックス環境での広範なテストと適切なガードレールの設定が推奨されます。
エージェントが有用な例:
•SWE-benchタスクを解決するコーディングエージェント(タスク記述に基づいて多数のファイルを編集する)。
•Anthropic社の「コンピューター使用」リファレンス実装(Claudeがコンピューターを使用してタスクを達成する)。
エージェント構築の原則とツールのプロンプトエンジニアリング
エージェントを実装する際には、以下の3つの核となる原則に従うことが推奨されています。
1.
エージェントの設計においてシンプルさ (simplicity) を維持する。
2.
エージェントの計画ステップを明示的に示すことで透明性 (transparency)
を優先する。
3.
徹底したツール ドキュメント作成とテスト (documentation and testing)を通じて、エージェント・コンピューター・インターフェース (ACI) を慎重に作成する。
どのようなエージェント的システムを構築する場合でも、ツールはエージェントの重要な部分となる可能性が高いです。ツールは、Claudeが外部サービスやAPIと連携できるようにします。ツールの定義と仕様には、全体的なプロンプトと同様に、プロンプトエンジニアリングの注意を払うべきです。
ツールのフォーマットを決定する際には、以下の点が提案されています。

モデルに、考え込んで「窮地に陥る」前に十分なトークンを与える。

フォーマットを、インターネット上のテキストで自然に発生するモデルが慣れているものに近づける。

何千行ものコードの正確なカウントを維持したり、書くコードをエスケープしたりするようなフォーマットの「オーバーヘッド」がないようにする。
良い**エージェント・コンピューター・インターフェース(ACI)**を作成するためには、以下のような検討が重要です。

モデルの立場になって考える。説明やパラメータからツールの使い方が明白か、それとも慎重に考える必要があるか。

パラメータ名や説明を変更して、より分かりやすくする方法を考える。これは、チームの新人開発者向けに優れたドキュメントストリングを書くのと同様に考えるべきです。

モデルがツールをどのように使用するかをテストする。多くの入力例をワークベンチで実行し、モデルがどのような間違いを犯すかを確認し、改善を繰り返す。

ツールをポカヨケする。間違いを犯しにくくなるように引数を変更する。
SWE-bench向けのエージェントを構築する際には、全体のプロンプトよりもツールの最適化に多くの時間を費やしたと述べられています。例えば、エージェントがルートディレクトリから移動した後に、相対ファイルパスを使用するツールでモデルが間違いを犯すことが判明し、ツールを常に絶対ファイルパスを要求するように変更したところ、モデルは問題なくこの方法を使用するようになったとのことです。
最終的に、LLM分野での成功は、最も洗練されたシステムを構築することではなく、ニーズに合った「正しい」システムを構築することにかかっています。シンプルなプロンプトから始め、包括的な評価でそれらを最適化し、よりシンプルな解決策が不十分な場合にのみ多段階のエージェント的システムを追加することが推奨されています

knaka Tech-Blogknaka Tech-Blog

Workflows シーケンス処理 実装

  • シーケンス処理的な、タスク処理
  • 前のMCP例 TODO表示、CSVダウンロード
  • データは、スプレッドシート例と同様 API連携

概要

  • LLM gemini
  • React構成
  • Vercel AI SDK
  • Google スプレッドシート
  • AppSheet ノーコード
  • node 20

書いたコード


.env

GOOGLE_GENERATIVE_AI_API_KEY: gemini の鍵
GOOGLE_API_KEY: アプリ鍵
SPREADSHEET_ID_1: スプレッドシート ID

GOOGLE_GENERATIVE_AI_API_KEY="api-key"
GOOGLE_API_KEY="api-key"
SPREADSHEET_ID_1=""

  • Agent
  • mcp_react3/src/agent/sheet-list-agent.ts
  • toolを、連続して呼び出します。

https://github.com/kuc-arc-f/rolldown_2ex/blob/main/mcp_react3/src/agent/sheet-list-agent.ts

import AgentUtil  from '../lib/AgentUtil';

export async function SheetListAgent(){
  try{
    let text = "### Step1: リストを markdown記法の表形式で表示" + "\n";
    text += await AgentUtil.sendTool("getSheetTestで、リストを markdown記法の表形式で表示して欲しい");

    text += "### Step2: 一覧のCSVダウンロードのリンク表示" + "\n";;
    text += await AgentUtil.sendTool("getSheetCsvで。一覧のCSVダウンロードのリンク表示して欲しい。");

    return text;
  }catch(e){
    console.error(e);
    throw new Error('Error , SheetListAgent');
  }
}
  • Step1: TODO, テーブル表示
  • Step2: CSVダウンロードリンクの追加

knaka Tech-Blogknaka Tech-Blog

プロンプト内パラメータを、各toolに渡す Workflows

  • プロンプト内の数値等を抽出し。各 toolに引数渡す例になります

概要

  • LLM gemini
  • React構成
  • Vercel AI SDK
  • Google スプレッドシート
  • AppSheet ノーコード
  • node 20

書いたコード


.env

  • GOOGLE_GENERATIVE_AI_API_KEY: gemini の鍵
  • GOOGLE_API_KEY: アプリ鍵
  • SPREADSHEET_ID_2: スプレッドシート ID
GOOGLE_GENERATIVE_AI_API_KEY="api-key"
GOOGLE_API_KEY="api-key"
SPREADSHEET_ID_2=""
CSV_PATH_BASE="http://localhost:3000/data/"

  • Agent
  • mcp_react3/src/agent/price-list-up-agent.ts
  • toolを、パラメータ渡し。連続して呼び出します。

https://github.com/kuc-arc-f/rolldown_2ex/blob/main/mcp_react3/src/agent/price-list-up-agent.ts

    let target = inputText.replace(/[^0-9]/g, '')
    console.log("target=", target);
    if(!target){
      throw new Error("Error, target=NULL");
    }

    let text = "";
    const step1num = Number(target);
    let valid = AgentUtil.validateNumber(step1num)
    console.log("step1num.valid=", valid);
    if(valid === false){
      throw new Error("Error, validateNumber is NG");
    }
    text += "### Step1: 指定価格以上のリストを表示します。" + "\n";
    let cmd = `getPriceListUp 価格: ${step1num} 円以上の。リストを markdown記法の表形式で表示して欲しい`;
    console.log("step1cmd=", cmd);
    text += await AgentUtil.sendTool(cmd);
    //Step-2
    cmd = `getPriceUpTotal 価格: ${step1num} 円以上`;
    console.log("step2cmd=", cmd);
    text += "### Step2: 指定価格以上の合計金額を表示します。" + "\n";
    text += await AgentUtil.sendTool(cmd);
  • Step1: 指定金額範囲、購入リスト テーブル表示
  • Step2: 指定金額範囲、合計計算 表示


プロンプト、参考

price-list-up-agent 200 円以上

knaka Tech-Blogknaka Tech-Blog

初級編 Workflow の例

  • 初級編的な、シーケンス実行例です。
  • 簡単な、外部API連携なしの例になります。
  • サイコロ実行、日付の表示、時刻の表示

概要

  • LLM gemini
  • React構成
  • Vercel AI SDK
  • node 20

書いたコード


.env

  • GOOGLE_GENERATIVE_AI_API_KEY: gemini の鍵
GOOGLE_GENERATIVE_AI_API_KEY="api-key"

  • tool を、三種類追加します。

  • mcp_react3/src/tools/firstGetRandom.ts

  • mcp_react3/src/tools/firstGetDate.ts

  • mcp_react3/src/tools/firstGetTime.ts


  • Agent
  • mcp_react3/src/agent/first-agent.ts
  • toolを、連続して呼び出します。

https://github.com/kuc-arc-f/rolldown_2ex/blob/main/mcp_react3/src/agent/first-agent.ts

    let text = "";
    text += "### Step1: サイコロを振ります。" + "\n";
    let cmd = `firstGetRandom 6`;
    console.log("step1cmd=", cmd);
    text += await AgentUtil.sendTool(cmd);
    text += "***\n";
    //Step-2
    cmd = `firstGetDate`;
    console.log("step2cmd=", cmd);
    text += "### Step2: 現在の 日付を返します。" + "\n";
    text += await AgentUtil.sendTool(cmd);
    text += "\n" + "***\n";
    //Step-3
    cmd = `firstGetTime`;
    console.log("step3cmd=", cmd);
    text += "### Step3: 現在の 時間を返します。" + "\n";
    text += await AgentUtil.sendTool(cmd);
    text += "\n" + "***\n";
  • Step1: サイコロ実行
  • Step2: 日付の表示
  • Step3: 時刻の表示

プロンプト、参考

first-agent

knaka Tech-Blogknaka Tech-Blog

Agent UI 修正、各タスク完了後の表示

  • 機能的に、前回とほぼ同等
  • 各タスク後に、再描画する変更
  • フロント側で、各タスク起動するように修正。

概要

  • LLM gemini
  • React構成
  • Vercel AI SDK
  • node 20

書いたコード


プロンプト、参考

price-list-updown-agent 最低金額: 100 円 , 最高金額: 200 円

  • 初級版
first-agent

GIF 動画

  • 4 ステップ


  • 初級者編