{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f4cf9593",
   "metadata": {},
   "source": [
    "# 课程 01 - AI 代理简介\n",
    "\n",
    "欢迎来到 **AI 新手代理** 课程的第一课！\n",
    "\n",
    "**AI 代理** 是一个使用大型语言模型（LLM）作为推理引擎的程序，并且能够在现实世界中采取<em>行动</em> —— 调用 API、查询数据库或运行代码 —— 以代表用户完成目标。\n",
    "\n",
    "在本笔记本中，您将构建第一个代理：一个推荐度假目的地的 <strong>旅行代理</strong>。在此过程中，您将学习如何：\n",
    "\n",
    "1. 使用 **Microsoft Agent Framework** 连接到 Microsoft Foundry Agent 服务。\n",
    "2. 给代理一个 <strong>工具</strong> —— 一个它可以调用的普通 Python 函数。\n",
    "3. 运行代理并检查其响应。\n",
    "4. 逐个令牌流式传输代理的响应。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1e2c3d4",
   "metadata": {},
   "source": [
    "## 设置\n",
    "\n",
    "在运行此笔记本之前，请确保您已完成以下操作：\n",
    "\n",
    "1. **拥有一个 Microsoft Foundry 项目** 并已部署聊天模型（例如 `gpt-5-mini`）。\n",
    "2. **已使用 Azure CLI 登录** — 在终端运行 `az login`。\n",
    "3. **设置必需的环境变量：**\n",
    "   - `AZURE_AI_PROJECT_ENDPOINT` — 您的 Microsoft Foundry 项目端点。\n",
    "   - `AZURE_AI_MODEL_DEPLOYMENT_NAME` — 您已部署模型的名称。\n",
    "\n",
    "下面的单元格将安装您需要的 Python 包。\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fda5fa0a",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install agent-framework azure-ai-projects azure-identity -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 dotenv\n",
    "from agent_framework.foundry import FoundryChatClient\n",
    "from azure.identity import AzureCliCredential\n",
    "from agent_framework import tool\n",
    "\n",
    "dotenv.load_dotenv(dotenv.find_dotenv())\n",
    "\n",
    "endpoint = os.getenv(\"AZURE_AI_PROJECT_ENDPOINT\")\n",
    "model = os.getenv(\"AZURE_AI_MODEL_DEPLOYMENT_NAME\")\n",
    "\n",
    "if not endpoint or not model:\n",
    "    raise ValueError(\n",
    "        \"Missing required environment variables. \"\n",
    "        \"Please set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME in your .env file.\"\n",
    "    )\n",
    "\n",
    "provider = FoundryChatClient(\n",
    "    project_endpoint=endpoint,\n",
    "    model=model,\n",
    "    credential=AzureCliCredential()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5f6a7b8",
   "metadata": {},
   "source": [
    "## 创建你的第一个智能体\n",
    "\n",
    "一个智能体需要两样东西：\n",
    "\n",
    "- <strong>指令</strong>，告诉它<em>它是谁</em>以及<em>如何表现</em>（系统提示）。\n",
    "- <strong>工具</strong> —— 用 `@tool` 装饰的 Python 函数，智能体可以调用它们来获取信息或执行操作。\n",
    "\n",
    "下面我们定义了一个简单的工具，它返回一个受欢迎的度假目的地列表。当用户询问旅行推荐时，智能体将使用此工具。\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 a list of popular vacation destinations.\"\"\"\n",
    "    return [\n",
    "        \"Barcelona\",\n",
    "        \"Paris\",\n",
    "        \"Berlin\",\n",
    "        \"Tokyo\",\n",
    "        \"Sydney\",\n",
    "        \"New York City\",\n",
    "        \"Cairo\",\n",
    "        \"Cape Town\",\n",
    "        \"Rio de Janeiro\",\n",
    "        \"Bali\",\n",
    "    ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cf5a4800",
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = provider.as_agent(\n",
    "    name=\"TravelAgent\",\n",
    "    instructions=(\n",
    "        \"You are a helpful travel agent. Help users find their perfect vacation \"\n",
    "        \"destination based on their preferences. Use the get_destinations tool \"\n",
    "        \"to see available destinations.\"\n",
    "    ),\n",
    "    tools=[get_destinations],\n",
    ")\n",
    "\n",
    "response = await agent.run(\n",
    "    \"I'm looking for a warm beach destination. What do you recommend?\"\n",
    ")\n",
    "print(response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9e0f1a2",
   "metadata": {},
   "source": [
    "## 流式响应\n",
    "\n",
    "为了获得更互动的体验，您可以<strong>流式</strong>获取代理的响应。代理会随着文本生成逐块产出，而不是等待完整回复。这在聊天界面中特别有用，因为您希望实时展示输出内容。\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "772e9481",
   "metadata": {},
   "outputs": [],
   "source": [
    "async for chunk in agent.run(\n",
    "    \"Tell me about Tokyo as a travel destination\", stream=True\n",
    "):\n",
    "    print(chunk, end=\"\", flush=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3b4c5d6",
   "metadata": {},
   "source": [
    "## 总结\n",
    "\n",
    "在本课中，您学到了如何：\n",
    "\n",
    "- <strong>创建一个提供程序</strong>，通过 `FoundryChatClient` 连接到 Microsoft Foundry Agent Service。\n",
    "- **使用 `@tool` 装饰器定义工具**，以便代理可以调用您的 Python 函数。\n",
    "- <strong>运行代理</strong>，发送用户消息并打印其响应。\n",
    "- <strong>流式传输响应</strong>，实现实时输出。\n",
    "\n",
    "在下一课中，我们将更深入地探讨代理框架，并学习如何赋予代理更强大的工具和多步骤推理能力。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n\n<!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**免责声明**：\n本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。\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
}