AI Agentアプリ開発入門：Workflow・tool calling・guardrails・structured outputの使い分け

3行まとめ

このテーマをもう少し広げて見るなら、OpenAI Agents SDKのguardrailsを置く場所：input・output・tool・handoffの境界 と Vercel AI SDKのtool approval設計：needsApproval・toolApproval・WorkflowAgentの使い分け も合わせて確認してください。この記事のguardrails節から、input、output、tool、handoffへ検査を分ける実装判断に進めるため。

Workflow

手順、分岐、再実行、承認待ちを管理します。

Tool

外部APIや社内ツールを呼ぶ入口を制限します。

Guardrails

入力、出力、ツール実行前後を検査します。

Output

結果を保存やUI表示に使える型へ固定します。

Agentアプリは、賢い1つの箱ではなく責務の分割として見ると安定します。

• AI Agentアプリは、Workflow、tool calling、guardrails、structured outputを分けて設計すると、失敗条件とレビュー箇所が見えやすくなります。
• 2026年5月28日時点で、公式ドキュメントとnpm情報から確認したlatestは@openai/agents@0.11.5、@langchain/langgraph@1.3.2、@mastra/core@1.37.1、ai@6.0.191です。
• 実務導入では、まずread-onlyのtool calling、小さなWorkflow、人間承認、構造化された結果保存から始めるのが安全です。

本文の事実確認には、公式ドキュメント、公式ヘルプ、関連する仕様・SDKドキュメントを使っています。実リポジトリでの性能ベンチマークや更新代行は、本文で明記した場合を除き実施していません。

この記事でわかること

部品の役割

4つの部品を何に使うか整理できます。

選定観点

SDKやフレームワークを見る軸を作れます。

安全策

権限、承認、ログ、失敗条件を決められます。

フレームワーク比較より先に、アプリ側の責務を決めます。

• AI Agentアプリで混ざりやすい4つの部品の役割
• OpenAI Agents SDK、LangGraph、Mastra、Vercel AI SDKを選ぶときの見方
• 実務タスクをWorkflow、tool calling、guardrails、structured outputに分解する手順
• 失敗しやすい設計と、導入前に置くべき安全策
• 小規模チームで最初に作るべき最小構成

前提知識

項目	内容	見方
Workflow		決まった手順や承認待ちをコードで扱います。
tool calling		外部機能を呼び出す接点を作ります。
guardrails		危険な入力や出力を別層で止めます。
structured output		結果を型付きデータとして扱います。

役割を分けると、失敗時に原因を追いやすくなります。

ここでいうAI Agentは、単にLLMへ長いプロンプトを投げるチャットボットではありません。ユーザーの依頼を受け、状態を持ち、必要に応じて外部ツールを呼び、結果を検証し、次の手順へ進むアプリケーションを指します。

実務で扱うときは、Agentを「賢い1つの箱」として見ないほうが安定します。たとえばPRレビュー支援を作る場合でも、内部では少なくとも次の処理が分かれます。

部品	役割	例
Workflow	手順、分岐、再実行、承認待ちを管理する	PR取得、差分要約、テスト実行、レビュー生成、人間承認
tool calling	LLMが外部機能を呼ぶための接点を作る	GitHub API、テスト実行、ドキュメント検索、MCPツール
guardrails	入力、出力、ツール呼び出しの前後で制約をかける	repo allowlist、危険コマンド拒否、秘密情報検出、出力形式チェック
structured output	LLMの最終結果をアプリで扱える形に固定する	JSON Schema、Zod schema、レビュー指摘リスト、承認リクエスト

この4つを混ぜると、あとで事故の原因が追えません。「モデルが勝手にコメントした」のか、「toolの権限が広すぎた」のか、「Workflowの再実行で二重投稿した」のか、「JSONは返ったが業務ルールに反した」のかが分からなくなります。

まず4つを混ぜない

1. 1手順

   順序や分岐はWorkflowへ置きます。

2. 2外部操作

   APIや社内ツールはtool callingへ置きます。

3. 3制約

   禁止条件はguardrailsへ置きます。

4. 4結果

   保存や表示はstructured outputへ置きます。

最初に責務を分けると、後から権限を絞りやすくなります。

AI Agentアプリの設計で最初に決めるべきなのは、どこをLLMに任せ、どこを普通のプログラムで固定するかです。判断の目安は次の通りです。

