AI エージェント フレームワーク + MCP 統合ナニー レベルのチュートリアル: 外部ツールを呼び出すことができるエージェントを最初から構築する

🛒 開発者向けに、環境準備からMCPサーバーの書き込み、LangGraphの共同デバッグまでをワンストップで行う入門チュートリアル。

チュートリアルの目的

このチュートリアルでは、外部ツールを呼び出すことができる AI エージェントを最初から構築します。まず Python を使用して MCP 標準に準拠するツール サービス (MCP サーバー) を作成し、次に LangGraph を使用してそれを会話型エージェントに接続します。学習後は、サンプルを実行できるだけでなく、独自のシステムの API をツールにカプセル化し、エージェントに接続できるようになります。

準備チェックリスト

• [ ] インターネット対応の開発マシン (macOS/Linux/Windows も可)、Python 3.10 以降。
• [ ] uv をインストールします (推奨、Python 環境と依存関係の管理に使用されます): curl -LsSf https://astral.sh/uv/install.sh | sh、次に source ~/.zshrc。
• [ ] 利用可能な LLM API キー (OpenAI / Anthropic / 国内の大型モデルが許容されます。このチュートリアルでは例として OpenAI 互換インターフェイスを使用します)。
• [ ] 「実際のツール」の例を準備する: このチュートリアルではツールとして「ローカル ファイルの読み取り」を使用しますが、これを天気 API やデータベース クエリに変更することもできます。
• [ ] (オプション) MCP Inspector ビジュアル デバッグ ツールをインストールします。

バージョンのヒント: MCP SDK と LangGraph は迅速に反復されます。次のコマンドのバージョン番号は、公式リアルタイム ページに準拠しています。インストールが失敗した場合は、エラー レポートのプロンプトを優先してください。

ステップ 1: プロジェクトと仮想環境を作成する

「」バッシュ mkdir mcp-agent-demo && cd mcp-agent-demo uv init --python 3.11 uv add "mcp[cli]" langgraph langchain-openai python-dotenv 「」

注: uv init は pyproject.toml と main.py を生成します。 mcp[cli] は、MCP ランタイムおよびデバッグ コマンドを提供します。

ステップ 2: 最初の MCP サーバーを作成する

「ローカル ファイルの内容を読み取る」ためのツールを実装するための server.py を作成します。

「」パイソン mcp.server.fastmcp から FastMCP をインポート

mcp = FastMCP("ファイルリーダー")

@mcp.tool() def read_file(パス: str) -> str: """指定されたパスにあるテキスト ファイルの内容を読み取ります。エージェントが外部ツールを呼び出すことを示すために使用されます。""" 試してみてください: open(path, "r", encoding="utf-8") を f として使用: f.read(2000) を返す e としての例外を除く: return f"読み取りに失敗しました: {e}"

name == "main"の場合: mcp.run() 「」

キーポイント: @mcp.tool() デコレーターは通常の関数をツールとして登録し、関数パラメーターとドキュメント文字列によって、モデルが参照できるツール スキーマが自動的に生成されます。 説明は、いつ呼び出すべきかをモデルが認識できるように明確に記述する必要があります。

ステップ 3: MCP Inspector を使用してサーバーを検証する

「」バッシュ uv run mcp dev サーバー.py 「」

ブラウザとインスペクタで「http://localhost:6274」を開きます。

1. 「read_file」ツールを選択します。
2. パラメータ {"path": "README.md"} を入力します (最初にプロジェクト内に README.md を作成します)。
3. [通話] をクリックすると、右側にファイルの内容が表示されます。

このステップでは、「ツール自体が利用可能である」ことを確認し、最初にモデル レベルで問題を切り分けることができます。

ステップ 4: LangGraph を使用してエージェントを構築し、MCP ツールに接続する

「agent.py」を作成します。

「」パイソン 非同期をインポートする langchain_openai から ChatOpenAI をインポート langgraph.prebuilt import create_react_agent から langchain_mcp_adapters.client から MultiServerMCPClient をインポート

