ai-agents-for-beginners

コースセットアップ

はじめに

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

他の学習者に参加して助けを得る

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

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

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

これはリポジトリをフォークするリンクをクリックして行えます。

次のリンクにあなたのフォークしたコースのバージョンができているはずです：

フォークしたリポジトリ

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

履歴とすべてのファイルを完全にダウンロードすると、リポジトリ全体は大きくなる場合があります（約3 GB）。ワークショップへの参加のみや、一部のレッスンフォルダだけが必要な場合は、浅いクローン（またはスパースクローン）でかなり小さくダウンロードできます。

クイック浅いクローン — 最小限の履歴、すべてのファイル

下記のコマンドで<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

次に、必要なフォルダを指定します（以下の例は2つのフォルダを表示）：

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

クローンしてファイル確認後、ファイルのみが必要で容量を開放したい場合（git履歴は不要）は、リポジトリのメタデータを削除してください（💀元に戻せません — Git機能はすべて失われます）：

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

GitHub Codespacesの利用（ローカルの大きなダウンロードを避けるため推奨）

ヒント

コードの実行

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

コードサンプルでは、FoundryChatClientを使用したMicrosoft Agent Framework (MAF)を用い、Microsoft Foundryを通じてMicrosoft Foundry Agent Service V2（Responses API）に接続します。

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

要件

このリポジトリのルートにはコードサンプルを実行するのに必要なPythonパッケージをすべて記載したrequirements.txtファイルがあります。

リポジトリのルートで次のコマンドを実行してインストールできます：

pip install -r requirements.txt

コンフリクトや問題を避けるため、Pythonの仮想環境を作成することを推奨します。

VSCodeのセットアップ

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

image

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

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

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

  1. ai.azure.com にアクセスし、Azureアカウントでサインインします。
  2. ハブを作成するか（既存のものを使用）、ハブリソースの概要をご参照ください。
  3. ハブ内でプロジェクトを作成します。
  4. Models + Endpoints → モデルをデプロイからモデル（例：gpt-5-mini）をデプロイします。

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

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

プロジェクト接続文字列

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

ほとんどのノートブックは azure-identity パッケージの AzureCliCredential または DefaultAzureCredential で Azure CLI のサインイン状態（az login）を使用して認証します。これによりAPIキーは不要です。一部のレッスンやオプション統合はAPIキーを使用しますので、各レッスンの前提条件で追加の環境変数を確認してください。Azure CLIへのサインインが必要です。

  1. Azure CLIが未インストールの場合はインストール：aka.ms/installazurecli

  2. 次を実行しサインイン：

     az login

    ブラウザがないリモート/Codespace環境の場合：

     az login --use-device-code

  3. プロンプトが表示されたらサブスクリプションを選択 — Foundryプロジェクトが含まれるものを選んでください。

  4. サインイン済みを確認：

     az account show

なぜaz login？ ノートブックは azure-identity の AzureCliCredential（またはDefaultAzureCredential）を使って認証します。これにより.env ファイルにAPIキーやシークレットが不要になり、Azure CLIセッションが資格情報を提供します。これはセキュリティのベストプラクティスです。

ステップ 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-5-mini
変数 場所
AZURE_AI_PROJECT_ENDPOINT Foundryポータル → プロジェクト → Overview ページ
AZURE_AI_MODEL_DEPLOYMENT_NAME Foundryポータル → Models + Endpoints → デプロイ済みモデル名

これでほとんどのレッスンは準備完了です！ノートブックは自動的に az login セッションで認証します。

ステップ 5: Python依存関係のインストール

pip install -r requirements.txt

先ほど作成した仮想環境内で実行することを推奨します。

オプションセットアップ：Azure AI Search（レッスン5と16）

レッスン5（Agentic RAG）とレッスン16のノートブックは、インメモリのナレッジベースでそのまま実行可能で、追加のAzureリソースは不要です。実際のAzure AI Searchインデックスでバックアップしたい場合、レッスン16ノートブックは現在キー認証を使用しており、AZURE_SEARCH_SERVICE_ENDPOINTとAZURE_SEARCH_API_KEYの両方が設定された時だけインメモリ検索からAzure AI Searchに切り替わります。そのため実際のインデックスで実行するには管理キーも設定する必要があります。本コースの他の部分で使用されているaz loginフローに準拠した推奨のキーなし認証のMicrosoft Entra ID (RBAC)は、本番コードでは推奨されます。

以下のRBAC手順はセットアップガイドサンプルと自身のコードに適用されますが、レッスン16ノートブックでキーなし認証を有効にするものではありません。レッスン16は引き続きエンドポイントと管理キーの両方を必要とします。

  1. 検索サービスでロールベースアクセスを有効にします：

     az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey

  2. 必要なロールを自分に割り当てる（インデックスの作成/ロードおよびクエリ）：

     az role assignment create --assignee <your-user-or-principal-id> --role "Search Service Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
 az role assignment create --assignee <your-user-or-principal-id> --role "Search Index Data Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)

  3. .env ファイルにエンドポイントを追加します：

変数 場所
AZURE_SEARCH_SERVICE_ENDPOINT Azureポータル → Azure AI Search リソース → Overview → URL
AZURE_SEARCH_API_KEY レッスン16ノートブックでAzure AI Searchをキー認証で使用するために必要。Azureポータル → 設定 → キー → プライマリ管理キー