やりたいこと	主に使う部品	理由
決まった手順を毎回同じ順序で進めたい	Workflow	手順、分岐、再試行、承認待ちをコードで管理できる
必要なときだけ外部APIや社内ツールを呼びたい	tool calling	モデルに選ばせる余地を残しつつ、入力schemaと権限を制限できる
危険な入力、出力、ツール呼び出しを止めたい	guardrails	モデルの判断とは別の検査層を置ける
結果をDB保存、UI表示、後続処理に渡したい	structured output	自然文ではなく型付きデータとして扱える

たとえば、請求書の問い合わせに回答するAgentで「契約プランを調べる」処理はtool callingです。「未払いがあれば法務確認へ回す」処理はWorkflowです。「顧客IDが許可された範囲か確認する」処理はguardrailsです。「回答の根拠、金額、次アクションをJSONで返す」処理はstructured outputです。

この切り分けを先に置くと、フレームワーク選定も楽になります。すべてを1つのAgentループに押し込む必要はありません。

Workflowは手順と再実行性のために使う

1. 取得

   入力や対象データを集めます。

2. 判断

   分岐や承認要否を決めます。

3. 承認

   必要なら人間入力を待ちます。

4. 実行

   承認済みの内容だけ処理します。

5. 記録

   結果とログを残します。

再実行できる設計にすると、途中失敗から戻りやすくなります。

Workflowは、AI Agentアプリの「業務手順」をコードに落とす場所です。Mastraの公式Workflow説明では、複雑な複数ステップの処理を、1つのAgentの推論に頼るのではなく、明確なステップとして定義するための仕組みとして紹介されています。順次実行、並列実行、分岐、ループ、エラー処理、Agentやtoolとの組み合わせが主な使いどころです。

LangGraphも同じ領域に強い選択肢です。公式ドキュメントでは、LangGraphは長時間動くstatefulなAgentのための低レベルなオーケストレーションruntimeとして説明され、durable execution、streaming、human-in-the-loop、persistenceが中心機能として挙げられています。

Workflowを使うべきなのは、次の条件に当てはまるときです。

• 人間承認を途中に入れる
• 失敗後に同じ地点から再開したい
• 外部API、DB書き込み、ファイル操作など副作用がある
• 各ステップのログと状態を監査したい
• 1回のLLM呼び出しでは終わらない

逆に、1回の質問に対して文章を返すだけなら、最初からWorkflow runtimeを入れる必要はありません。設計を重くすると、トラブル時に見る場所が増えます。

Workflowで注意すること

Workflowは「状態を保存できるから安全」ではありません。再開時に副作用が重複しないようにする必要があります。

LangGraphのdurable executionドキュメントでは、再開時にコードが停止した行から再開するのではなく、適切な地点から再実行されること、非決定的な処理や副作用をtaskやnodeに包むこと、idempotentな処理にすることが重要だと説明されています。これは実務でもかなり大事です。

PRレビュー支援でいうと、「GitHubへコメント投稿するstep」が再試行されるなら、同じコメントを二重投稿しないidempotency keyが必要です。「テストを実行するstep」は何度走ってもよいかもしれませんが、「リリースタグを作るstep」は人間承認なしで再実行してはいけません。

tool callingは外部操作の入口にする

項目	内容	見方
schema		入力形式を固定し、曖昧な引数を減らします。
allowlist		呼べるAPI、repo、commandを絞ります。
side effect		書き込みや送信は承認前提にします。
log		実行内容と結果を追えるようにします。

ToolはAIの腕を伸ばす場所なので、境界を先に決めます。

tool callingは、LLMがアプリケーション内の関数や外部システムを呼ぶ仕組みです。Vercel AI SDKのTool Callingドキュメントでは、toolはdescription、inputSchema、任意のexecuteを持つものとして説明され、generateTextやstreamTextに渡せます。OpenAIのStructured Outputsドキュメントでも、システム内の機能やデータにつなぐ場合はfunction callingを使う、ユーザーへ返す形式を固定したい場合は構造化されたresponse formatを使う、という切り分けが示されています。

tool callingで大事なのは、モデルに「何でもできる関数」を渡さないことです。最初はread-onlyのtoolから始めます。

import { tool } from "ai";
import { z } from "zod";

