บทเรียนนี้จะครอบคลุมวิธีการรันตัวอย่างโค้ดของหลักสูตรนี้
ก่อนที่คุณจะเริ่มโคลนรีโปของคุณ ให้เข้าร่วมกับ ช่อง Discord AI Agents For Beginners เพื่อขอความช่วยเหลือเกี่ยวกับการตั้งค่า ถามคำถามเกี่ยวกับหลักสูตร หรือเชื่อมต่อกับผู้เรียนอื่นๆ
เพื่อเริ่มต้น กรุณาโคลนหรือฟอร์ก GitHub Repository นี้ ซึ่งจะทำให้คุณมีเวอร์ชันของวัสดุหลักสูตรเป็นของตัวเองเพื่อให้คุณสามารถรัน ทดสอบ และปรับแต่งโค้ดได้!
คุณสามารถทำได้โดยคลิกที่ลิงก์ เพื่อฟอร์กรีโป
ตอนนี้คุณควรมีเวอร์ชันฟอร์กของหลักสูตรนี้ในลิงก์ต่อไปนี้:

รีโปเต็มสามารถมีขนาดใหญ่ (~3 GB) เมื่อคุณดาวน์โหลดประวัติทั้งหมดและไฟล์ทั้งหมด หากคุณเข้าร่วมเฉพาะเวิร์กช็อปหรือต้องการเพียงโฟลเดอร์บทเรียนไม่กี่โฟลเดอร์ โคลนแบบตื้น (หรือโคลนแบบห่างๆ) จะดาวน์โหลดน้อยกว่ามาก
แทนที่ <your-username> ในคำสั่งด้านล่างด้วย URL ฟอร์กของคุณ (หรือ URL upstream หากคุณต้องการ)
เพื่อโคลนเฉพาะประวัติ commit ล่าสุด (ดาวน์โหลดขนาดเล็ก):
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
วิธีนี้ใช้ partial clone และ sparse-checkout (ต้องใช้ Git 2.25+ และแนะนำให้ใช้ Git รุ่นใหม่ที่รองรับ partial clone):
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) กรุณาลบ metadata ของรีโป (💀 ไม่สามารถย้อนกลับได้ — คุณจะสูญเสียฟังก์ชันการทำงาน Git ทั้งหมด):
# zsh/bash
rm -rf .git
# PowerShell
Remove-Item -Recurse -Force .git
สร้าง Codespace ใหม่สำหรับรีโปนี้ผ่าน GitHub UI
หลักสูตรนี้มีชุด Jupyter Notebooks ที่คุณสามารถรันเพื่อรับประสบการณ์จริงในการสร้าง AI Agents
ตัวอย่างโค้ดใช้ Microsoft Agent Framework (MAF) กับ FoundryChatClient ซึ่งเชื่อมต่อกับ Microsoft Foundry Agent Service V2 (Responses API) ผ่าน Microsoft Foundry
ไฟล์โน้ตบุ๊ก Python ทั้งหมดจะถูกตั้งชื่อว่า *-python-agent-framework.ipynb
หมายเหตุ: หากคุณยังไม่มี Python3.12 ให้ติดตั้งก่อน จากนั้นสร้าง venv โดยใช้ python3.12 เพื่อให้แน่ใจว่าติดตั้งเวอร์ชันที่ถูกต้องจากไฟล์ requirements.txt
ตัวอย่าง
สร้างไดเรกทอรี Python venv:
python -m venv venv
จากนั้นเปิดใช้งานสภาพแวดล้อม venv สำหรับ:
# zsh/bash
source venv/bin/activate
# Command Prompt for Windows
venv\Scripts\activate
.NET 10+: สำหรับโค้ดตัวอย่างที่ใช้ .NET ให้ติดตั้ง .NET 10 SDK หรือตัวใหม่กว่าก่อน จากนั้นตรวจสอบเวอร์ชัน .NET SDK ที่ติดตั้ง:
dotnet --list-sdks
gpt-5-mini) ดู ขั้นตอนที่ 1 ด้านล่างเราได้รวมไฟล์ requirements.txt ไว้ในโฟลเดอร์รากของรีโปนี้ ซึ่งบรรจุแพ็กเกจ Python ที่จำเป็นทั้งหมดสำหรับการรันตัวอย่างโค้ด
คุณสามารถติดตั้งโดยรันคำสั่งต่อไปนี้ในเทอร์มินัลที่โฟลเดอร์รากของรีโป:
pip install -r requirements.txt
เราแนะนำให้สร้างสภาพแวดล้อม Python เสมือนเพื่อหลีกเลี่ยงความขัดแย้งและปัญหาใดๆ
ตรวจสอบให้แน่ใจว่าคุณใช้เวอร์ชัน Python ที่ถูกต้องใน VSCode
คุณต้องมี hub และ project ใน Microsoft Foundry พร้อมโมเดลที่ติดตั้งเพื่อรันโน้ตบุ๊ก
gpt-5-mini) จาก Models + Endpoints → Deploy modelจากโปรเจกต์ของคุณในพอร์ทัล Microsoft Foundry:

