{ "cells": [ { "cell_type": "markdown", "id": "f4cf9593", "metadata": {}, "source": [ "# 🐍 AI Travel Agent with Microsoft Agent Framework (Python)\n", "\n", "## πŸ“‹ Scenario Overview\n", "\n", "This notebook demonstrates how to build an intelligent travel planning agent using the Microsoft Agent Framework for Python. The agent leverages GitHub Models to automatically generate personalized day-trip itineraries for random destinations worldwide.\n", "\n", "**Key Features:**\n", "- 🎲 **Smart Destination Selection**: Custom tool function for random destination picking\n", "- πŸ—ΊοΈ **Detailed Itinerary Generation**: AI-powered travel planning with local recommendations\n", "- πŸ”„ **Async Processing**: Uses asyncio for efficient API communication\n", "- πŸ› οΈ **Tool Integration**: Demonstrates function calling capabilities in AI agents\n", "\n", "## πŸ—οΈ Technical Implementation\n", "\n", "### Core Components\n", "- **Agent Framework**: Python implementation of Microsoft's agent orchestration system\n", "- **GitHub Models API**: Access to state-of-the-art language models via GitHub's inference service\n", "- **OpenAI Compatibility**: Uses OpenAI client patterns with GitHub Models backend\n", "- **Environment Management**: Secure credential handling with python-dotenv\n", "\n", "### Architecture Flow\n", "```python\n", "User Request β†’ ChatAgent β†’ GitHub Models API ↔ get_random_destination()\n", " ↓\n", " Travel Itinerary Response\n", "```\n", "\n", "### Key Classes & Methods\n", "- `ChatAgent`: Main conversational agent orchestrator\n", "- `OpenAIChatClient`: GitHub Models API client wrapper\n", "- `get_random_destination()`: Custom tool function for destination selection\n", "- Environment variables: Secure API configuration management\n", "\n", "## βš™οΈ Prerequisites & Setup\n", "\n", "**Required Dependencies:**\n", "```bash\n", "\n", "pip install agent-framework-core -U\n", "```\n", "\n", "**Environment Configuration (.env file):**\n", "```env\n", "GITHUB_TOKEN=your_github_personal_access_token\n", "GITHUB_ENDPOINT=https://models.inference.ai.azure.com\n", "GITHUB_MODEL_ID=gpt-4o-mini\n", "```\n", "\n", "**GitHub Models Access:**\n", "1. Sign up for GitHub Models access\n", "2. Generate a personal access token\n", "3. Configure environment variables as shown above\n", "\n", "## πŸš€ Usage Instructions\n", "\n", "Execute the cells below in sequence to:\n", "1. Import required libraries and load environment variables\n", "2. Define the random destination generator tool\n", "3. Create and configure the AI agent\n", "4. Run travel planning requests and view results\n", "\n", "Let's build an intelligent travel planning assistant! 🌟" ] }, { "cell_type": "code", "execution_count": 1, "id": "fda5fa0a", "metadata": {}, "outputs": [], "source": [ "# ! pip install -r ../../../Installation/requirements.txt -U" ] }, { "cell_type": "code", "execution_count": 2, "id": "c0df8a52", "metadata": {}, "outputs": [], "source": [ "# πŸ“¦ Import Required Libraries\n", "# Standard library imports for system operations and random number generation\n", "import os\n", "from random import randint\n", "\n", "# Third-party library for loading environment variables from .env file\n", "from dotenv import load_dotenv" ] }, { "cell_type": "code", "execution_count": 3, "id": "151e0314", "metadata": {}, "outputs": [], "source": [ "# πŸ€– Import Microsoft Agent Framework Components\n", "# ChatAgent: The main agent class for conversational AI\n", "# OpenAIChatClient: Client for connecting to OpenAI-compatible APIs (including GitHub Models)\n", "from agent_framework import Agent\n", "from agent_framework.openai import OpenAIChatCompletionClient" ] }, { "cell_type": "code", "execution_count": 4, "id": "a6141584", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# πŸ”§ Load Environment Variables\n", "# This loads configuration from a .env file in the project root\n", "# Required variables: GITHUB_ENDPOINT, GITHUB_TOKEN, GITHUB_MODEL_ID\n", "load_dotenv()" ] }, { "cell_type": "code", "execution_count": 5, "id": "a6507f83", "metadata": {}, "outputs": [], "source": [ "# 🎲 Tool Function: Random Destination Generator\n", "# This function will be available to the agent as a tool\n", "# The agent can call this function to get random vacation destinations\n", "def get_random_destination() -> str:\n", " \"\"\"Get a random vacation destination.\n", " \n", " Returns:\n", " str: A randomly selected destination from our predefined list\n", " \"\"\"\n", " # List of popular vacation destinations around the world\n", " destinations = [\n", " \"Barcelona, Spain\",\n", " \"Paris, France\", \n", " \"Berlin, Germany\",\n", " \"Tokyo, Japan\",\n", " \"Sydney, Australia\",\n", " \"New York, USA\",\n", " \"Cairo, Egypt\",\n", " \"Cape Town, South Africa\",\n", " \"Rio de Janeiro, Brazil\",\n", " \"Bali, Indonesia\"\n", " ]\n", " # Return a random destination from the list\n", " return destinations[randint(0, len(destinations) - 1)]" ] }, { "cell_type": "code", "execution_count": 6, "id": "5d4f0568", "metadata": {}, "outputs": [], "source": [ "# πŸ”— Create OpenAI Chat Client for GitHub Models\n", "# This client connects to GitHub Models API (OpenAI-compatible endpoint)\n", "# Environment variables required:\n", "# - GITHUB_ENDPOINT: API endpoint URL (usually https://models.inference.ai.azure.com)\n", "# - GITHUB_TOKEN: Your GitHub personal access token\n", "# - GITHUB_MODEL_ID: Model to use (e.g., gpt-4o-mini, gpt-4o)\n", "openai_chat_client = OpenAIChatCompletionClient(\n", " base_url=os.environ.get(\"GITHUB_ENDPOINT\"),\n", " api_key=os.environ.get(\"GITHUB_TOKEN\"), \n", " model=os.environ.get(\"GITHUB_MODEL_ID\")\n", ")" ] }, { "cell_type": "code", "execution_count": 7, "id": "cf5a4800", "metadata": {}, "outputs": [], "source": [ "# πŸ€– Create the Travel Planning Agent\n", "# This creates a conversational AI agent with specific capabilities:\n", "# - client: The AI model client for generating responses\n", "# - instructions: System prompt that defines the agent's personality and role\n", "# - tools: List of functions the agent can call to perform actions\n", "agent = Agent(\n", " client=openai_chat_client,\n", " instructions=\"You are a helpful AI Agent that can help plan vacations for customers at random destinations.\",\n", " tools=[get_random_destination] # Our random destination tool function\n", ")" ] }, { "cell_type": "code", "execution_count": 8, "id": "772e9481", "metadata": {}, "outputs": [], "source": [ "# πŸš€ Run the Agent\n", "# Send a message to the agent and get a response\n", "# The agent will use its tools (get_random_destination) if needed\n", "response = await agent.run(\"Plan me a day trip\")" ] }, { "cell_type": "code", "execution_count": 9, "id": "93c114ea", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# πŸ“‹ View Raw Response Object\n", "# This shows the complete response structure including metadata\n", "# Useful for debugging and understanding the response format\n", "response" ] }, { "cell_type": "code", "execution_count": 10, "id": "a731b547", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "πŸ–οΈ Travel plan:\n", "I suggest a day trip to Cape Town, South Africa. Here's a possible itinerary for your day:\n", "\n", "Morning:\n", "- Start with a visit to Table Mountain. Take the cable car up for breathtaking views of the city and coastline.\n", "- Explore the mountain's trails if you're up for some light hiking.\n", "\n", "Lunch:\n", "- Head to the V&A Waterfront for lunch. There are many restaurants offering fresh seafood and local dishes.\n", "\n", "Afternoon:\n", "- Visit Robben Island, where Nelson Mandela was imprisoned. The historical tour is highly recommended.\n", "- Alternatively, explore the Kirstenbosch National Botanical Garden for a relaxing stroll among beautiful plants.\n", "\n", "Evening:\n", "- Enjoy dinner at a local restaurant in the city center or near Camps Bay beach.\n", "- If time allows, experience the vibrant nightlife or catch a live music performance.\n", "\n", "Would you like more detailed recommendations on places to eat, transport options, or other activities?\n" ] } ], "source": [ "# πŸ“– Extract and Display the Travel Plan\n", "# Get the last message from the conversation (agent's response)s\n", "last_message = response.messages[-1]\n", "# Extract the text content from the message\n", "text_content = last_message.contents[0].text\n", "# Display the formatted travel plan\n", "print(\"πŸ–οΈ Travel plan:\")\n", "print(text_content)" ] } ], "metadata": { "kernelspec": { "display_name": "agentdev", "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.10" }, "polyglot_notebook": { "kernelInfo": { "defaultKernelName": "csharp", "items": [ { "aliases": [], "name": "csharp" } ] } } }, "nbformat": 4, "nbformat_minor": 5 }