export const listPullRequestFiles = tool({
  description: "許可されたリポジトリのPR差分ファイル名をread-onlyで取得する",
  inputSchema: z.object({
    owner: z.string(),
    repo: z.string(),
    pullNumber: z.number().int().positive(),
  }),
  execute: async ({ owner, repo, pullNumber }) => {
    if (!isAllowedRepo(owner, repo)) {
      throw new Error("repository is not allowed");
    }

    return fetchPullRequestFilesReadOnly({ owner, repo, pullNumber });
  },
});

この例では、toolのschemaはあくまで入力の形を制限するだけです。実務では、isAllowedRepoのような権限チェックを別に置きます。schemaがあるから安全、ではありません。

MCPを使う場合も考え方は同じです。外部ツールをMCP Serverとして切り出しても、権限が広いtoolを渡せば危険です。MCP側のToolsや認可、Transportの更新影響を見るときは、MCP更新で壊さないための確認手順のように、まずread-onlyで境界を作るのが現実的です。

tool callingで注意すること

条件

write系toolを渡す前に、対象repo、対象branch、実行できるcommand、外部通信先、timeout、承認者を普通のコードで固定します。

注意点

schemaは入力形式を縛るだけで、実行権限までは守りません。deleteFile、createIssue、sendEmailのような副作用を持つtoolは、承認済みpayloadだけを受け取り、実行ログを残す形にします。

tool callingの失敗は、単なる例外だけではありません。

• モデルが存在しないtoolを呼ぶ
• schemaに合わない引数を作る
• toolの実行がtimeoutする
• tool resultが大きすぎて次のLLM入力を圧迫する
• toolが副作用を持ち、再試行で二重実行される
• ユーザー入力がtool引数に入り、想定外のリソースへアクセスする

Vercel AI SDKのTool Callingドキュメントでは、tool call関連のエラーとしてNoSuchToolError、InvalidToolInputError、ToolCallRepairErrorが説明されています。これは、実務でも監視対象にしたほうがよい分類です。

また、複数stepのtool callingでは上限が必要です。モデルが調査を続けすぎると、コストも時間も読みにくくなります。maxStepsやstopWhenのような停止条件、toolごとのtimeout、結果サイズの制限は最初から入れておきます。

guardrailsはモデルとは別の検査層にする

入力

秘密情報や対象外データを止めます。

出力

形式違反や禁止表現を止めます。

Tool

危険な引数や対象外操作を止めます。

権限

ユーザーや環境ごとの実行可否を見ます。

安全策はプロンプトだけに寄せず、別の検査層として置きます。

guardrailsは、入力、出力、tool呼び出しの前後に置く検査です。禁止トピックのような会話ポリシーだけでなく、実務では権限、形式、コスト、秘密情報、危険操作を止めるために使います。

OpenAI Agents SDKのGuardrailsドキュメントでは、tool guardrailsはtool()で定義するfunction toolに適用されると説明されています。一方で、handoff、hosted tools、built-in execution tools、agent.asTool()には同じguardrail pipelineがそのまま適用されない注意も書かれています。ここは導入時に見落としやすい点です。

guardrailsは、1か所に置けば終わりではありません。次のように分けます。

場所	目的	例
入力前	扱ってよい依頼か確認する	対象repo、ユーザー権限、プロジェクトID、機密情報の混入
tool実行前	実行してよい操作か確認する	read-onlyか、書き込みか、承認済みか、allowlist内か
tool実行後	戻り値を次のLLM入力に入れてよいか確認する	秘密情報マスク、最大文字数、不要な個人情報の削除
最終出力前	ユーザーやDBに渡してよいか確認する	JSON schema、業務ルール、危険な指示の混入

特にコード実行、ファイル編集、DB更新、外部APIの書き込みは、tool実行前のguardrailが重要です。最終出力だけを検査しても、すでに外部操作が終わっていれば遅いからです。

guardrailsで注意すること

根拠

guardrailsは、モデルに「気をつけて」と頼む代わりではありません。入力、tool引数、出力、保存前データをそれぞれ検査し、違反時に止めるための層です。

評価基準

最初の評価では、禁止repo、secretらしい文字列、巨大diff、外部POST、未承認writeを意図的に混ぜ、guardrailsが止められるかを確認します。

guardrailsを「LLMにもう一度チェックさせる」だけにすると、肝心なところで揺れます。秘密情報の検出、パス制限、repo allowlist、コマンドallowlist、金額上限、承認済みユーザーの確認は、できるだけ通常のコードで判定します。