非同期def main(): MultiServerMCPClient( との非同期 {"ファイルリーダー": {"コマンド": "uv", "args": ["run", "server.py"], "transport": "stdio"}} ) クライアントとして: tools = client.get_tools() モデル = ChatOpenAI(モデル = "gpt-4o-mini", 温度 = 0) エージェント = create_react_agent(モデル、ツール) result = await Agent.ainvoke({"messages": [("user", "プロジェクト内の README.md を読み、最初の 3 行を要約してください")]}) print(結果["メッセージ"][-1].content)

name == "main"の場合: asyncio.run(main()) 「」

実行:

「」バッシュ import OPENAI_API_KEY="あなたのキー" uvはPythonのagent.pyを実行します 「」

予想される出力: モデルは最初に「read_file」ツールを呼び出してファイルを読み取り、次に返されたコンテンツに基づいて概要を提供します。これは完全な「エージェント → MCP → 実際のツール」リンクです。

ステップ 5: 実際のビジネス ツールに接続する (例: SQLite のクエリ)

「クエリ データベース」ツールを使用して「server.py」を拡張します。

「」パイソン sqlite3をインポートする

@mcp.tool() def query_sqlite(db_path: str, SQL: str) -> str: """SQLite データベースに対して読み取り専用の SELECT クエリを実行し、結果を返します。""" sql.strip(). lower().startswith("select") でない場合: return "SELECT クエリのみが許可されます" conn = sqlite3.connect(db_path) 試してみてください: 行 = conn.execute(sql).fetchmany(10) return "\n".join(str(r) for r in rows) e としての例外を除く: return f"クエリが失敗しました: {e}" 最後に: conn.close() 「」

企業に実装する場合、この読み取り専用クエリを「権限検証を伴う内部 API カプセル化」に置き換えることが、運用レベルのツールの最小形式となります。

ステップ 6: 構成、ログ、および一般的なエラー

• ログ: 各ステップでのツール呼び出しを観察するには、「ChatOpenAI」と「agent.py」のエージェントに「verbose=True」を追加します。
• タイムアウト: エージェントのスタックを避けるために、MCP ツール呼び出しのタイムアウトをクライアントで設定できます。
• 一般的なエラーの報告と処理:

検証方法

1. ツール層の検証: MCP Inspector は各ツールを個別にテストします。
2. リンクの検証: エージェントに 3 つの異なるタスクを完了させ、ツールが毎回正しく選択されていることを確認します。
3. 回帰検証: ユースケースをスクリプトに統合し、変更後に再実行します。

よくある質問 (FAQ)

1. MCP は Python を使用する必要がありますか?

   いいえ。公式 SDK は Python と TypeScript をサポートしており、Node 環境は @modelcontextprotocol/sdk を使用します。

2. ローカル GPU がない場合でも、このチュートリアルを使用できますか?

   できる。このチュートリアルの LLM は API を使用し、大規模なモデル推論のみにコンピューティング能力が必要で、軽量のツール サービスのみがローカルで実行されます。

3. エージェントがツールを呼び出さない場合はどうすればよいですか?

まず、ツールの説明に「いつ呼び出すか」というトリガー条件が含まれているかどうかを確認し、次にモデルに関数呼び出し機能があることを確認し、最後により単純なプロンプトを使用してテストします。

4. MCP サーバーを運用環境に導入するにはどうすればよいですか?

   サーバーは、標準入出力の代わりにストリーミング可能な HTTP トランスポートを使用し、統合認証にアクセスして、独立したプロセス/コンテナとしてデプロイできます。

5. 複数のツールが相互に干渉することはありますか?

   各ツールには独立した名前空間とスキーマがあります。説明が明確で権限が最小限に抑えられている限り、通常は干渉は発生しません。同時実行性の高いシナリオではフローを制限することをお勧めします。

進歩と拡大

• マルチエージェント オーケストレーション: LangGraph のステート マシンを使用して、「計画、実行、レビュー」を複数の役割に分割します。
• MCP レジストリ: 内部ツール登録センターを構築して、バージョンと権限を統一します。
• 評価セット: ビジネス ユース ケースを自動回帰に導き、動作のドリフトを防ぎます。
• 民営化: LLM をローカル展開モデル (Ollama など) に置き換えて、フルリンク イントラネット運用を実現します。