AIエージェントの作り方完全ガイド。仕組み・設計パターン・実装まで解説

三好 大悟

「DifyやChatGPTは使いこなせている。でも仕組みを理解した上で、自分のコードでAIエージェントを動かせるようになりたい」

そう思っている方に向けて、本記事を書きました。

Pythonで生成AIを呼び出す処理は書けても、「自律的に判断して外部ツールを使い回すAIエージェント」を設計から実装まで一気通貫で理解しようとすると、どこかで壁にぶつかります。その壁の正体は多くの場合、「なぜこう設計するのか」という設計思想への理解不足です。コードを書く前に設計パターンを理解しておくと、実装の選択肢と根拠が明確になります。

本記事では、以下の内容を順に解説します。

  • AIエージェントと生成AIの違い（構造の比較）
  • ReAct・Tool-callingという設計パターンの「なぜ」
  • フレームワーク選定の判断基準（比較表あり）
  • OpenAI Agents SDKを使った最小実装（コード付き）
  • マルチエージェント・Agentic RAGへの拡張方法
  • 実装でよくある失敗と対処法

Pythonの基礎があり、OpenAI APIを一度でも触ったことのある方なら、この記事を読み終えたあとに最小構成のAIエージェントを動かせるようになります。

「AIエージェントの開発について、もう少し詳しく話を聞いてみたい」という方は、リベルクラフトへご相談ください。

⇨リベルクラフトへの無料相談はこちら

AIエージェントとは？生成AIとの決定的な違い

AIエージェントとは、与えられた目標を達成するために自律的に考え、外部ツールを呼び出し、結果を踏まえて次の行動を決定できるAIシステムです。

ChatGPTのような生成AIが「一問一答」で動くのに対し、AIエージェントは複数ステップのタスクを自分でループしながら処理します。「調べる→考える→実行する→確認する」というサイクルを自律的に回せる点が最大の違いです。

実際の用途でイメージするとわかりやすいです。「競合他社の最新情報をまとめてレポートにして」という指示を出した場合、生成AI単体では学習済み知識の範囲内でしか回答できません。しかしAIエージェントなら、Web検索ツールを呼び出して最新情報を取得し、内容を整理してレポート形式に組み上げるところまで自律で完走できます。

AIエージェントの活用事例についてはこちらも参考にしてください。 参照記事：AIエージェント活用事例10選｜業種・業務別の具体例と導入チェックリスト

生成AIとAIエージェントの3つの違い

生成AIとAIエージェントの違いを3軸で整理します。

比較軸生成AI（チャット型）AIエージェント
動作スタイル指示応答型（1問1答）目標駆動型（自律ループ）
状態管理ステートレス（基本的に）状態（メモリ）を持つ
ツール利用テキスト生成のみ外部API・コード実行・検索等を呼び出す

この3点の差が、「一問一答で使えるもの」と「複雑なタスクを自律で完走できるもの」の分かれ目です。

生成AIとAIエージェントの動作スタイルの違いを示すフロー比較図

AIエージェントの基本構造（モデル・ツール・メモリ・プランナー）

AIエージェントは、以下の4つのコンポーネントで構成されています。

  • モデル（LLM）：思考と判断を担うコア。「次に何をすべきか」を推論する頭脳
  • ツール（Tools）：Web検索・コード実行・データベース照会など外部機能を呼び出す手足
  • メモリ（Memory）：タスクの途中経過やツール実行結果を保持する短期記憶
  • プランナー（Planner）：ループを制御し、ゴール達成まで実行を続ける制御装置

4コンポーネントが連携することで、AIエージェントは複雑なタスクを分解・実行・修正しながら自律的に完結させることができます。コンポーネントへの理解は、フレームワーク選定や実装設計の判断基準にもなります。

AIエージェントの設計パターン

実装に入る前に「なぜこう設計するのか」を把握しておくことが重要です。設計パターンへの理解が浅いまま書いたコードは、動いているように見えても意図した通りに動かないことが多い。競合記事の多くが「どう使うか」で終わっているのに対して、ここでは「なぜこう設計するのか」まで掘り下げます。

ReAct（Reasoning + Acting）の仕組み

ReAct（Reasoning and Acting）とは、「考える→実行する→観察する」のループを繰り返すことでタスクを解決するAIエージェントの設計パターンです。2022年にYao et al.が発表した論文（ReAct: Synergizing Reasoning and Acting in Language Models）で提案されました。