LLMを使うguardrailは、曖昧な分類や文章評価に向いています。たとえば「このレビューコメントは攻撃的すぎないか」「ユーザーへ出す説明として根拠が足りるか」はLLM評価でも意味があります。しかし、「このAPIキーをログに出してよいか」「このリポジトリに書き込んでよいか」は、LLMではなくプログラムで止めます。

structured outputは最終結果の契約にする

項目	内容	見方
status		成功、保留、失敗、要承認を分けます。
evidence		根拠や参照元を残します。
actions		次に実行する候補を配列にします。
risks		未確認点や注意点を別フィールドにします。

型があると、レビュー、保存、再実行がしやすくなります。

structured outputは、LLMの最終結果をアプリケーションが扱える形に固定するための契約です。OpenAIのStructured Outputsドキュメントでは、Structured OutputsはJSON modeより進んだ仕組みとして説明され、JSONとして有効であることだけでなくschemaへの準拠を扱います。Vercel AI SDK側でも、Core APIはstructured data生成やschema-compatibleなヘルパーを提供しています。

structured outputを使うべきなのは、次のような場合です。

• DBへ保存する
• UIで一覧表示する
• 後続のWorkflow stepへ渡す
• レビューや承認画面で人間が確認する
• テストで回帰を検知したい

PRレビュー支援なら、自然文だけではなく次のような形で返すと扱いやすくなります。

import { z } from "zod";

export const ReviewFinding = z.object({
  severity: z.enum(["info", "warning", "blocking"]),
  file: z.string(),
  line: z.number().int().positive().nullable(),
  summary: z.string(),
  evidence: z.string(),
  suggestedAction: z.string(),
});

export const ReviewResult = z.object({
  verdict: z.enum(["approve", "request_changes", "needs_human_review"]),
  findings: z.array(ReviewFinding),
  confidence: z.number().min(0).max(1),
});

ここで重要なのは、structured outputは業務ルールの代わりではないという点です。confidenceが0.9でも、blockingの指摘があるなら自動approveしない、といった判定はアプリ側で書きます。

structured outputで注意すること

確認項目

構造化出力では、status、confidence、evidence、risks、nextActions、needsHumanApprovalのように、UIとレビューで使う項目を先に決めます。

注意点

JSON SchemaやZod schemaに合っていても、内容が正しいとは限りません。根拠URL、対象ファイル、未確認範囲、人間レビュー要否を別フィールドにして、後続処理が鵜呑みにしない設計にします。

structured outputは、モデルやproviderによって対応範囲が変わります。OpenAIのStructured Outputsドキュメントでも、response formatでのStructured Outputsは対応モデルの条件が示されています。Vercel AI SDKのTool Callingドキュメントでも、strict tool callingはproviderやモデルによって対応が異なり、未対応の場合は無視されることがあると説明されています。

つまり、schemaを書けばどのモデルでも同じ挙動になるわけではありません。複数providerを切り替える場合は、同じschema、同じ入力、同じ期待値でスモークテストを用意します。

フレームワーク別の見方

項目	内容	見方
OpenAI Agents SDK		Agent、tool、handoff、guardrailsの扱いを確認します。
LangGraph		state、node、checkpoint、interruptを見ます。
Mastra		workflow、agent、tool approvalを見ます。
Vercel AI SDK		UI、tool calling、structured outputの接続を見ます。

どれが万能かではなく、止めたい場所と保存したい状態で選びます。

2026年5月28日時点で、公式ドキュメントとnpm情報から見る限り、4つの選択肢は次のように分けて考えると実務判断しやすいです。

選択肢	npm latest	向いている使い方	注意点
OpenAI Agents SDK	@openai/agents@0.11.5	OpenAI API前提で、Agent、tool、handoff、guardrails、tracingを軽く組みたい	tool guardrailsの適用範囲を公式ドキュメントで確認する。モデル/API料金は別途必要
LangGraph	@langchain/langgraph@1.3.2	長時間実行、human-in-the-loop、状態保存、再開、監査を重視する	低レベルなので設計力が要る。副作用のidempotency設計が必須
Mastra	@mastra/core@1.37.1	TypeScript中心でAgent、Workflow、tool、memory、MCPをまとめて扱いたい	dist-tagやAPIの動きが速い。導入時はlatestを固定するだけでなく更新手順を決める
Vercel AI SDK	ai@6.0.191	Next.jsやWeb UIで、streaming、tool calling、structured outputを素早く組みたい	Workflow runtimeそのものではない。承認待ちや再開は外部状態管理と組み合わせる

