mirrors / microsoft--ai-agents-for-beginners

项目文件夹

microsoft--ai-agents-for-beginners
文件
main
T
wehub-resource-sync c79da9cdf9 chore: import upstream snapshot with attribution
2026-07-13 12:59:43 +08:00

314 行
11 KiB
Plaintext
原始文件 永久链接 Blame 文件历史

{
"cells": [
{
"cell_type": "markdown",
"id": "8744544f",
"metadata": {},
"source": [
"# Lesson 04 - Tool Use Design Pattern\n",
"\n",
"Sa leksiyon na ito matututuhan mo ang **Tool Use** design pattern para sa AI agents gamit ang Microsoft Agent Framework (Python). Tatalakayin natin:\n",
"\n",
"- Pagtukoy ng function tools gamit ang `@tool` decorator at typed parameters\n",
"- Pagbibigay ng tool schemas para malaman ng model kung ano ang ginagawa ng bawat tool\n",
"- Pagkontrol ng tool execution gamit ang `approval_mode`\n",
"- Pagbabalik ng **structured output** sa pamamagitan ng mga Pydantic models at `response_format`\n",
"\n",
"Ang senaryo ay isang **travel booking agent** na maaaring maghanap ng mga destinasyon, suriin ang availability, at kunin ang impormasyon ng mga flight.\n"
]
},
{
"cell_type": "markdown",
"id": "b1a2c3d4",
"metadata": {},
"source": [
"## Setup\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "59c0feeb",
"metadata": {},
"outputs": [],
"source": [
"%pip install agent-framework azure-ai-projects azure-identity python-dotenv -U -q"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c0df8a52",
"metadata": {},
"outputs": [],
"source": [
"import logging\n",
"logging.getLogger(\"agent_framework.foundry\").setLevel(logging.ERROR)\n",
"\n",
"import os\n",
"import asyncio\n",
"import dotenv\n",
"from typing import Annotated\n",
"\n",
"from pydantic import BaseModel\n",
"from agent_framework import tool\n",
"from agent_framework.foundry import FoundryChatClient\n",
"from azure.identity import DefaultAzureCredential\n",
"\n",
"dotenv.load_dotenv(dotenv.find_dotenv())\n",
"\n",
"endpoint = os.getenv(\"AZURE_AI_PROJECT_ENDPOINT\")\n",
"deployment_name = os.getenv(\"AZURE_AI_MODEL_DEPLOYMENT_NAME\")\n",
"\n",
"missing = [k for k, v in {\n",
" \"AZURE_AI_PROJECT_ENDPOINT\": endpoint,\n",
" \"AZURE_AI_MODEL_DEPLOYMENT_NAME\": deployment_name\n",
"}.items() if not v]\n",
"\n",
"if missing:\n",
" raise ValueError(\n",
" f\"Missing required environment variables: {', '.join(missing)}. \"\n",
" \"Please set them as environment variables (e.g., in your .env file or shell environment).\"\n",
" )"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a6141584",
"metadata": {},
"outputs": [],
"source": [
"# Create the Azure AI Foundry client\n",
"client = FoundryChatClient(\n",
" project_endpoint=endpoint,\n",
" model=deployment_name,\n",
" credential=DefaultAzureCredential()\n",
")"
]
},
{
"cell_type": "markdown",
"id": "d5e6f7a8",
"metadata": {},
"source": [
"## Pagde-define ng Mga Tool gamit ang @tool Decorator\n",
"\n",
"Ang `@tool` decorator ay nagtatakda ng isang simpleng Python function bilang isang tool na maaaring tawagin ng isang ahente.\n",
"Pangunahing punto:\n",
"\n",
"- Ang **docstring** ang nagiging deskripsyon ng tool na nakikita ng modelo.\n",
"- Ang **Type annotations** (kasama ang `Annotated` na may mga deskripsyon) ay nagtatakda ng schema ng tool.\n",
"- Ang `approval_mode` ay kumokontrol kung kinakailangan ng pahintulot ng user bago isagawa ang bawat tawag.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a6507f83",
"metadata": {},
"outputs": [],
"source": [
"@tool(approval_mode=\"never_require\")\n",
"def get_destinations() -> list[str]:\n",
" \"\"\"Get available vacation destinations.\"\"\"\n",
" return [\"Barcelona\", \"Paris\", \"Berlin\", \"Tokyo\", \"Sydney\", \"New York City\"]\n",
"\n",
"\n",
"@tool(approval_mode=\"never_require\")\n",
"def check_availability(\n",
" destination: Annotated[str, \"The destination to check\"],\n",
") -> str:\n",
" \"\"\"Check booking availability for a destination.\"\"\"\n",
" availability = {\n",
" \"Barcelona\": \"Available - 3 spots left\",\n",
" \"Paris\": \"Available\",\n",
" \"Berlin\": \"Sold out\",\n",
" \"Tokyo\": \"Available - 1 spot left\",\n",
" \"Sydney\": \"Available\",\n",
" \"New York City\": \"Available\",\n",
" }\n",
" return availability.get(destination, \"Unknown destination\")\n",
"\n",
"\n",
"@tool(approval_mode=\"never_require\")\n",
"def get_flight_info(\n",
" origin: Annotated[str, \"Origin airport code\"],\n",
" destination: Annotated[str, \"Destination airport code\"],\n",
") -> str:\n",
" \"\"\"Get flight information between two cities.\"\"\"\n",
" flights = {\n",
" \"LHR-BCN\": \"BA 2042, Departs 08:30, Arrives 11:45, $350\",\n",
" \"LHR-CDG\": \"AF 1081, Departs 09:15, Arrives 11:30, $280\",\n",
" \"LHR-NRT\": \"JL 044, Departs 11:00, Arrives 07:00+1, $890\",\n",
" }\n",
" return flights.get(\n",
" f\"{origin}-{destination}\",\n",
" f\"No direct flights from {origin} to {destination}\",\n",
" )"
]
},
{
"cell_type": "markdown",
"id": "e9f0a1b2",
"metadata": {},
"source": [
"## Paglikha ng Agent na may Maramihang Kagamitan\n",
"\n",
"Ibigay ang lahat ng tatlong kagamitan sa kliyente upang ang modelo ay makatawag ng alinman sa mga ito na kailangan upang sagutin ang tanong ng gumagamit.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "be18ac4f",
"metadata": {},
"outputs": [],
"source": [
"travel_tools = [get_destinations, check_availability, get_flight_info]\n",
"\n",
"agent = client.as_agent(\n",
" name=\"TravelToolAgent\",\n",
" instructions=\"You are a travel agent. Use the available tools to answer questions about destinations, availability, and flights.\",\n",
" tools=travel_tools,\n",
")\n",
"\n",
"response = await agent.run(\n",
" \"What destinations do you have? Which ones are still available?\"\n",
")\n",
"print(response)"
]
},
{
"cell_type": "markdown",
"id": "c3d4e5f6",
"metadata": {},
"source": [
"## Structured Output with Tools\n",
"\n",
"Sa pamamagitan ng pagtatakda ng `response_format` sa isang Pydantic model, pinipilit ang ahente na magbalik ng maayos na naka-type na JSON object sa halip na malayang anyo ng teksto. Kapaki-pakinabang ito kapag kailangang gamitin ng downstream na code ang resulta sa programmatic na paraan.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "772e9481",
"metadata": {},
"outputs": [],
"source": [
"class BookingRecommendation(BaseModel):\n",
" destination: str\n",
" available: bool\n",
" flight_details: str\n",
" estimated_cost: int\n",
"\n",
"\n",
"class TravelPlan(BaseModel):\n",
" recommendations: list[BookingRecommendation]\n",
"\n",
"\n",
"structured_agent = client.as_agent(\n",
" name=\"StructuredTravelAgent\",\n",
" instructions=(\n",
" \"You are a travel agent. Use the available tools to find destinations, \"\n",
" \"check availability, and get flight info. Return structured results.\"\n",
" ),\n",
" tools=[get_destinations, check_availability, get_flight_info],\n",
")\n",
"\n",
"response = await structured_agent.run(\n",
" \"I want to fly from London Heathrow to somewhere warm in Europe. \"\n",
" \"Check what's available.\"\n",
")\n",
"if response:\n",
" print(response)"
]
},
{
"cell_type": "markdown",
"id": "a7b8c9d0",
"metadata": {},
"source": [
"## Mga Pattern ng Pag-apruba ng Tool\n",
"\n",
"Kinokontrol ng parameter na `approval_mode` sa `@tool` kung kailangan ba ng pag-apruba ng tao bago isagawa ang mga tawag sa tool:\n",
"\n",
"| Mode | Pag-uugali |\n",
"|---|---|\n",
"| `\"never_require\"` | Awtomatikong tumatakbo ang tool — hindi kailangan ng kumpirmasyon ng gumagamit. |\n",
"| `\"always_require\"` | Bawat tawag ay kailangang aprubahan ng gumagamit bago ito isagawa. |\n",
"\n",
"Gamitin ang `\"always_require\"` para sa mga tool na may mga side-effect (hal. pag-book ng flight, pagsingil ng credit card) upang manatiling kasama ang tao sa proseso.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a731b547",
"metadata": {},
"outputs": [],
"source": [
"@tool(approval_mode=\"always_require\")\n",
"def book_flight(\n",
" origin: Annotated[str, \"Origin airport code\"],\n",
" destination: Annotated[str, \"Destination airport code\"],\n",
" passenger_name: Annotated[str, \"Full name of the passenger\"],\n",
") -> str:\n",
" \"\"\"Book a flight for a passenger. Requires approval before executing.\"\"\"\n",
" return (\n",
" f\"Flight booked from {origin} to {destination} \"\n",
" f\"for {passenger_name}. Confirmation #TRV-2024-{hash(passenger_name) % 10000:04d}\"\n",
" )\n",
"\n",
"\n",
"print(\"Tool name:\", book_flight.name)\n",
"print(\"Approval mode:\", book_flight.approval_mode)"
]
},
{
"cell_type": "markdown",
"id": "f1e2d3c4",
"metadata": {},
"source": [
"## Summary\n",
"\n",
"Sa leksyong ito natutunan mo kung paano:\n",
"\n",
"1. **Mag-defina ng mga tools** gamit ang `@tool` decorator na may typed parameters at docstrings na nagsisilbing schema ng tool.\n",
"2. **Pagsamahin ang maraming tools** upang tawagan ito ng agent nang sunud-sunod para sagutin ang mga kumplikadong tanong.\n",
"3. **Magbalik ng istrukturadong output** sa pamamagitan ng pagpapasa ng modelong Pydantic bilang `response_format`.\n",
"4. **Kontrolin ang pag-apruba ng tool** gamit ang `approval_mode` upang mapanatili ang pagkakaroon ng tao sa proseso para sa mga sensitibong operasyon.\n",
"\n",
"Ang mga pattern na ito ang pundasyon para sa paggawa ng maaasahan at handang gamitin sa produksyon na mga agent na kayang makipag-ugnayan sa mga panlabas na sistema nang ligtas.\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n\n<!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**Pagtatanggi**:\nAng dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito.\n<!-- CO-OP TRANSLATOR DISCLAIMER END -->\n"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.0"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
在新工单中引用 查看 Git Blame 复制永久链接