ai-agents-for-beginners

コースのセットアップ

はじめに

このレッスンでは、このコースのコードサンプルを実行する方法を説明します。

他の学習者に参加してサポートを受ける

リポジトリをクローンする前に、セットアップのヘルプやコースに関する質問、他の学習者とのつながりのために、AI Agents For Beginners Discord チャンネルに参加してください。

このリポジトリをクローンまたはフォークする

始めるには、このGitHubリポジトリをクローンまたはフォークしてください。これにより、自分専用のコース教材のバージョンが作成され、コードの実行、テスト、調整が可能になります！

フォークするリンクをクリックして実行できます。

以下のリンクにあなたのフォークしたコースのバージョンが表示されるはずです：

Forked Repo

シャロークローン（ワークショップ/Codespacesに推奨）

フルリポジトリは履歴やすべてのファイルをダウンロードすると大きく（約3GB）なることがあります。ワークショップに参加するだけ、または一部のレッスンフォルダだけ必要な場合は、シャロークローン（またはスパースクローン）で履歴を切り詰めるかスキップし、ダウンロード量を減らせます。

クイックシャロークローン — 最小限の履歴、全ファイル

以下のコマンドの<your-username>部分をあなたのフォークURL（もしくはアップストリームURL）に置き換えてください。

最新のコミット履歴のみをクローンする（ダウンロード量を抑える）：

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

特定のブランチをクローンする場合：

git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

部分的（スパース）クローン — 最小限のblob + 選択フォルダのみ

これは部分クローンとスパースチェックアウトを使います（Git 2.25以上と部分クローン対応の最新Git推奨）：

git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

リポジトリフォルダに移動：

cd ai-agents-for-beginners

次に必要なフォルダを指定します（例は二つのフォルダ）：

git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

ファイルをクローンして確認後、ファイルだけが必要で容量を確保したい場合はリポジトリメタデータを削除してください（💀不可逆 — Gitのすべての機能、コミットやプル、プッシュ、履歴アクセスを失います）。

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

GitHub Codespaces を使う（ローカルの大容量ダウンロードを避けるのに推奨）

GitHub UIからこのリポジトリの新しいCodespaceを作成します。
作成したCodespaceのターミナルで、上記のシャロー/スパースクローンのいずれかを実行して、必要なレッスンフォルダのみをCodespaceの作業フォルダに取り込みます。
任意：Codespaces内でクローンした後、不要な容量確保のために.gitを削除してください（上記の削除コマンド参照）。
補足：Codespaceで直接リポジトリを開く場合（追加クローンなし）、Codespacesはdevcontainer環境を構築し、必要以上のプロビジョニングが行われることがあります。新鮮なCodespace内でシャローコピーをクローンすると、ディスク使用量をより細かく管理できます。

ヒント

編集やコミットする場合は、必ずクローンURLを自分のフォークURLに置き換えてください。
後でより多くの履歴やファイルが必要になったら、取得したりスパースチェックアウトでさらにフォルダを含めるよう調整可能です。

コードの実行

このコースでは、AIエージェント構築の実践体験ができる一連の Jupyter Notebook を提供しています。

サンプルコードはMicrosoft Agent Framework (MAF)を AzureAIProjectAgentProvider と共に使用し、Azure AI Agent Service V2（Responses API）に Microsoft Foundry 経由で接続します。

すべてのPythonノートブックは *-python-agent-framework.ipynb とラベル付けされています。

必要条件

Python 3.12+
- 注: Python3.12がインストールされていない場合は必ずインストールしてください。その後、requirements.txt の正しいバージョンをインストールできるように python3.12 で仮想環境を作成してください。
  
  例
  
  Python仮想環境ディレクトリを作成：
```
python -m venv venv
```
  続いて仮想環境を有効化：
```
# zsh/bash
source venv/bin/activate
```
```
# Command Prompt for Windows
venv\Scripts\activate
```
.NET 10+：.NETを使ったサンプルコード用に、.NET 10 SDK以降をインストールし、バージョンを確認してください。
```
  dotnet --list-sdks
```
Azure CLI — 認証に必須。aka.ms/installazurecliからインストールしてください。
Azure サブスクリプション — Microsoft Foundry と Azure AI Agent Service へのアクセス用。
Microsoft Foundry プロジェクト — デプロイ済みモデル（例：gpt-4o）のあるプロジェクトを作成します。詳細は以下のステップ1を参照。

このリポジトリのルートには、コード実行に必要なPythonパッケージをすべて記載した requirements.txt ファイルを含めています。

リポジトリルートのターミナルで以下のコマンドを実行してインストールできます：

pip install -r requirements.txt

パッケージの競合や問題を避けるため、Pythonの仮想環境作成を推奨します。

VSCodeのセットアップ

VSCodeで正しいPythonバージョンを使用していることを確認してください。

Microsoft Foundry と Azure AI Agent Service のセットアップ

ステップ1: Microsoft Foundryプロジェクトを作成

ノートブックを実行するには、モデルがデプロイされたAzure AI Foundryのハブとプロジェクトが必要です。

ai.azure.com にアクセスし、Azureアカウントでサインインします。
ハブを作成（または既存のものを使う）。詳細：https://learn.microsoft.com/azure/ai-foundry/concepts/ai-resources
ハブ内でプロジェクトを作成します。
モデル + エンドポイント → モデルのデプロイからモデル（例：gpt-4o）をデプロイします。

ステップ2: プロジェクトのエンドポイントとモデルデプロイ名を取得

Microsoft Foundryポータルのプロジェクトから：

プロジェクトエンドポイント — 概要ページにアクセスし、エンドポイントURLをコピーします。

Project Connection String