OpenAI Agents SDK

OpenAI Agents SDK for TypeScriptの公式トップページでは、少ないプリミティブでagentic AI appsを作るSDKとして説明されています。Agent、tool、handoff、guardrails、tracingのような概念をまとめて扱えるので、OpenAI API中心に作るなら初速が出ます。

ただし、guardrailsの適用範囲は必ず確認します。たとえばtool guardrailsが適用されるのはfunction toolであり、handoffやbuilt-in execution toolsに同じ扱いを期待してはいけません。sandboxやshellのような強い機能を使う場合は、SDKのguardrailsだけでなく、OS権限、作業ディレクトリ、ネットワーク、秘密情報の扱いも別に設計します。

LangGraph

LangGraphは、Workflowやstateful Agentの設計に向いています。公式Overviewでは、LangGraphは低レベルなorchestration runtimeで、durable execution、streaming、human-in-the-loop、persistenceに焦点を当てると説明されています。

特に、途中で人間承認を待つ、障害後に再開する、長時間の処理を扱う、といった要件では強いです。公式interruptsドキュメントでは、interrupt()でgraph executionをpauseし、checkpointerで状態を保存し、Commandでresumeする流れが説明されています。

一方で、低レベルなぶん、何をnodeにし、どの状態を保存し、どの副作用をtaskに分けるかを自分で決める必要があります。小さなチャット機能だけなら過剰です。

Mastra

Mastraは、TypeScriptでAgentアプリを組むときに、Workflow、Agent、tool、memory、MCPを近い距離で扱える選択肢です。公式Workflowページでは、単一Agentの推論に頼らず、明確なステップとして複数処理を定義し、順次、並列、分岐、ループを組み立てられると説明されています。

TypeScriptのWebアプリや業務アプリにAI処理を組み込みたい場合、Mastraは見通しがよいです。特に「ユーザー操作を受けてWorkflowを進め、途中でAgentやtoolを呼ぶ」形に向きます。

注意点は、APIや周辺パッケージの変化を前提に運用ルールを作ることです。検証時点のnpmではlatestが1.37.1、alphaが1.38.0-alpha.2でした。社内テンプレートでは、package versionを固定し、アップデート時にサンプルWorkflowを再実行するチェックを置くのが安全です。

Vercel AI SDK

Vercel AI SDKは、Web UIとLLM呼び出しの距離を縮めたいときに強いです。公式Referenceでは、generateText、streamText、structured output、tool、MCP client、provider registryなどがCoreの主要機能として並んでいます。Tool Callingドキュメントでは、ZodやJSON schemaを使った入力schema、tool実行、streaming中のtool input lifecycle hooks、エラー分類が説明されています。

Next.jsでチャット、レビュー画面、承認画面を作りたいなら、Vercel AI SDKは最初に検討する価値があります。ただし、AI SDK自体をWorkflow runtimeとして扱わないほうがよいです。承認待ち、再開、監査ログ、ジョブキューは、DBやqueue、LangGraph、Mastraなどと組み合わせます。

実務タスクを4つに分解する例

1. 1Workflow

   PR取得、差分要約、承認待ちを順番にします。

2. 2Tool

   GitHub APIやテスト実行を接続します。

3. 3Guardrails

   repo、branch、秘密情報、危険コマンドを確認します。

4. 4Output

   指摘、根拠、重要度をJSONにします。

例に落とすと、どこをLLMに任せるか決めやすくなります。

例として、「GitHub PRを読み、レビュー案を作り、人間が承認したらコメントする」AI Agentアプリを考えます。公開記事なので、実在の非公開repo、APIキー、社内コードは使いません。

要件

• 対象repoはallowlistに入ったものだけ
• 最初はPRへの書き込みをしない
• 差分、テスト結果、関連ドキュメントを読んでレビュー案を作る
• 人間が承認した場合だけGitHubへコメントする
• 指摘はseverity、file、line、evidence、suggestedActionを持つ
• 失敗時に途中から再開できる

分解結果