ループは以下の3ステップで構成されています。

  1. Thought（思考）：LLMが「次に何をすべきか」を推論する
  2. Action（実行）：推論に基づいてツールを呼び出す
  3. Observation（観察）：ツールの実行結果を確認し、次の思考に活かす

このサイクルを繰り返すことで、1回の推論ではたどり着けない複雑な問題を段階的に解決できます。

なぜこの設計が優れているのか。論文では「推論ステップと行動ステップを交互に繰り返すことで、Chain-of-Thought単体より誤りを自己修正しやすくなる」と述べられています。つまり、途中でエラーが発生しても「エラーを観察→別の手段を考える→再実行」という自己修正が起動するのがポイントです。エージェントが「失敗を踏まえて考え直せる」構造になっているため、一度の推論ミスでタスク全体が止まりません。

この設計思想を理解しておくと、後述の実装コードで「なぜこう書くのか」が自然に理解できるようになります。

ReActパターンのThought・Action・Observationの3ステップループを示すフロー図

Tool-calling（Function calling）とは

Tool-callingとは、LLMが外部のツール（関数）をどのタイミングで・どの引数で呼び出すかを判断する仕組みです。OpenAIではFunction callingとも呼ばれます。

仕組みの概略は以下の通りです。

  1. 利用可能なツールの一覧とその仕様（JSON Schema形式）をLLMに渡す
  2. LLMは入力に応じて「このツールを、この引数で呼び出すべき」という判断を返す
  3. アプリケーション側が実際にツールを呼び出し、結果をLLMに戻す
  4. LLMは結果を踏まえて次の推論または最終回答を生成する

ReActループの中での位置づけとしては、「Action」ステップがTool-callingに相当します。LLMが実際にコードを実行するわけではなく、「どのツールを呼ぶか」を判断してアプリケーション側に委ねる構造です。この分離設計により、ツールをPythonで自由に実装できます。

フレームワーク選び方早見表

実装時に最初に悩む「どのフレームワークを使うか」の判断基準を整理します。

フレームワーク向いているケース難易度備考
OpenAI Agents SDKシンプルな単一エージェント・OpenAI API完結・素早くプロトタイプ低本記事の実装例で使用
LangGraph複雑な状態管理・チェックポイント・ストリーミング中〜高詳細はNo.70で解説予定
AutoGen複数エージェントの対話・会話型マルチエージェント中Microsoft製
CrewAIロールプレイ型のマルチエージェント協調タスク中高レベルな抽象化

判断の基本方針：まず動かすならOpenAI Agents SDK、状態管理が複雑になったらLangGraphへ移行する。

「LangGraphに移行すべき」具体的なタイミングの目安は、以下の3点です。

  • チェックポイントを使って処理を途中再開したい
  • ストリーミングでUIにリアルタイム表示したい
  • エージェント間の制御フローを細かくグラフ構造で設計したい

上記が必要になったと感じた時点でLangGraphに切り替えると判断コストが最小化されます。最初からLangGraphを選ぶ必要はありません。

AIエージェントを作る前の準備

環境構築（Python・OpenAI API・openai-agents）

Python 3.9以上を前提とします。OpenAI Agents SDKのインストールは1コマンドです。

pip install openai-agents

APIキーは.envファイルで管理します。ソースコードにベタ書きすると意図せずGitHubに公開してしまうリスクがあるため、シークレット管理は最初から徹底してください。

# .env ファイルの内容
OPENAI_API_KEY=sk-...
# Python側での読み込み
from dotenv import load_dotenv
load_dotenv()

エージェントに任せるタスクと目標を定義する

実装を始める前に「何をするエージェントか」を明確にしておくことが重要です。タスクが曖昧だとツールの設計も曖昧になり、エージェントがいつツールを使えばよいか判断できなくなります。

本記事では「ユーザーの質問を受け取り、Web検索して要約して返すエージェント」を実装例として使います。シンプルなタスクですが、Tool定義→Agent作成→run実行→ログ確認という一連の流れを体験するには十分な題材です。

OpenAI Agents SDKでAIエージェントを実装する最小構成

記事のメインセクションです。OpenAI Agents SDKを使って「Web検索して要約するエージェント」を作ります。コードは全体で30行程度に収めつつ、各ステップで「なぜこう書くのか」を補足します。

Step 1：ツール（Tool）を定義する

