/translations/tl/03-agentic-design-patterns/code_samples/03-python-agent-framework.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "lesson-intro",
   "metadata": {},
   "source": [
    "# Lesson 03 - Mga Pattern ng Agentic Design\n",
    "\n",
    "Sa araling ito, tatalakayin natin ang tatlong pangunahing pattern ng disenyo para sa paggawa ng epektibong mga AI agent:\n",
    "\n",
    "1. **Malinaw na Instruksyon para sa Agent** — Paggawa ng tiyak at malinaw na mga prompt na nagtatalaga ng papel para gabayan ang kilos ng agent\n",
    "2. **Estrukturadong Output gamit ang Pydantic Models** — Pagtiyak na ang mga agent ay magbibigay ng inaasahan at na-validate na data\n",
    "3. **Mga Agent na May Isang Responsibilidad Lamang** — Pagdidisenyo ng mga nakatuong agent na mahusay sa isang gawain\n",
    "\n",
    "Ipapatupad natin ang bawat pattern sa isang **scenario ng tagapayo ng destinasyon sa paglalakbay**, unti-unting bumubuo ng sistema na kayang magmungkahi ng mga destinasyon, mag-check ng availability, at mag-asikaso ng mga logistics.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "setup-header",
   "metadata": {},
   "source": [
    "## Setup\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "setup-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install agent-framework azure-ai-projects azure-identity pydantic python-dotenv --quiet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "imports",
   "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",
    "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",
    "    )\n",
    "\n",
    "provider = FoundryChatClient(\n",
    "    project_endpoint=endpoint,\n",
    "    model=deployment_name,\n",
    "    credential=DefaultAzureCredential()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "pattern1-header",
   "metadata": {},
   "source": [
    "## Pattern 1: Malinaw na Mga Tagubilin para sa Ahente\n",
    "\n",
    "Ang pinakamabisang pattern ay ang pinakamadali rin: pagsulat ng malinaw, detalyadong mga tagubilin para sa iyong ahente.\n",
    "\n",
    "Magandang mga tagubilin ang naglalarawan:\n",
    "- **Sino** ang ahente (persona at tono)\n",
    "- **Ano** ang dapat gawin nito (mga hakbang-hakbang na responsibilidad)\n",
    "- **Paano** ito dapat kumilos (mga limitasyon at estilo)\n",
    "\n",
    "Sa ibaba, gagawa tayo ng isang travel concierge agent na may malinaw na mga tagubilin na humuhubog sa bawat tugon na kanyang ginagawa.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "pattern1-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = provider.as_agent(\n",
    "    name=\"TravelConcierge\",\n",
    "    instructions=\"\"\"You are a luxury travel concierge named Alex. Your role is to:\n",
    "1. Understand the traveler's preferences (budget, climate, activities)\n",
    "2. Check destination availability before making recommendations\n",
    "3. Provide detailed, personalized travel suggestions\n",
    "4. Always mention visa requirements and best travel seasons\n",
    "Be warm, professional, and enthusiastic about travel.\"\"\",\n",
    ")\n",
    "\n",
    "response = await agent.run(\n",
    "    \"I'd love a week-long vacation somewhere with great food and history. Budget around $2500.\"\n",
    ")\n",
    "print(response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "pattern2-header",
   "metadata": {},
   "source": [
    "## Pattern 2: Istrakturadong Output gamit ang mga Pydantic Models\n",
    "\n",
    "Ang free-form na teksto ay kapaki-pakinabang para sa usapan, ngunit ang mga downstream na sistema ay nangangailangan ng istrakturadong data.\n",
    "Sa pamamagitan ng pagpares ng **mga Pydantic model** sa isang **tool function**, maaari nating:\n",
    "\n",
    "- Tukuyin ang eksaktong iskema para sa output ng ahente\n",
    "- Awtomatiko na i-validate ang mga sagot\n",
    "- Maayos na isama ang mga resulta ng ahente sa lohika ng aplikasyon\n",
    "\n",
    "Nagpapakilala rin kami ng isang tool na nagbabalik ng mga detalye ng destinasyon upang maging batayan ng ahente ang mga rekomendasyon nito sa totoong data.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "pattern2-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "class DestinationRecommendation(BaseModel):\n",
    "    destination: str\n",
    "    available: bool\n",
    "    best_season: str\n",
    "    highlights: list[str]\n",
    "    estimated_budget_usd: int\n",
    "\n",
    "\n",
    "class TravelRecommendations(BaseModel):\n",
    "    recommendations: list[DestinationRecommendation]\n",
    "    personalized_note: str\n",
    "\n",
    "\n",
    "@tool(approval_mode=\"never_require\")\n",
    "def get_destination_details(destination: Annotated[str, \"The destination to look up\"]) -> str:\n",
    "    \"\"\"Get details about a vacation destination.\"\"\"\n",
    "    details = {\n",
    "        \"Barcelona\": \"Available. Best: May-Jun. Beach, architecture, nightlife. ~$2000/week\",\n",
    "        \"Tokyo\": \"Available. Best: Mar-Apr. Culture, food, technology. ~$2500/week\",\n",
    "        \"Cape Town\": \"Not available. Best: Nov-Mar. Nature, wine, adventure. ~$1800/week\",\n",
    "    }\n",
    "    return details.get(destination, f\"{destination}: No information available.\")\n",
    "\n",
    "\n",
    "structured_agent = provider.as_agent(\n",
    "    name=\"StructuredTravelExpert\",\n",
    "    instructions=\"You are a travel expert. Recommend destinations based on traveler preferences. Use the get_destination_details tool.\",\n",
    "    tools=[get_destination_details],\n",
    ")\n",
    "\n",
    "response = await structured_agent.run(\n",
    "    \"Recommend 3 destinations for a culture-loving traveler with a $2500 budget\"\n",
    ")\n",
    "\n",
    "if response:\n",
    "    print(response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "pattern3-header",
   "metadata": {},
   "source": [
    "## Pattern 3: Mga Ahenteng may Isa lamang na Responsibilidad\n",
    "\n",
    "Nakikinabang ang mga komplikadong gawain sa paghahati ng trabaho sa iba't ibang pokus na mga ahente, bawat isa ay may iisang responsibilidad:\n",
    "\n",
    "- Isang **Eksperto sa Destinasyon** na may alam tungkol sa mga lugar at availability\n",
    "- Isang **Tagaplano ng Lohistika** na humahawak ng mga flight, hotel, at itineraryo\n",
    "\n",
    "Ito ay sumasalamin sa prinsipyo ng software engineering na *paghiwalay ng mga responsibilidad* — ang bawat ahente ay mas madaling subukan, panatilihin, at pagbutihin nang nakapag-iisa.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "pattern3-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "destination_agent = provider.as_agent(\n",
    "    name=\"DestinationExpert\",\n",
    "    tools=[get_destination_details],\n",
    "    instructions=\"\"\"You are a destination research specialist. Your only job is to:\n",
    "1. Evaluate destinations based on traveler preferences\n",
    "2. Check availability using the provided tool\n",
    "3. Return a short ranked list with pros/cons\n",
    "Do NOT discuss flights, hotels, or logistics — another agent handles that.\"\"\",\n",
    ")\n",
    "\n",
    "logistics_agent = provider.as_agent(\n",
    "    name=\"LogisticsPlanner\",\n",
    "    instructions=\"\"\"You are a travel logistics planner. Your only job is to:\n",
    "1. Create a day-by-day itinerary for the chosen destination\n",
    "2. Suggest flight and hotel options within the stated budget\n",
    "3. Note visa requirements and travel insurance recommendations\n",
    "Do NOT recommend destinations — another agent handles that.\"\"\",\n",
    ")\n",
    "\n",
    "# Step 1: Destination Expert picks the best options\n",
    "dest_response = await destination_agent.run(\n",
    "    \"I want a week of culture and food for under $2500. Where should I go?\"\n",
    ")\n",
    "print(\"=== Destination Expert ===\")\n",
    "print(dest_response)\n",
    "\n",
    "# Step 2: Logistics Planner builds the trip plan\n",
    "logistics_response = await logistics_agent.run(\n",
    "    f\"Plan a week-long trip based on this recommendation:\\n{dest_response}\"\n",
    ")\n",
    "print(\"\\n=== Logistics Planner ===\")\n",
    "print(logistics_response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "summary",
   "metadata": {},
   "source": [
    "## Buod\n",
    "\n",
    "Sa araling ito, inilapat namin ang tatlong disenyo ng agentic sa isang senaryo ng tagapagrekomenda ng paglalakbay:\n",
    "\n",
    "| Pattern | Pangunahing Ideya | Benepisyo |\n",
    "|---|---|---|\n",
    "| **Malinaw na Mga Tagubilin** | Tukuyin ang persona, mga responsibilidad, at mga limitasyon mula sa simula | Pare-pareho, ayon sa tatak na kilos ng ahente |\n",
    "| **Nakasalalay na Output** | Gamitin ang mga modelong Pydantic bilang format ng tugon | Napatunayan, nababasang makina na mga resulta |\n",
    "| **Isang Responsibilidad** | Bigyan ang bawat ahente ng isang pokus na gawain | Mas madaling subukan, panatilihin, at pagsamahin |\n",
    "\n",
    "Ang mga pattern na ito ay kusang bumubuo — maaari mong pagsamahin ang malinaw na mga tagubilin sa nakasalalay na output sa loob ng isang ahente na may isang responsibilidad upang bumuo ng matibay, handa sa produksyon na mga sistema.\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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}