設計対象	実装すること
Workflow	PR取得、差分要約、テスト実行、レビュー案生成、承認待ち、コメント投稿をstepに分ける
tool calling	listPullRequestFiles、getPullRequestDiff、runTestsReadOnly、createReviewCommentAfterApprovalをtool化する
guardrails	repo allowlist、path allowlist、write toolの承認必須、秘密情報マスク、最大step数、timeout
structured output	ReviewResult schemaでレビュー案を返し、UIとDBに保存する

この分解にすると、実装前にレビューできるポイントが増えます。たとえば、createReviewCommentAfterApprovalだけはwrite権限を持つtoolにし、それ以外はread-onlyにできます。承認前にwrite toolを呼んだ場合はguardrailで拒否します。Workflowの状態には「承認済みか」「どのレビュー案に対する承認か」「投稿済みcomment idは何か」を保存します。

最小構成の擬似コード

type ReviewWorkflowState = {
  owner: string;
  repo: string;
  pullNumber: number;
  diffSummary?: string;
  testResult?: "passed" | "failed" | "skipped";
  reviewResult?: ReviewResult;
  approval?: {
    approved: boolean;
    approvedBy: string;
    approvedAt: string;
  };
  postedCommentId?: string;
};

async function reviewWorkflow(state: ReviewWorkflowState) {
  assertAllowedRepository(state.owner, state.repo);

  const diff = await tools.getPullRequestDiff.readOnly(state);
  state.diffSummary = await summarizeDiffAsStructuredData(diff);

  state.testResult = await tools.runTestsReadOnly(state);
  state.reviewResult = await generateReviewResult(state);

  await waitForHumanApproval(state.reviewResult);

  if (!state.approval?.approved) {
    return { status: "needs_revision", state };
  }

  state.postedCommentId = await tools.createReviewCommentAfterApproval.write(state);
  return { status: "posted", state };
}

この擬似コードで重要なのは、LLMがすべてを決めていない点です。repo制限、承認待ち、write toolの実行条件、投稿済みIDの保存は普通のコードで扱います。LLMは差分要約やレビュー案作成に使い、結果はschemaで受けます。

実行コマンドと確認結果

項目	内容	見方
version		SDKやpackageのバージョンを残します。
command		確認に使ったコマンドを残します。
result		成功、失敗、未検証を分けます。
date		確認日を残して更新時に追えるようにします。

検証情報は本文の判断材料として短く残します。

今回、記事内のversion情報は次のコマンドで確認しました。

npm view @openai/agents version dist-tags --json
npm view @langchain/langgraph version dist-tags --json
npm view @mastra/core version dist-tags --json
npm view ai version dist-tags --json

確認結果の要約です。

package	latest	補足
@openai/agents	0.11.5	dist-tagはlatestのみ確認
@langchain/langgraph	1.3.2	rcやnextも存在
@mastra/core	1.37.1	alphaとして1.38.0-alpha.2を確認
ai	6.0.191	beta、canary、ai-v5など複数dist-tagを確認

この結果は2026年5月28日時点のものです。Agent系SDKは更新が速いため、記事を読んだ時点では必ず公式ドキュメントとnpmで再確認してください。

結果

できたこと

公式情報と小さな構成で確認できた範囲です。

未検証

本番負荷、権限運用、費用は別途確認します。

次の判断

小さなPoCへ進むかを決めます。

動いたことは入口であり、本番運用の合格ではありません。

この4つの部品は、次のように役割を固定すると扱いやすいです。

判断軸	使うもの
手順、再試行、承認、長時間実行	Workflow
外部API、社内ツール、MCP接続	tool calling
実行前後の制約、権限、秘密情報、危険操作の停止	guardrails
UI、DB、後続処理へ渡す最終結果	structured output

フレームワーク選定では、UI中心ならVercel AI SDK、OpenAI API中心の軽いAgentならOpenAI Agents SDK、再開やhuman-in-the-loop重視ならLangGraph、TypeScriptでWorkflowとAgentをまとめて作るならMastra、という見方が現実的です。

ただし、これはベンチマーク結果ではありません。今回の記事では、同一タスクを各SDKで実装して速度、コスト、成功率を測ったわけではありません。あくまで公式一次情報と公開パッケージ情報に基づく、設計前の判断ガイドです。

失敗点・ハマりどころ

1つのloop

手順と権限が混ざります。

Tool過多