最初に、エージェントが使えるツールを定義します。OpenAI Agents SDKでは@function_toolデコレータを使うと、Pythonの関数をToolとして登録できます。

from agents import function_tool

@function_tool
def search_web(query: str) -> str:
    """
    指定したキーワードでインターネット検索を行い、上位の検索結果テキストを返す。
    事実確認・最新情報の取得・特定のトピックの概要把握に使用する。
    ユーザーの質問に答えるために最新の外部情報が必要な場合に呼び出す。
    """
    # 実際の実装ではTavily・Serper等のAPIを使用する
    # ここでは動作確認用のダミーレスポンスを返す
    return f"「{query}」の検索結果：OpenAI Agents SDKは2025年3月にリリースされた軽量なエージェントフレームワークです。"

ここで重要なのは、docstringの質です。

LLMはdocstringを読んで「このToolをいつ・なぜ使うか」を判断します。docstringが短すぎたり曖昧だったりすると、LLMは不必要なタイミングでツールを呼び出したり、逆にツールを呼び出すべき場面でスキップしてしまいます。

悪い例と良い例を対比すると、その差は明確です。

# 悪い例：曖昧すぎてLLMが判断できない
@function_tool
def search_web(query: str) -> str:
    """検索する"""
    ...

# 良い例：何を・いつ・なぜ使うかが明記されている
@function_tool
def search_web(query: str) -> str:
    """
    指定したキーワードでインターネット検索を行い、上位の検索結果テキストを返す。
    事実確認・最新情報の取得・特定のトピックの概要把握に使用する。
    ユーザーの質問に答えるために最新の外部情報が必要な場合に呼び出す。
    """
    ...

docstringはLLMへのプロンプトと同じ役割を果たします。「入力として何を渡すか」「どんな状況で使うべきか」「何が返ってくるか」の3点を明記することが、Toolが正しく機能する前提条件です。

Step 2：エージェントを作成してrunを実行する

次にAgentインスタンスを作成し、Runner.run()でエージェントを起動します。

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="WebSearchAgent",
    instructions="ユーザーの質問をWeb検索で調べて、簡潔に要約して答えてください。",
    tools=[search_web],
    model="gpt-4o-mini",
)

async def main():
    result = await Runner.run(
        agent,
        "OpenAI Agents SDKとはどんなフレームワークですか？",
        max_turns=5,
    )
    print(result.final_output)

asyncio.run(main())

各引数の役割を整理します。

引数役割
nameエージェントの識別名。ログや複数エージェント構成で参照される
instructionsエージェントの行動方針を定義するシステムプロンプト
toolsエージェントが使えるToolのリスト
model使用するLLMモデル名。コストを抑えたい場合はgpt-4o-miniが現実的
max_turnsReActループの最大実行回数。設定しないとAPIコストが無制限に増える

Runner.run()は非同期関数です。Jupyterノートブックの場合はawait Runner.run(...)だけで動きます。Pythonスクリプトの場合はasyncio.run(main())でラップしてください。同期実行が必要なシンプルなケースではRunner.run_sync()も使えます。

たったこれだけで、内部ではReActループが動いています。search_webが必要と判断されると、LLMがToolを呼び出し、結果を受け取って最終回答を生成するまでを自動で処理します。

OpenAI Agents SDKの実装フロー。@function_tool・Agent・Runner.runの3層構造を示す図

Step 3：実行ログでReActループの動作を確認する

コードが動いた段階で止まらず、「内部で何が起きているか」を確認できる状態にしておくことが重要です。実務では、ToolがいつどんなタイミングでPythonで呼ばれたかを追跡できないとデバッグが難しくなります。

result.new_messagesを使うと、ReActループの各ステップを確認できます。

async def main():
    result = await Runner.run(
        agent,
        "OpenAI Agents SDKとはどんなフレームワークですか？",
        max_turns=5,
    )
    
    # ReActループの各ステップを確認する
    for message in result.new_messages:
        print(f"[{message.role}] {message.content or '(tool_call)'}")
        if hasattr(message, 'tool_calls') and message.tool_calls:
            for tc in message.tool_calls:
                print(f"  → Tool呼び出し: {tc.function.name}({tc.function.arguments})")
    
    print("\n--- 最終回答 ---")
    print(result.final_output)

出力例のイメージ：

[assistant] (tool_call)
  → Tool呼び出し: search_web({"query": "OpenAI Agents SDK 概要 2025"})