モデルデプロイ名 — モデル + エンドポイントに移動し、デプロイ済みモデルを選択、デプロイ名を確認します（例：gpt-4o）。

ステップ3: `az login` でAzureにサインイン

すべてのノートブックは認証に AzureCliCredential を使用します。APIキー不要でAzure CLI経由でサインインが必要です。

まだの場合、Azure CLIをインストールしてください：aka.ms/installazurecli
次のコマンドでサインイン：
```
 az login
```
または、ブラウザを使えないリモート/Codespace環境ではこちら：
```
 az login --use-device-code
```
Foundryプロジェクトが含まれるサブスクリプションを選択するよう促された場合は選択します。
サインインの確認：
```
 az account show
```

なぜ az login？ ノートブックは azure-identity パッケージの AzureCliCredential で認証します。これはAzure CLIのセッションが認証情報を提供するため、.envにAPIキーやシークレットを保存しません。セキュリティのベストプラクティスです。

ステップ4: `.env` ファイルを作成

サンプルファイルをコピー：

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

.env を開いて以下2つの値を入力します：

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

変数	探し場所
`AZURE_AI_PROJECT_ENDPOINT`	Foundryポータル → プロジェクト → 概要ページ
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	Foundryポータル → モデル + エンドポイント → デプロイ済みモデルの名前

ここまででほとんどのレッスンで完了です！ノートブックは az login セッションを通じて自動認証されます。

ステップ5: Python依存パッケージをインストール

pip install -r requirements.txt

仮想環境を有効にしてから実行するのを推奨します。

レッスン5（Agentic RAG）用の追加セットアップ

レッスン5は検索補強生成のためAzure AI Searchを使用します。実行する場合は、以下の変数を .env に追記してください：

変数	探し場所
`AZURE_SEARCH_SERVICE_ENDPOINT`	Azureポータル → Azure AI Searchリソース → 概要 → URL
`AZURE_SEARCH_API_KEY`	Azureポータル → Azure AI Searchリソース → 設定 → キー → 主管理キー

レッスン6とレッスン8（GitHub Models）用の追加セットアップ

一部ノートブックはAzure AI FoundryではなくGitHub Modelsを使います。実行予定の場合は .env に以下を追加してください：

変数	探し場所
`GITHUB_TOKEN`	GitHub → 設定 → 開発者向け設定 → 個人アクセストークン
`GITHUB_ENDPOINT`	`https://models.inference.ai.azure.com` （デフォルト値）
`GITHUB_MODEL_ID`	使用するモデル名（例：`gpt-4o-mini`）

代替プロバイダー：MiniMax（OpenAI互換）

MiniMaxは最大20万4千トークンの大規模コンテキストモデルを、OpenAI互換APIで提供します。Microsoft Agent Frameworkの OpenAIChatClient は任意のOpenAI互換エンドポイントに対応するため、MiniMaxをGitHub ModelsやOpenAIの代替として利用可能です。

以下の変数を .env に追加してください：

変数	探し場所
`MINIMAX_API_KEY`	MiniMaxプラットフォーム → APIキー
`MINIMAX_BASE_URL`	`https://api.minimax.io/v1` （デフォルト値）
`MINIMAX_MODEL_ID`	使用モデル名（例：`MiniMax-M2.7`）

利用可能モデル：MiniMax-M2.7（推奨）、MiniMax-M2.7-highspeed（高速応答）

OpenAIChatClient を使うコードサンプル（例：レッスン14のホテル予約ワークフロー）は、MINIMAX_API_KEY 設定時に自動的にMiniMax設定を検出して使用します。

レッスン8（Bing Grounding Workflow）用の追加セットアップ

レッスン8の条件付きワークフローノートブックは、Azure AI Foundry経由のBing groundingを使います。該当サンプルを実行する場合は .env に以下を追加してください：

変数	探し場所
`BING_CONNECTION_ID`	Azure AI Foundryポータル → プロジェクト → 管理 → 接続済みリソース → Bing接続 → 接続IDをコピー

トラブルシューティング

macOSでのSSL証明書検証エラー

macOSで次のようなエラーが出る場合：

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

これはmacOSのPythonでシステムSSL証明書が自動的に信頼されない既知問題です。以下の順に対処法を試してください：

方法1: PythonのInstall Certificatesスクリプトを実行（推奨）

# インストールしたPythonのバージョン（例: 3.12または3.13）で3.XXを置き換えてください。
/Applications/Python\ 3.XX/Install\ Certificates.command

方法2: ノートブックで connection_verify=False を使う（GitHub Modelsノートブックのみ）

レッスン6のノートブック 06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb では既にコメントアウトされた回避策が含まれています。クライアント作成時に connection_verify=False のコメントを外してください：

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # 証明書エラーが発生した場合はSSL検証を無効にしてください
)

⚠️ 警告: SSL検証を無効化すると証明書検証がスキップされ、安全性が低下します。開発環境での一時的回避策としてのみ使い、本番環境では絶対に使わないでください。

方法3: truststore をインストールして使用

pip install truststore

その後、ノートブックやスクリプトの冒頭に以下を追加してください：

import truststore
truststore.inject_into_ssl()

困ったときは？

セットアップで問題があればAzure AI Community Discordに参加、またはissueを作成してください。

次のレッスン

これでコースのコードを実行する準備が整いました。AIエージェントの世界をさらに学ぶことを楽しんでください！

AIエージェントの紹介とユースケース

免責事項:
本書類は AI 翻訳サービス Co-op Translator を使用して翻訳されています。正確性には努めていますが、自動翻訳には誤りや不正確な箇所が含まれる可能性があることをご了承ください。原文の母国語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じた誤解や誤訳について、当方は一切責任を負いません。

This site is open source. Improve this page.