どの外部操作が必要か追いにくくなります。

検査不足

出力形式や禁止条件をモデル任せにします。

ログなし

失敗時に再現できません。

失敗原因を追える形にすることが、初期設計の目的です。

1. Agentに手順を任せすぎる

「まず差分を読み、次にテストを見て、最後にレビュー案を出す」という手順までLLMに任せると、実行のたびに順序が揺れます。順序が業務上重要ならWorkflowにします。

2. read-onlyとwriteを同じtoolにする

githubToolのような大きなtoolに、読み取りと書き込みをまとめると危険です。最初はread-only toolだけにし、write toolは人間承認後のstepでだけ使います。

3. guardrailsを最終出力だけに置く

外部APIの書き込みやファイル編集は、最終出力より前に実行されます。tool実行前に止めないと間に合いません。

4. structured outputを過信する

schemaに合ったJSONが返っても、業務上正しいとは限りません。severityがinfoでも、実際にはリリース停止級の問題かもしれません。重要な判定はアプリ側のルールと人間レビューで補います。

5. 再実行で副作用が重複する

Workflowを途中再開できるようにしても、投稿、支払い、デプロイ、メール送信のような副作用が二重実行されると事故になります。idempotency key、実行済みID、承認IDを保存します。

6. provider差を吸収できると思い込む

tool callingやstructured outputの対応は、providerやモデルで差があります。抽象SDKを使っていても、strict mode、schema制約、streaming event、エラー形式は完全には同じになりません。

実務で使うなら

1. read-only

   情報取得と要約だけにします。

2. 小さなWorkflow

   固定手順を1つ作ります。

3. 承認付きTool

   書き込み前に人間確認を入れます。

4. 構造化保存

   結果と根拠をDBやログに残します。

低リスクな入口から、確認できた範囲だけ広げます。

小規模チームで最初に作るなら、次の順序がおすすめです。

1. 対象タスクを1つに絞る。PRレビュー、Issue分類、リリースノート生成など、成功条件を人間が判定できるものにする。
2. read-only toolだけを作る。GitHub、Jira、Notion、DBなどへ接続する場合も、最初は取得だけにする。
3. structured outputのschemaを先に決める。UI、DB、レビュー観点をschemaから逆算する。
4. Workflowは3から5stepに抑える。長くなったらsub workflowに分ける。
5. write操作は人間承認後にする。承認者、承認対象、承認時刻、実行結果を保存する。
6. tool resultをログに残す前にマスクする。APIキー、個人情報、社内URL、秘密のファイルパスを出さない。
7. テストには「toolが失敗する」「schema違反が返る」「承認されない」「再実行される」を入れる。

この順序なら、AIの精度が期待より低くても、被害範囲を小さくできます。導入判断もしやすくなります。

セキュリティ・コスト注意

項目	内容	見方
secret		入力、ログ、tool引数に秘密情報を混ぜない設計にします。
permission		readとwrite、低リスクと高リスクを分けます。
cost		長いcontextや再実行の費用を見積もります。
audit		誰が何を承認したか追えるようにします。

Agent導入では、動作確認と同じくらい境界設計が重要です。

AI Agentアプリでは、LLMそのものよりtoolと権限がリスクになります。次のルールは最低限置きます。

• APIキーは環境変数やsecret managerで扱い、記事、ログ、プロンプト、tool resultに出さない。
• toolごとに権限を分け、read-onlyから始める。
• repo、project、tenant、userごとのallowlistをアプリ側で確認する。
• write操作は人間承認後だけにする。
• shell、file edit、DB update、外部送信は、timeout、allowlist、作業ディレクトリ制限を入れる。
• tool resultは最大文字数を制限し、必要なら要約してからLLMに戻す。
• LLM呼び出し回数、max steps、token上限、retry上限を設定する。
• モデルprovider、SDK、ホスティング先の利用規約、データ保持、学習利用、企業利用条件を導入前に確認する。

コスト面では、Workflow化すると1タスクあたりのLLM呼び出し回数が増えます。差分要約、レビュー案生成、出力検査、修正案生成を別々に呼ぶと、1回のユーザー操作で複数回課金されます。最初は、stepごとのtoken使用量、tool呼び出し回数、再試行回数をログに残してください。