[tool] 「OpenAI Agents SDK」の検索結果：...
[assistant] OpenAI Agents SDKは2025年3月にリリースされた...

--- 最終回答 ---
OpenAI Agents SDKは、Pythonで軽量なAIエージェントを構築するためのフレームワークです...

Thought（assistantの思考）→ Action（Tool呼び出し）→ Observation（tool roleの返答）の流れがメッセージとして現れます。この確認ができるようになると、「なぜToolが呼ばれないのか」「なぜ無限ループになるのか」といったデバッグが格段に楽になります。

また、OpenAIダッシュボードの「Trace viewer」でも実行ログを視覚的に確認できます。本番運用に入る前に一度確認しておくと、予期しない動作の原因を素早く特定できます。

より複雑な実装が必要になったら

最小実装を動かせたら、次のステップとして2方向の拡張があります。

「より実践的にAIエージェント開発を体系的に習得したい」という方には、Craft College Advancedをご検討ください。

⇨Craft College Advanced（詳細はこちら）

発展：マルチエージェントとAgentic RAGへの拡張

シングルエージェントが動いたら、次のステップとして2つの拡張パターンを把握しておくと実務に役立ちます。

マルチエージェント構成への拡張

マルチエージェントとは、役割の異なる複数のエージェントが協調してタスクをこなす構成を指します。複雑なタスクを単一エージェントに任せると推論の精度が落ちるため、「調査担当」「分析担当」「報告担当」のように役割を分けることが有効なケースがあります。

代表的なのはSupervisorパターンです。Supervisorエージェントがユーザーからタスクを受け取り、専門のWorkerエージェントに処理を委譲（handoff）する構造です。

[ユーザー]
    ↓
[Supervisorエージェント]
    ├→ Worker A（調査エージェント）
    ├→ Worker B（分析エージェント）
    └→ Worker C（レポート作成エージェント）

Agentic RAGとは（エージェントとRAGの組み合わせ）

Agentic RAGとは、RAG（検索拡張生成）をエージェントのToolとして組み込み、必要に応じて能動的に社内データを検索するパターンです。

従来のRAGが「常に社内ドキュメントを検索してから回答する」のに対し、Agentic RAGでは「この質問に社内情報が必要か」をエージェントが判断した上で検索を行います。不要な検索をスキップできるためレスポンスが速くなり、コストも下がります。

具体的には、前述のStep 1で定義したsearch_webツールと同様の方法で、社内ドキュメントの検索機能を1つのToolとして定義します。エージェントは質問内容に応じて「外部Web検索」と「社内ドキュメント検索」を使い分けながら回答する設計になります。

AIエージェント実装時のよくある失敗と対処法

実装して「動いたように見えるが期待通りではない」というケースには、いくつかの典型的なパターンがあります。企業AI導入の現場でも頻繁に遭遇する問題です。

ToolのdocstringがLLMへのプロンプトになることを意識する

最も多いハマりポイントのひとつが、Toolのdocstringの書き方です。

LLMはdocstringを読んで「このToolをいつ・なぜ使うか」を判断します。Step 1で示した悪い例のようにdocstringが「検索する」の1行だと、LLMは使うべき場面でツールを呼ばなかったり、逆に不必要なタイミングで呼び出したりします。

改善のポイントは3つです。

  • 何を入力するか：引数の意味と形式を明確にする（例：「検索キーワードを1〜3語で渡す」）
  • 何が返されるか：返り値の形式を明記する（例：「検索結果テキスト・最大500字」）
  • どんな状況で使うか：「最新情報が必要な場合」「外部情報を参照すべき場合」など条件を書く

docstringへの投資は、プロンプトエンジニアリングへの投資と同義です。ここを疎かにするとToolがまともに機能しません。

APIコストとループ回数の管理（max_turnsパラメータ）

ReActループが終了条件なしに回り続けると、APIのコストが際限なく増え続けます。OpenAI Agents SDKではRunner.run()のmax_turnsパラメータでループの上限を設定できます。

result = await Runner.run(
    agent,
    "質問テキスト",
    max_turns=10,  # 最大10ターンに制限
)

max_turnsを超えるとMaxTurnsExceeded例外が発生します。本番運用ではtry-exceptでこの例外をキャッチし、ユーザーへのエラーメッセージや再試行ロジックを組み込んでおくことが必要です。