なぜキーなし？ 管理キーは検索サービスに対する完全な書き込みアクセスを許可し、.envファイルを通じて漏洩する恐れがあります。RBACでは代わりに az login のIDが使われます。これが本コースノートブックのキーなしEntra IDパターン（AzureCliCredential / DefaultAzureCredentialを介す）と一致します。ロールを使ったAzure AI Searchへの接続を参照してください。

Azure AI SearchセットアップガイドにPythonや.NETでの完全なインデックス作成サンプルが掲載されています。

Azure OpenAIを直接呼び出すレッスン向け追加セットアップ（レッスン6と8）

レッスン6と8の一部ノートブックは、Microsoft Foundryプロジェクトを経由せずAzure OpenAIを直接（Responses APIを使って）呼び出します。これらのサンプルは旧GitHub Modelsを使用していましたが廃止され、Responses APIをサポートしていません。.envに次の変数を追加してください：

変数 場所
AZURE_OPENAI_ENDPOINT Azureポータル → Azure OpenAI リソース → キーとエンドポイント → エンドポイント (例：https://<your-resource>.openai.azure.com)
AZURE_OPENAI_DEPLOYMENT Responses APIをサポートするデプロイ済みモデル名（例：gpt-5-mini）
AZURE_OPENAI_API_KEY 任意 — az login / Entra ID以外のキー認証を使う場合のみ必要

Responses APIは安定版の/openai/v1/エンドポイントを使用するため、api-versionは不要です。キーなしのEntra ID認証にはaz loginでサインインしてください。

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

MiniMaxは、最大204Kトークンの長大コンテキスト対応モデルをOpenAI互換APIで提供します。Microsoft Agent FrameworkのOpenAIChatClientは任意のOpenAI互換エンドポイントで動作するため、OpenAIChatClientを使うレッスンはMiniMaxを代替としてそのまま利用可能です。

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

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

モデル例：MiniMax-M3（推奨）、MiniMax-M2.7、MiniMax-M2.7-highspeed（高速応答）。モデル名と提供状況は時々変わることがあります。また、モデルへのアクセスはアカウントに依存します。

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

代替プロバイダー: Novita AI（OpenAI互換）

Novita AI は、オープンソースおよび最先端のLLM（DeepSeek、Llama、Qwenなど）向けのOpenAI互換APIを提供しています。Microsoft Agent Frameworkの OpenAIChatClient はあらゆるOpenAI互換のエンドポイントで動作するため、Novita AIをAzure OpenAIやOpenAIの代替としてそのまま利用できます。

これらの変数を .env ファイルに追加してください：

変数 入手場所
NOVITA_API_KEY Novita AI ダッシュボード → API Keys
NOVITA_BASE_URL https://api.novita.ai/openai/v1 を使う（デフォルト値）
NOVITA_MODEL_ID 使用するモデル名（例：moonshotai/kimi-k3）

例モデル: moonshotai/kimi-k3, zai-org/glm-5.2, deepseek/deepseek-v4-flash-0731。Novita AIは他にも多くのオープンソースモデルファミリー（Llama、Qwen、GLMなど）をホストしています — 利用可能なモデルとモデルIDの一覧はNovita AIモデルライブラリで確認できます。

現状のサンプルは NOVITA_* 変数を自動で使用しません。Novita AIを使うには、実行中のサンプルの OpenAIChatClient 構築時にこれらの値を明示的に渡してください。

代替プロバイダー: Foundry Local（モデルをローカル実行）

Foundry Local は軽量なランタイムで、言語モデルを完全に自分のマシン上でダウンロード、管理、提供し、OpenAI互換API経由で利用できます — クラウド不要です。

Microsoft Agent Frameworkの OpenAIChatClient はどのOpenAI互換エンドポイントとも動くため、Foundry LocalはAzure OpenAIのローカル代替としてそのまま使えます。

1. Foundry Local をインストール

# ウィンドウズ
winget install Microsoft.FoundryLocal

# macOS
brew install foundrylocal

2. モデルをダウンロード・実行（これでローカルサービスも起動します）：

foundry model list          # 利用可能なモデルを見る
foundry model run phi-4-mini

3. ローカルエンドポイントを発見するためのPython SDKをインストール：

pip install foundry-local-sdk

4. Microsoft Agent Frameworkをローカルのモデルに向ける：

from foundry_local import FoundryLocalManager
from agent_framework.openai import OpenAIChatClient

# 必要に応じてモデルをダウンロードし、ローカルで提供してから、エンドポイント/ポートを検出します。
manager = FoundryLocalManager("phi-4-mini")

chat_client = OpenAIChatClient(
    base_url=manager.endpoint,      # 例： http://localhost:<port>/v1
    api_key=manager.api_key,        # Foundry Localでは常に「not-required」です。
    model_id=manager.get_model_info("phi-4-mini").id,
)

agent = chat_client.as_agent(
    name="LocalAgent",
    instructions="You are a helpful assistant running fully on-device.",
)

補足: Foundry LocalはOpenAI互換のChat Completionsエンドポイントを公開しています。ローカル開発やオフライン用途に使えます。完全なResponses API機能セット（状態管理会話など）はAzure OpenAIやMicrosoft Foundryプロジェクトをご利用ください。

レッスン8の追加セットアップ（Bing Groundingワークフロー）

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

変数 入手場所
BING_CONNECTION_ID Microsoft 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検証を無効化する（connection_verify=False）と証明書検証をスキップするためセキュリティが低下します。これは開発環境での一時的回避策としてのみ使い、本番環境では絶対に使用しないでください。

オプション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.