Newsletterでは、AIコーディングエージェントやMCP、Agent SDKの更新で実務判断に影響がありそうなものだけを短く追っています。この記事のような導入判断メモを継続的に見たい場合は、記事読了後に登録するくらいの距離感がちょうどよいです。

導入しない方がよいケース

権限未定

どこまで実行できるか決まっていません。

ログ未整備

失敗時に原因を追えません。

承認なし

副作用のある操作を人間が確認できません。

責任不明

出力のレビュー担当が決まっていません。

止める条件を先に決めると、PoCが感覚論になりません。

次の条件なら、Agent化を急がないほうがよいです。

• 単純なCRUDや検索で、通常のUIとバリデーションのほうが速い
• 失敗時の責任者、承認者、復旧手順が決まっていない
• write権限を最初からAIに渡す必要がある
• ログを残せない、またはログに秘密情報が混じる状態を避けられない
• モデルproviderのデータ利用条件を確認できていない
• 期待する出力品質をテストで評価できない

AI Agentは、曖昧な入力を扱うには便利です。一方で、権限、監査、コスト、再実行性を曖昧にしたまま導入すると、普通の自動化より原因追跡が難しくなります。

利益相反とAI利用

提供

無償提供やスポンサー関係があれば書きます。

広告

アフィリエイトや広告関係を分けます。

AI利用

調査、構成、確認に使った範囲を残します。

開示は記事末尾で簡潔にまとめます。

この記事は、スポンサー提供、アフィリエイト、無償の検証環境提供を受けていません。記事の構成と下書きにはAIによる補助を使っていますが、公式一次情報の確認、コマンド実行結果、公開判断は人間が確認する前提の下書きとして保存しています。

FAQ

最初は何から

read-onlyの要約と構造化出力から始めます。

Framework選び

止めたい場所と状態保存で選びます。

Tool権限

最小権限と承認ログを前提にします。

迷ったら、再現性、権限、ログへ戻ります。

最初に学ぶならどれがよいですか

Next.jsアプリに組み込むならVercel AI SDK、OpenAI API中心で軽くAgentを作るならOpenAI Agents SDK、Workflowと再開性を深く学ぶならLangGraph、TypeScriptで業務WorkflowまでまとめたいならMastraから入るのが分かりやすいです。

LangGraphとMastraは競合しますか

一部は競合します。どちらもWorkflowやAgent orchestrationに関わります。ただし、LangGraphは低レベルなruntimeとして状態管理や再開性を細かく扱う方向、MastraはTypeScriptのアプリ開発体験としてAgent、Workflow、MCP、memoryをまとめる方向で見たほうが判断しやすいです。

guardrailsがあればwrite toolを自動実行してよいですか

いいえ。guardrailsは必要ですが、write操作には人間承認、権限分離、idempotency、監査ログが必要です。特に外部API、DB、ファイル、デプロイ、メール送信は、承認なしの自動実行から始めないほうが安全です。

structured outputだけでレビュー品質は上がりますか

上がるのは扱いやすさです。レビュー品質そのものは、入力情報、モデル、プロンプト、tool、評価データ、人間レビューに依存します。structured outputは、指摘を比較、保存、テストしやすくするための土台です。

---

次に読むなら

参照した主な情報源

公式Docs

SDKやフレームワークの仕様を確認します。

npm

公開バージョンと更新状況を確認します。

GitHub

README、examples、release情報を確認します。

導入前には、利用するバージョンの公式情報を再確認します。

• OpenAI Agents SDK for TypeScript
• OpenAI Agents SDK Tools
• OpenAI Agents SDK Guardrails
• OpenAI Structured Outputs
• LangGraph overview
• LangGraph interrupts
• LangGraph durable execution
• Mastra Workflows
• Mastra workflow snapshots
• Vercel AI SDK Tool Calling
• Vercel AI SDK Core Reference

次に読むなら

法人向けにAIコーディングエージェントやMCP、Agent Workflowを導入する場合は、ツール比較より先に、権限設計、ログ設計、人間承認フロー、禁止操作、テスト手順を整理したほうがうまく進みます。AI Dev Lab Japanでは、その前提を記事として少しずつ公開していきます。

更新履歴

1. 2026年5月28日

   公式ドキュメントとnpm情報を確認して初版を作成しました。

導入時には利用するSDKと公式情報を再確認します。

• 2026年5月28日：初版下書きを作成。公式ドキュメントとnpm package情報を確認。