タスクの複雑さに応じたmax_turnsの目安は「シンプルな検索タスク：5〜10」「複数ステップのタスク：15〜20」程度です。初期値は低めに設定して実際の使われ方を確認しながら調整することを推奨します。

ハルシネーションとToolの誤呼び出し対策

LLMが引数の形式を誤って渡してきたり、Tool実行中にAPIエラーが起きたりすると、エージェントが想定外の動作をすることがあります。

対策として有効なのは以下の3点です。

  • エラーハンドリング：try-exceptでTool実行のエラーをキャッチし、エラーメッセージをObservationとしてLLMに返す
  • ロギング：各ステップの入出力を記録し、エラー発生時に追跡できるようにする
  • テスト実行：想定外の入力（空文字・極端に長い文字列・日本語混じりのクエリ等）で挙動を事前確認する
@function_tool
def search_web(query: str) -> str:
    """
    指定したキーワードでインターネット検索を行い、上位の検索結果テキストを返す。
    事実確認・最新情報の取得・特定のトピックの概要把握に使用する。
    ユーザーの質問に答えるために最新の外部情報が必要な場合に呼び出す。
    """
    try:
        result = actual_search_api(query)
        return result
    except Exception as e:
        return f"検索中にエラーが発生しました: {str(e)}。別のクエリで再試行してください。"

エラーメッセージをObservationの一部としてLLMに渡すことで、エージェントが別の手段に切り替える判断ができるようになります。エラーを握りつぶすとLLMが状況を把握できず、無限ループや誤った回答につながります。

まとめ

本記事で解説した内容を整理します。

  • AIエージェントは「目標駆動型・状態管理あり・ツール連携」の3点で通常の生成AIと異なる
  • ReAct（Thought → Action → Observation のループ）が自律動作の核心にある設計パターン。自己修正できる構造だから複雑なタスクをこなせる
  • Tool-callingはLLMが「どのToolをどの引数で呼ぶか」を判断する仕組みで、ReActのActionステップに対応する
  • フレームワークは「まず動かすならOpenAI Agents SDK、複雑な状態管理が必要になったらLangGraph」という判断基準で選ぶ
  • 最小実装は「Tool定義 → Agent作成 → run実行 → ログ確認」の4ステップで動く
  • 実装の3大ハマりポイントは「docstringの質」「max_turns未設定」「エラーハンドリング不足」

まずは本記事のコードをそのままコピーして、最小構成（Tool 1個・シングルエージェント）を動かしてみてください。「動かして確認して修正する」サイクルが、AIエージェント開発の最短習得ルートです。

本格的な実装に進む際は以下の関連記事も参照してください。

AIエージェント実装をもっと体系的に学ぶなら

AIエージェントの基礎から、マルチエージェント・Agentic RAGまでを体系的に習得したい方には、Craft College データサイエンティスト養成講座（アドバンスト版）をご検討ください。

本記事で解説したReAct・Tool-calling・フレームワーク選定の知識を土台に、OpenAI Agents SDKでの実装からLangGraphを使ったマルチエージェント構成まで実装ベースで学べます。「12週間で実務レベルのAIエージェント開発スキルを習得する」ことを目標にカリキュラムを設計しています。

⇨Craft College Advanced（詳細はこちら）

AIエージェント開発に関するご相談はこちら

「記事を読んで実装してみたが、うまく動かない」「自社業務へのAIエージェント導入を検討している」という方は、リベルクラフトへご相談ください。

リベルクラフトでは、AIエージェントの設計・開発・運用支援を一貫してサポートしています。

リベルクラフト コーポレートサイト トップページ

⇨リベルクラフトへの無料相談はこちら

この記事を書いた人

慶應義塾大学で金融工学を専攻。 卒業後はスタートアップのデータサイエンティストとして、AI・データ活用コンサルティング事業などに従事。 その後、株式会社セブン&アイ・ホールディングスにて、小売・物流事業におけるAI・データ活用の推進に貢献。 株式会社リベルクラフトを設立し、AIやデータサイエンスなどデータ活用領域に関する受託開発・コンサルティングや法人向けトレーニング、教育事業を展開。

関連記事

DONWLOAD

資料ダウンロード

リベルクラフトの提供サービスや支援事例について、
資料でご覧いただけます。

資料一覧へ

CONTACT

無料相談

AI・データ活用のご状況をお伺いし、
プロジェクトを前に進めるための情報を提供します。

無料相談
無料相談