gpt-5-mini)az loginโน้ตบุ๊กส่วนใหญ่จะพิสูจน์ตัวตนผ่าน การเข้าสู่ระบบ Azure CLI ของคุณ — โดยใช้ AzureCliCredential หรือ DefaultAzureCredential (ซึ่งดึงข้อมูลจากเซสชัน az login ของคุณ) จากแพ็กเกจ azure-identity — ดังนั้นไม่ต้องใช้คีย์ API บางบทเรียนและการรวมระบบเพิ่มเติมตามความสมัครใจจะใช้คีย์ API; โปรดตรวจสอบเงื่อนไขเบื้องต้นของบทเรียนแต่ละบทสำหรับตัวแปรสภาพแวดล้อมเพิ่มเติมซึ่งจำเป็นต้องเข้าสู่ระบบผ่าน Azure CLI
ติดตั้ง Azure CLI หากยังไม่ได้ติดตั้ง: aka.ms/installazurecli
เข้าสู่ระบบ โดยรัน:
az login
หรือถ้าคุณอยู่ในสภาพแวดล้อมระยะไกล/Codespace ที่ไม่มีเบราว์เซอร์:
az login --use-device-code
เลือกการสมัครใช้งานของคุณ หากมีการแจ้งเตือน — เลือกอันที่มีโปรเจกต์ Foundry ของคุณอยู่
ตรวจสอบ ว่าคุณได้เข้าสู่ระบบแล้ว:
az account show
ทำไมต้องใช้
az login? โน้ตบุ๊กพิสูจน์ตัวตนผ่านAzureCliCredential(หรือDefaultAzureCredentialซึ่งดึงจากเซสชัน Azure CLI ของคุณ) จากแพ็กเกจazure-identityซึ่งหมายความว่าเซสชัน Azure CLI ของคุณจะให้ข้อมูลรับรอง — ไม่มีคีย์ API หรือความลับในไฟล์.envของคุณ นี่เป็น แนวทางปฏิบัติด้านความปลอดภัยที่ดีที่สุด
.env ของคุณคัดลอกไฟล์ตัวอย่าง:
# zsh/bash
cp .env.example .env
# PowerShell
Copy-Item .env.example .env
เปิด .env และกรอกค่าเหล่านี้:
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 ของคุณ
pip install -r requirements.txt
เราแนะนำให้รันภายในสภาพแวดล้อมเสมือนที่คุณสร้างไว้ก่อนหน้านี้
โน้ตบุ๊กบทเรียนที่ 5 (Agentic RAG) และบทเรียนที่ 16 รันได้ทันทีด้วยฐานความรู้ในหน่วยความจำ — ไม่ต้องใช้ทรัพยากร Azure เพิ่มเติม หากคุณต้องการเชื่อมต่อกับดัชนีของ Azure AI Search จริง โปรดทราบว่า โน้ตบุ๊กบทเรียนที่ 16 ใช้การพิสูจน์ตัวตนแบบใช้คีย์: มันจะสลับจากการค้นหาในหน่วยความจำไปยัง Azure AI Search เฉพาะเมื่อ ทั้ง AZURE_SEARCH_SERVICE_ENDPOINT และ AZURE_SEARCH_API_KEY ถูกตั้งค่า และจะอยู่ที่การค้นหาในหน่วยความจำหากไม่ได้ตั้งค่า ดังนั้นถ้าจะรันกับดัชนีจริง คุณต้องตั้งค่าคีย์แอดมินด้วย การพิสูจน์ตัวตนแบบไร้คีย์ด้วย Microsoft Entra ID (RBAC) เป็นวิธีที่แนะนำสำหรับโค้ดการผลิตของคุณเอง สอดคล้องกับการไหลของ az login ที่ใช้ในส่วนอื่นๆ ของหลักสูตรนี้
ขั้นตอน RBAC ด้านล่างใช้กับตัวอย่างในคู่มือการตั้งค่าและโค้ดของคุณเอง ไม่ได้เปิดใช้การพิสูจน์ตัวตนแบบไร้คีย์ในโน้ตบุ๊กบทเรียนที่ 16; บทเรียนที่ 16 ยังคงต้องการทั้ง endpoint และคีย์แอดมินสำหรับใช้ Azure AI Search
เปิดใช้งานการเข้าถึงตามบทบาท (RBAC) บนบริการค้นหาของคุณ:
az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey
มอบหมายบทบาทที่จำเป็นให้กับตัวคุณเอง (สร้าง/โหลดดัชนี และคิวรี):
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)
เพิ่ม endpoint ลงในไฟล์ .env ของคุณ:
| ตัวแปร | ที่หาเจอ |
|---|---|
AZURE_SEARCH_SERVICE_ENDPOINT |
พอร์ทัล Azure → ทรัพยากร Azure AI Search ของคุณ → Overview → URL |
AZURE_SEARCH_API_KEY |
จำเป็น (พร้อมกับ endpoint) เพื่อเปิดใช้งาน Azure AI Search ในโน้ตบุ๊กบทเรียนที่ 16 ซึ่งใช้การพิสูจน์ตัวตนด้วยคีย์ พอร์ทัล Azure → Settings → Keys → คีย์แอดมินหลัก |
ทำไมต้องไร้คีย์? คีย์แอดมินให้สิทธิเขียนเต็มรูปแบบกับบริการค้นหาของคุณและอาจรั่วไหลผ่านไฟล์
.envด้วย RBAC ตัวตนaz loginของคุณจะถูกใช้แทน — ซึ่งเป็นรูปแบบการพิสูจน์ตัวตนแบบไร้คีย์ของ Entra ID ที่โน้ตบุ๊กของหลักสูตรใช้ (ผ่านAzureCliCredential/DefaultAzureCredential) ดูเพิ่มเติม เชื่อมต่อไปยัง Azure AI Search โดยใช้บทบาท
ดูคู่มือการตั้งค่า Azure AI Search setup guide สำหรับตัวอย่างเต็มของการสร้างดัชนีด้วย Python และ .NET
โน้ตบุ๊กบางตัวในบทเรียนที่ 6 และ 8 เรียกใช้ Azure OpenAI โดยตรง (โดยใช้ Responses API) แทนการผ่านโปรเจกต์ Microsoft Foundry ตัวอย่างเหล่านี้เคยใช้ GitHub Models ซึ่งเลิกใช้แล้วและไม่รองรับ Responses API โปรดเพิ่มตัวแปรเหล่านี้ในไฟล์ .env ของคุณ:
| ตัวแปร | ที่หาเจอ |
|---|---|
AZURE_OPENAI_ENDPOINT |
พอร์ทัล Azure → ทรัพยากร Azure OpenAI ของคุณ → Keys and Endpoint → Endpoint (เช่น https://<your-resource>.openai.azure.com) |
AZURE_OPENAI_DEPLOYMENT |
ชื่อของโมเดลที่ติดตั้งของคุณ (เช่น gpt-5-mini) ซึ่งรองรับ Responses API |
AZURE_OPENAI_API_KEY |
ตัวเลือก — เฉพาะถ้าคุณใช้การพิสูจน์ตัวตนด้วยคีย์แทน az login / Entra ID |
Responses API ใช้ endpoint เสถียร
/openai/v1/ดังนั้นไม่ต้องระบุapi-versionเข้าสู่ระบบด้วยaz loginเพื่อใช้การพิสูจน์ตัวตนแบบไร้คีย์ Entra ID
MiniMax ให้บริการโมเดลขนาดใหญ่บริบท (สูงสุด 204K tokens) ผ่าน API ที่เข้ากันได้กับ OpenAI เนื่องจาก Microsoft Agent Framework’s OpenAIChatClient ทำงานได้กับ endpoint ที่เข้ากันได้กับ OpenAI ใดๆ คุณสามารถใช้ MiniMax เป็นตัวเลือกแทนสำหรับบทเรียนที่ใช้ OpenAIChatClient
เพิ่มตัวแปรเหล่านี้ในไฟล์ .env ของคุณ:
| ตัวแปร | ที่หาเจอ |
|---|---|
MINIMAX_API_KEY |
MiniMax Platform → API Keys |
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 ของคุณโดยอัตโนมัติเมื่อมีการตั้งค่า MINIMAX_API_KEY
Novita AI ให้บริการ API ที่รองรับ OpenAI สำหรับโมเดลภาษาที่เป็นโอเพ่นซอร์สและก้าวหน้า (DeepSeek, Llama, Qwen และอื่น ๆ) เนื่องจาก OpenAIChatClient ของ Microsoft Agent Framework ทำงานร่วมกับจุดสิ้นสุดที่รองรับ 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 และอื่น ๆ) — ตรวจสอบ คลังโมเดล Novita AI เพื่อดูรายชื่อโมเดลและรหัสโมเดลที่มีอยู่ในขณะนี้
ตัวอย่างปัจจุบันไม่ใช้ตัวแปร NOVITA_* โดยอัตโนมัติ หากต้องการใช้ Novita AI ให้ส่งค่าตัวแปรเหล่านี้เมื่อสร้าง OpenAIChatClient ในตัวอย่างที่คุณกำลังรันอย่างชัดเจน
Foundry Local คือการรันไทม์น้ำหนักเบาที่ดาวน์โหลด จัดการ และให้บริการโมเดลภาษา ทั้งหมดบนเครื่องของคุณเอง ผ่าน API ที่รองรับ OpenAI — ไม่ต้องใช้คลาวด์
เนื่องจาก OpenAIChatClient ของ Microsoft Agent Framework ทำงานร่วมกับจุดสิ้นสุดที่รองรับ OpenAI ใด ๆ ได้ Foundry Local จึงเป็นทางเลือกในเครื่องที่แทนที่ Azure OpenAI ได้โดยตรง
1. ติดตั้ง Foundry Local
# วินโดวส์
winget install Microsoft.FoundryLocal
# แมคโอเอส
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
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 ให้บริการจุดสิ้นสุด Chat Completions ที่รองรับ OpenAI ใช้สำหรับการพัฒนาในเครื่องและกรณีออฟไลน์ สำหรับคุณสมบัติเต็มรูปแบบของ Responses API (บทสนทนาที่มีสถานะ ฯลฯ) ให้ใช้ Azure OpenAI หรือโครงการ Microsoft Foundry
โน้ตบุ๊กกระบวนการทำงานแบบมีเงื่อนไขในบทเรียนที่ 8 ใช้ การอิง Bing ผ่าน Microsoft Foundry หากคุณวางแผนจะรันตัวอย่างนี้ ให้เพิ่มตัวแปรนี้ลงในไฟล์ .env ของคุณ:
| ตัวแปร | ที่หามันได้ที่ไหน |
|---|---|
BING_CONNECTION_ID |
พอร์ทัล Microsoft Foundry → โครงการของคุณ → การจัดการ → ทรัพยากรที่เชื่อมต่อ → การเชื่อมต่อ Bing ของคุณ → คัดลอก ID การเชื่อมต่อ |
หากคุณใช้ macOS และพบข้อผิดพลาดเช่น:
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain
นี่เป็นปัญหาที่ทราบใน Python บน macOS ที่ใบรับรอง SSL ของระบบไม่ได้รับความไว้วางใจโดยอัตโนมัติ ลองแก้ไขตามลำดับดังนี้:
ตัวเลือก 1: รันสคริปต์ Install Certificates ของ Python (แนะนำ)
# แทนที่ 3.XX ด้วยเวอร์ชัน Python ที่คุณติดตั้ง (เช่น 3.12 หรือ 3.13):
/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()
หากคุณมีปัญหาใด ๆ ในการรันการตั้งค่านี้ เข้าร่วมใน Discord ชุมชน Azure AI ของเราหรือ สร้างข้อผิดพลาด
ตอนนี้คุณพร้อมที่จะรันโค้ดบทเรียนนี้แล้ว เรียนรู้อย่างสนุกกับโลกของ AI Agents!
บทนำสู่ AI Agents และกรณีการใช้งาน Agent
ปฏิเสธความรับผิดชอบ: เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI Co-op Translator ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้