diff --git a/assets/images/tutorial-observation-apmplus-tracing.png b/assets/images/tutorial-observation-apmplus-tracing.png
new file mode 100644
index 00000000..f9f821c4
Binary files /dev/null and b/assets/images/tutorial-observation-apmplus-tracing.png differ
diff --git a/assets/images/tutorial-observation-cozeloop.png b/assets/images/tutorial-observation-cozeloop.png
new file mode 100644
index 00000000..1cd39320
Binary files /dev/null and b/assets/images/tutorial-observation-cozeloop.png differ
diff --git a/veadk_tutorial.ipynb b/veadk_tutorial.ipynb
new file mode 100644
index 00000000..61fd7a6f
--- /dev/null
+++ b/veadk_tutorial.ipynb
@@ -0,0 +1,2118 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "kMvAhdnYWpIf"
+ },
+ "source": [
+ "# **Volcengine Agent Development Kit 教程**"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "Sp8ynUiFXIHi"
+ },
+ "source": [
+ "## 介绍"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "mS7BD6K0Xkr9"
+ },
+ "source": [
+ "VeADK 是由火山引擎推出的一套面向智能体开发的全流程框架，旨在为开发者提供面向智能体构建、云端部署、评测与优化的全流程开发。\n",
+ "\n",
+ "相较于现有的智能体开发框架，VeADK 具备与火山引擎产品体系深度融合的优势，帮助开发者更高效地构建企业级 AI 智能体应用。"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "xw8bJmYEXJgg"
+ },
+ "source": [
+ "## 配置"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "nDzTOuunaSPB"
+ },
+ "source": [
+ "### 安装 VeADK"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "aAZ40k9uXhm6"
+ },
+ "outputs": [],
+ "source": [
+ "%pip install veadk-python --quiet"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "R0IY257hncOB"
+ },
+ "source": [
+ "> 如果你在本地使用的终端是`zsh`，当你进行`pip install`时，**依赖包名称应当被双引号包裹起来**，否则会解析错误。\n",
+ ">\n",
+ "> 你应当使用：\n",
+ "> ```bash\n",
+ "> pip install \"veadk-python\"\n",
+ "> pip install \"agent-pilot-sdk>=0.0.9\"\n",
+ "> ```"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "a-0A36gmXfJj"
+ },
+ "source": [
+ "### 环境变量"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {
+ "id": "B6o2LmjGXdb2"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "os.environ[\"MODEL_AGENT_NAME\"] = \"doubao-seed-1-6-250615\" # <-- 火山方舟大模型名称\n",
+ "\n",
+ "os.environ[\"MODEL_AGENT_API_KEY\"] = \"\" # <-- 设置火山方舟的API KEY来访问模型\n",
+ "\n",
+ "os.environ[\"LOGGING_LEVEL\"] = \"ERROR\" # <-- 调整日志等级"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "HCw_PEP5X-fc"
+ },
+ "source": [
+ "## Agent 构建"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "0rtLXYn4aoQt"
+ },
+ "source": [
+ "### 快速开始\n",
+ "\n",
+ "初始化Agent过程中，你可以不传入任何参数，VeADK 会自动读取环境变量。查看[完整的 Agent 参数](https://volcengine.github.io/veadk-python/agent.html#属性)。"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "l8yM5QKjYAVo",
+ "outputId": "239b8f05-25a5-4266-8142-a1204fefe031"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hello! It's fantastic to connect with a fellow Agent developer. As someone working in this space, you might be building Agents for specific domains like automation, data processing, or even multi-modal interaction. Are you currently focused on a particular project—maybe refining an existing Agent's capabilities, solving integration challenges (like tool APIs or workflow logic), or exploring new use cases? If you have questions about architecture design, optimizing response efficiency, or best practices for Agent-human collaboration, feel free to share—I’d love to help brainstorm or troubleshoot! 😊\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent\n",
+ "\n",
+ "agent = Agent() # 初始化 Agent\n",
+ "\n",
+ "response = await agent.run(\"你好，我是一名 Agent 开发者。\")\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "bnX7pSDFbuYY"
+ },
+ "source": [
+ "### 使用 Runner\n",
+ "\n",
+ "生产环境下的最佳实践：使用`Runner`来运行 Agent，通过`app_name`、`user_id`以及`session_id`以实现多租户隔离。"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "CYC9Z0_Yb-SX",
+ "outputId": "69d80b01-a820-4e62-e91d-d96682c3073a"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "你好！很高兴认识你这位 Agent 开发者！开发智能 Agent 确实是一项充满挑战又极具创造力的工作呢。你目前是在开发某个特定领域的 Agent（比如数据处理、自动化任务、智能交互等），还是在构建 Agent 框架或工具呢？如果在开发过程中遇到任何问题——比如数据科学模块的设计、代码实现（Python/JavaScript 等）、文档撰写，或者 Agent 与外部工具的集成等，都可以随时告诉我，我很乐意和你一起探讨解决方案！ 😊\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "agent = Agent()\n",
+ "short_term_memory = ShortTermMemory() # 短期记忆代表的是用户单次会话内的对话记录\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "# 使用 runner 中的`run`方法来调用 Agent\n",
+ "response = await runner.run(messages=\"你好，我是一名 Agent 开发者。\", session_id=session_id)\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "4WVpEzN_ale6"
+ },
+ "source": [
+ "### 使用 Tools"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "U3yLU8WndkTj"
+ },
+ "source": [
+ "初始化 Agent 时，你可以使用`tools`字段来挂载工具："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "KYoeTLH1c5nG",
+ "outputId": "58b57f13-68b6-45dd-f492-7b3abccd268b"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "北京现在天气晴朗，气温25°C。\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "from veadk.tools.demo_tools import get_city_weather\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "agent = Agent(tools=[get_city_weather])\n",
+ "short_term_memory = ShortTermMemory()\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "response = await runner.run(messages=\"北京的天气怎么样？\", session_id=session_id)\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "TWGfvP7peFPe"
+ },
+ "source": [
+ "你还可以体验**火山引擎提供的强大搜索能力**，例如使用`web_search`和`VeSearch`工具等。"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "JDtvFNcAy9FK"
+ },
+ "source": [
+ "使用`web_search`工具："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {
+ "id": "HxUlgqZAeKUn"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# 设置火山引擎 AK 和 SK 来使用 web_search 工具\n",
+ "os.environ[\"VOLCENGINE_ACCESS_KEY\"] = \"\"\n",
+ "os.environ[\"VOLCENGINE_SECRET_KEY\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "ZuToGTbOeTEB",
+ "outputId": "e360b132-1bff-4ed4-bf66-7910cd95d164"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "根据北京市生态环境监测中心数据，**今天（8月15日）北京空气质量指数（AQI）为40，等级为优**。具体污染物浓度如下： \n",
+ "- PM2.5：38 μg/m³ \n",
+ "- PM10：38 μg/m³ \n",
+ "- O3：24 μg/m³ \n",
+ "- NO2：7 μg/m³ \n",
+ "- SO2：1 μg/m³ \n",
+ "- CO：0.6 mg/m³ \n",
+ "\n",
+ "**建议措施**：各类人群可正常活动。 \n",
+ "\n",
+ "此外，未来三天（16-18日）空气质量预计维持优至良等级，首要污染物为臭氧（O3），需注意夏季臭氧污染防护。\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "from veadk.tools.builtin_tools.web_search import web_search\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "agent = Agent(tools=[web_search])\n",
+ "short_term_memory = ShortTermMemory()\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "response = await runner.run(messages=\"北京今天的空气质量\", session_id=session_id)\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "IoTXmqz8zAvp"
+ },
+ "source": [
+ "尝试使用`VeSearch`工具："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {
+ "id": "YhYG3VxpzE8i"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# 设置 vesearch 工具的 ENDPOINT 和 API KEY\n",
+ "os.environ[\"TOOL_VESEARCH_ENDPOINT\"] = \"\"\n",
+ "os.environ[\"TOOL_VESEARCH_API_KEY\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "948i9Be8zIvr",
+ "outputId": "ad556c58-f48a-4306-b812-969f4d38148a"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "### 北京未来七天天气预报（2025年8月16日-8月22日） \n",
+ "- **8月16日（周六）**：雷阵雨，24-31℃，南风1级，湿度82%，紫外线指数4，空气质量良。 \n",
+ "- **8月17日（周日）**：雷阵雨，24-30℃，东风1级，湿度85%，紫外线指数4，空气质量良。 \n",
+ "- **8月18日（周一）**：阴转雷阵雨，24-30℃，南风1级，湿度89%，紫外线指数4，空气质量良。 \n",
+ "- **8月19日（周二）**：雷阵雨，24-29℃，西北风1级，湿度86%，紫外线指数3，空气质量良。 \n",
+ "- **8月20日（周三）**：阴转雷阵雨，24-31℃，东南风1级，湿度86%，紫外线指数4，空气质量良。 \n",
+ "- **8月21日（周四）**：小雨转阴天，24-32℃，西南风1级，湿度80%，紫外线指数3，空气质量信息暂缺。 \n",
+ "- **8月22日（周五）**：晴，22-30℃，南风1级，湿度69%，紫外线指数5，空气质量信息暂缺。 \n",
+ "\n",
+ "### 重要提示 \n",
+ "- **预警信息**：15日傍晚至16日早晨有暴雨（小时雨强可达30毫米以上）及雷电，局地伴7级短时大风，山区需防范山洪、泥石流等次生灾害。 \n",
+ "- **生活建议**：未来三天（15-17日）不适宜洗车和户外活动，需随身携带雨具，注意防雷防雨。\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "from veadk.tools.builtin_tools.vesearch import vesearch\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "agent = Agent(tools=[vesearch])\n",
+ "short_term_memory = ShortTermMemory()\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "response = await runner.run(messages=\"未来七天北京的天气\", session_id=session_id)\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "qlLT8MMTbLmd"
+ },
+ "source": [
+ "### 短期记忆"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "0rzy1X8lXGLk"
+ },
+ "source": [
+ "你可以初始化一个`Local`模式的短期记忆，它只会存在与内存中。其仅在一次调用中会有记忆。"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "8L9ORClwXWbj",
+ "outputId": "9ab3735c-2ec7-4b2d-fadc-1dd4cd0dc398"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "当然记得！你叫VeADK，很高兴再次和你交流 😊\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "agent = Agent()\n",
+ "short_term_memory = ShortTermMemory(backend=\"local\") # 指定 local 后端，或直接 ShortTermMemory()\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "response = await runner.run(messages=[\"我叫VeADK\", \"你还记得我叫什么吗？\"], session_id=session_id)\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "_s35YbMcpXfd"
+ },
+ "source": [
+ "VeADK 还支持你将短期记忆持久化存储在云端，未来的某一时刻你可以加载历史对话。\n",
+ "\n",
+ "在使用云端记忆之前，需要安装`database`相关的依赖："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "3J7csxCJt9H1"
+ },
+ "outputs": [],
+ "source": [
+ "%pip install veadk-python[database] --quiet"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "VWTlOcEJwBrh"
+ },
+ "source": [
+ "使用 MySQL 作为短期记忆的数据库后端："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "MO6JCIAnqtES"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "os.environ[\"DATABASE_MYSQL_HOST\"] = \"\"\n",
+ "os.environ[\"DATABASE_MYSQL_USER\"] = \"\"\n",
+ "os.environ[\"DATABASE_MYSQL_PASSWORD\"] = \"\"\n",
+ "os.environ[\"DATABASE_MYSQL_DATABASE\"] = \"\"\n",
+ "os.environ[\"DATABASE_MYSQL_CHARSET\"] = \"utf8\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "aNJSp3Npo-cf",
+ "outputId": "932d4c63-bc02-480c-d037-36717bf867cb"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "原来你在7月15日买了20个冰激凌呀，数量不少呢！是有什么特别的场合需要用到这么多，还是单纯想囤货慢慢吃呀？ 😄 如果你需要记录这个购买信息、做简单的消费统计，或者有其他相关的小需求，随时告诉我，我可以帮你~\n",
+ "You mentioned that you bought the ice cream on July 15th. 😊\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "agent = Agent()\n",
+ "short_term_memory = ShortTermMemory(backend=\"mysql\") # 指定 mysql 后端\n",
+ "runner = Runner(agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id)\n",
+ "\n",
+ "prompt = \"我在 7 月 15 日购买了 20 个冰激凌\"\n",
+ "response = await runner.run(messages=prompt, session_id=session_id)\n",
+ "print(response)\n",
+ "\n",
+ "prompt = \"我什么时候买了冰激凌？\"\n",
+ "response = await runner.run(messages=prompt, session_id=session_id)\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "-z0V-jFqbP0u"
+ },
+ "source": [
+ "### 长期记忆"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "k9wKEHeYxIUT"
+ },
+ "source": [
+ "在使用记忆之前，需要安装`database`相关的依赖：\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "VZIeRU1QxHrk"
+ },
+ "outputs": [],
+ "source": [
+ "%pip install veadk-python[database] --quiet"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "hMrtrd2DxUar"
+ },
+ "source": [
+ "使用 OpenSearch 作为长期记忆的数据库后端："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "foSDByHiwJsp"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# OpenSearch 配置\n",
+ "os.environ[\"DATABASE_OPENSEARCH_HOST\"] = \"\"\n",
+ "os.environ[\"DATABASE_OPENSEARCH_PORT\"] = \"\"\n",
+ "os.environ[\"DATABASE_OPENSEARCH_USERNAME\"] = \"\"\n",
+ "os.environ[\"DATABASE_OPENSEARCH_PASSWORD\"] = \"\"\n",
+ "\n",
+ "# Embedding 配置（使用 OpenSearch 时，需要对文本进行向量化处理）\n",
+ "# 设置访问火山方舟的 Embedding 模型\n",
+ "os.environ[\"MODEL_EMBEDDING_NAME\"] = \"doubao-embedding-text-240715\"\n",
+ "os.environ[\"MODEL_EMBEDDING_API_BASE\"] = \"https://ark.cn-beijing.volces.com/api/v3/embeddings\"\n",
+ "os.environ[\"MODEL_EMBEDDING_DIM\"] = \"2560\"\n",
+ "os.environ[\"MODEL_EMBEDDING_API_KEY\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "8bjfZ6VwwLuI",
+ "outputId": "5c8dfc66-20b7-4384-d3c4-3999c1081d82"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "你上周五购买了一支冰激凌。\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.long_term_memory import LongTermMemory\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "\n",
+ "# 初始化一个长期记忆，采用 OpenSearch 向量化存储\n",
+ "# 长期记忆是跨 Session 的\n",
+ "long_term_memory = LongTermMemory(backend=\"opensearch\")\n",
+ "\n",
+ "agent = Agent(long_term_memory=long_term_memory)\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id,\n",
+ " short_term_memory=ShortTermMemory(),\n",
+ ")\n",
+ "\n",
+ "\n",
+ "# ===== 插入记忆 =====\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "teaching_prompt = \"我上周五购买了一支冰激凌。\"\n",
+ "\n",
+ "await runner.run(messages=teaching_prompt, session_id=session_id)\n",
+ "await runner.save_session_to_long_term_memory(session_id=session_id) # 将 teaching prompt 和智能体回答保存到长期记忆中\n",
+ "\n",
+ "\n",
+ "# ===== 检验记忆 =====\n",
+ "session_id = \"veadk_playground_session_2\" # 使用一个新的 Session 来检测跨 Session 检索\n",
+ "student_prompt = \"我上周五购买了什么? 用中文回答我。\"\n",
+ "\n",
+ "response = await runner.run(messages=student_prompt, session_id=session_id)\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "aEFDAJdtiiz1"
+ },
+ "source": [
+ "使用 Viking Memory 作为长期记忆的后端："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {
+ "id": "ng-LsHSrtE86"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# Viking 记忆库配置\n",
+ "os.environ[\"DATABASE_VIKING_PROJECT\"] = \"\"\n",
+ "os.environ[\"DATABASE_VIKING_REGION\"] = \"cn-beijing\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "metadata": {
+ "id": "3QJbO5JqixP6"
+ },
+ "outputs": [],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.long_term_memory import LongTermMemory\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "\n",
+ "# 初始化一个长期记忆，采用 Viking Memory 存储\n",
+ "# 长期记忆是跨 Session 的\n",
+ "long_term_memory = LongTermMemory(backend=\"viking\")\n",
+ "\n",
+ "agent = Agent(long_term_memory=long_term_memory)\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id,\n",
+ " short_term_memory=ShortTermMemory(),\n",
+ ")\n",
+ "\n",
+ "\n",
+ "# ===== 插入记忆 =====\n",
+ "session_id = \"veadk_playground_session_3\"\n",
+ "teaching_prompt = \"我这周三购买了三本书。\"\n",
+ "\n",
+ "await runner.run(messages=teaching_prompt, session_id=session_id)\n",
+ "await runner.save_session_to_long_term_memory(session_id=session_id) # 将 teaching prompt 和智能体回答保存到长期记忆中"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "4fbwGcOskUxX"
+ },
+ "source": [
+ "由于初始使用 Viking Memory 需要构建索引，因此需要等待 1-2 分钟。等待过后，执行如下代码检验："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "5kVLsehDkU8w",
+ "outputId": "91e309c8-c66f-455e-ce30-78f3c2c5ec5a"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "根据记忆记录，你在2025年8月13日（周三）购买了三本书。\n"
+ ]
+ }
+ ],
+ "source": [
+ "# ===== 检验记忆 =====\n",
+ "session_id = \"veadk_playground_session_4\" # 使用一个新的 Session 来检测跨 Session 检索\n",
+ "student_prompt = \"我这周三购买了什么? 用中文回答我。\"\n",
+ "\n",
+ "response = await runner.run(messages=student_prompt, session_id=session_id)\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "KavP1J1YbRRq"
+ },
+ "source": [
+ "### 知识库"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "_jZauBoRztaU"
+ },
+ "source": [
+ "由于知识库需要用到云端的向量化存储，因此在使用知识库之前，需要安装`database`相关的依赖："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "xuozqr1Hzwjz"
+ },
+ "outputs": [],
+ "source": [
+ "%pip install veadk-python[database] --quiet"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "8N01Na5az3iR"
+ },
+ "source": [
+ "使用 OpenSearch 作为知识库的后端："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "metadata": {
+ "id": "hxemLCX_0FP6"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# OpenSearch 配置\n",
+ "os.environ[\"DATABASE_OPENSEARCH_HOST\"] = \"\"\n",
+ "os.environ[\"DATABASE_OPENSEARCH_PORT\"] = \"9200\"\n",
+ "os.environ[\"DATABASE_OPENSEARCH_USERNAME\"] = \"\"\n",
+ "os.environ[\"DATABASE_OPENSEARCH_PASSWORD\"] = \"\"\n",
+ "\n",
+ "# 设置访问火山方舟的 Embedding 模型\n",
+ "os.environ[\"MODEL_EMBEDDING_NAME\"] = \"doubao-embedding-text-240715\"\n",
+ "os.environ[\"MODEL_EMBEDDING_API_BASE\"] = \"https://ark.cn-beijing.volces.com/api/v3/embeddings\"\n",
+ "os.environ[\"MODEL_EMBEDDING_DIM\"] = \"2560\"\n",
+ "os.environ[\"MODEL_EMBEDDING_API_KEY\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "dkhNOiQWnR7m",
+ "outputId": "863bfd61-6218-471a-dc66-e743cc1e51bb"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Knowledgebase file path: /tmp/knowledgebase.md\n"
+ ]
+ }
+ ],
+ "source": [
+ "# 准备知识库文档并保存到本地\n",
+ "content = \"\"\"\n",
+ " The secret of red is red_000000.\n",
+ " The secret of green is green_000111.\n",
+ " The secret of blue is blue_000222.\n",
+ " The secret of yellow is yellow_000333.\n",
+ "\"\"\"\n",
+ "\n",
+ "knowledgebase_file = \"/tmp/knowledgebase.md\"\n",
+ "with open(knowledgebase_file, \"w\", encoding=\"utf-8\") as f:\n",
+ " f.write(content)\n",
+ "\n",
+ "print(f\"Knowledgebase file path: {knowledgebase_file}\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "t_CC_0xJ0G8l",
+ "outputId": "41faebcd-c0fe-40e9-af54-576aefe6a33b"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "The secret of green is green_000111.\n"
+ ]
+ }
+ ],
+ "source": [
+ "import os\n",
+ "\n",
+ "from veadk import Agent, Runner\n",
+ "from veadk.knowledgebase.knowledgebase import KnowledgeBase\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "if os.path.exists(knowledgebase_file):\n",
+ " with open(knowledgebase_file, \"r\", encoding=\"utf-8\") as f:\n",
+ " knowledgebase_data = [line.strip() for line in f if line.strip()] # 手动切片文档内容\n",
+ "\n",
+ "knowledgebase = KnowledgeBase(backend=\"opensearch\") # 指定 opensearch 后端\n",
+ "knowledgebase.add(knowledgebase_data, app_name=app_name)\n",
+ "\n",
+ "agent = Agent(knowledgebase=knowledgebase)\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=ShortTermMemory(),\n",
+ " app_name=app_name,\n",
+ " user_id=user_id,\n",
+ ")\n",
+ "\n",
+ "response = await runner.run(messages=\"Tell me the secret of green.\", session_id=session_id)\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "V87HcIZXlijp"
+ },
+ "source": [
+ "使用 Viking DB 作为知识库的后端："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 14,
+ "metadata": {
+ "id": "kMOEqTbOlj-f"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# Viking DB 配置\n",
+ "os.environ[\"DATABASE_VIKING_PROJECT\"] = \"\"\n",
+ "os.environ[\"DATABASE_VIKING_REGION\"] = \"cn-beijing\"\n",
+ "\n",
+ "# 存储桶配置\n",
+ "os.environ[\"DATABASE_TOS_ENDPOINT\"] = \"tos-cn-beijing.volces.com\"\n",
+ "os.environ[\"DATABASE_TOS_REGION\"] = \"cn-beijing\"\n",
+ "os.environ[\"DATABASE_TOS_BUCKET\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "Hcx0bJwh0MI7",
+ "outputId": "67cd6291-63a2-404d-a5a9-e4221ad89420"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Knowledgebase file path: /tmp/knowledgebase.pdf\n"
+ ]
+ }
+ ],
+ "source": [
+ "import os\n",
+ "import requests\n",
+ "\n",
+ "# 准备知识库文档并保存到本地\n",
+ "pdf_url = \"https://arxiv.org/pdf/1706.03762\"\n",
+ "pdf_path = \"/tmp/knowledgebase.pdf\"\n",
+ "resp = requests.get(pdf_url)\n",
+ "with open(pdf_path, \"wb\") as f:\n",
+ " f.write(resp.content)\n",
+ "\n",
+ "print(f\"Knowledgebase file path: {pdf_path}\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "metadata": {
+ "id": "YERFdXvBxLUa"
+ },
+ "outputs": [],
+ "source": [
+ "from veadk import Agent\n",
+ "from veadk.knowledgebase.knowledgebase import KnowledgeBase\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "knowledgebase = KnowledgeBase(backend=\"viking\") # 指定 viking 后端\n",
+ "\n",
+ "with open(pdf_path, \"rb\") as f:\n",
+ " knowledgebase.add(f, app_name=app_name) # 直接添加文档，无需手动切片\n",
+ "\n",
+ "agent = Agent(knowledgebase=knowledgebase)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "fl50010V1vl5"
+ },
+ "source": [
+ "由于初始使用 Viking DB 需要构建索引，因此需要等待 3-4 分钟。等待过后，执行如下代码检验："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 17,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "TjT0hjrK10hq",
+ "outputId": "60d8a546-89e7-4747-afb5-6be0db64c446"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "`Multi-Head Attention` is a key component in the Transformer architecture, proposed in the paper *\"Attention Is All You Need\"* (Vaswani et al., 2017). It extends the standard attention mechanism by allowing the model to **simultaneously learn different types of attention patterns** from multiple \"heads\" (parallel attention functions), thereby capturing richer contextual relationships in the input data.\n",
+ "\n",
+ "\n",
+ "### **Core Idea** \n",
+ "Instead of computing a single attention function over the input, multi-head attention splits the query, key, and value vectors into multiple smaller subspaces (heads), computes scaled dot-product attention independently for each subspace, and then concatenates the results. This enables the model to focus on **different positional or semantic relationships** (e.g., local dependencies, long-range dependencies, syntactic vs. semantic cues) in parallel.\n",
+ "\n",
+ "\n",
+ "### **Mathematical Formulation** \n",
+ "Given queries \\( Q \\), keys \\( K \\), and values \\( V \\): \n",
+ "1. **Linear Projections**: Project \\( Q \\), \\( K \\), \\( V \\) into \\( h \\) heads using learnable weight matrices \\( W_Q^i \\), \\( W_K^i \\), \\( W_V^i \\) for head \\( i \\): \n",
+ " \\[\n",
+ " Q_i = Q W_Q^i, \\quad K_i = K W_K^i, \\quad V_i = V W_V^i\n",
+ " \\] \n",
+ " where \\( Q_i, K_i \\in \\mathbb{R}^{n \\times d_k} \\), \\( V_i \\in \\mathbb{R}^{n \\times d_v} \\), and \\( d_k = d_{\\text{model}}/h \\), \\( d_v = d_{\\text{model}}/h \\) (subspace dimensions per head). \n",
+ "\n",
+ "2. **Scaled Dot-Product Attention per Head**: For each head \\( i \\), compute attention scores: \n",
+ " \\[\n",
+ " \\text{Attention}(Q_i, K_i, V_i) = \\text{softmax}\\left( \\frac{Q_i K_i^T}{\\sqrt{d_k}} \\right) V_i\n",
+ " \\] \n",
+ " The scaling factor \\( \\sqrt{d_k} \\) prevents gradient vanishing due to large dot-product values. \n",
+ "\n",
+ "3. **Concatenation and Final Projection**: Concatenate outputs from all \\( h \\) heads and project to the original dimension \\( d_{\\text{model}} \\): \n",
+ " \\[\n",
+ " \\text{MultiHead}(Q, K, V) = \\left[ \\text{head}_1; \\text{head}_2; \\dots; \\text{head}_h \\right] W_O\n",
+ " \\] \n",
+ " where \\( W_O \\in \\mathbb{R}^{h d_v \\times d_{\\text{model}}} \\) is a learnable projection matrix. \n",
+ "\n",
+ "\n",
+ "### **Key Advantages** \n",
+ "- **Diversity of Attention Patterns**: Each head can specialize in different relationships (e.g., one head focuses on adjacent words, another on distant thematic connections). \n",
+ "- **Parallelization**: Computations across heads are independent, enabling efficient training/inference on GPUs. \n",
+ "- **Improved Expressiveness**: Combines multiple \"views\" of the input, enhancing the model’s ability to model complex dependencies (critical for tasks like machine translation, text summarization, and GPT-style language modeling). \n",
+ "\n",
+ "\n",
+ "### **Visual Intuition** \n",
+ "Imagine analyzing a sentence with multiple \"experts\" (heads): one expert checks grammar, another identifies entity relationships, and a third tracks discourse flow. Multi-head attention aggregates their insights to form a holistic understanding.\n",
+ "\n",
+ "\n",
+ "In summary, multi-head attention is foundational to the Transformer’s success, enabling it to outperform RNN/LSTM-based models on sequence modeling tasks by efficiently capturing both local and global context.\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Runner\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=ShortTermMemory(),\n",
+ " app_name=app_name,\n",
+ " user_id=user_id,\n",
+ ")\n",
+ "\n",
+ "response = await runner.run(messages=\"What is `Multi-Head Attention`?\", session_id=session_id)\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "Wg8lAqX1zZHp"
+ },
+ "source": [
+ "### 多 Agent 协同\n",
+ "\n",
+ "你可以通过设置`sub_agents`字段来进行多 Agent 之间的本地协同。"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "mJm99M-AzwjV",
+ "outputId": "734ceed7-0d51-4357-892f-05da3e4821f5"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "```python\n",
+ "# 作者：python-coder\n",
+ "def quick_sort(arr):\n",
+ " \"\"\"\n",
+ " 使用快速排序算法对列表进行排序\n",
+ " \n",
+ " 参数:\n",
+ " arr: 需要排序的列表\n",
+ " \n",
+ " 返回:\n",
+ " 排序后的列表\n",
+ " \"\"\"\n",
+ " if len(arr) <= 1:\n",
+ " return arr\n",
+ " \n",
+ " # 选择基准元素（这里选择中间元素）\n",
+ " pivot = arr[len(arr) // 2]\n",
+ " \n",
+ " # 分区：小于基准、等于基准、大于基准\n",
+ " left = [x for x in arr if x < pivot]\n",
+ " middle = [x for x in arr if x == pivot]\n",
+ " right = [x for x in arr if x > pivot]\n",
+ " \n",
+ " # 递归排序并合并结果\n",
+ " return quick_sort(left) + middle + quick_sort(right)\n",
+ "\n",
+ "# 测试示例\n",
+ "if __name__ == \"__main__\":\n",
+ " test_arr = [3, 6, 8, 10, 1, 2, 1]\n",
+ " print(\"排序前:\", test_arr)\n",
+ " sorted_arr = quick_sort(test_arr)\n",
+ " print(\"排序后:\", sorted_arr)\n",
+ "```\n",
+ "\n",
+ "这段代码实现了快速排序算法，具有以下特点：\n",
+ "1. 采用递归实现，代码简洁易懂\n",
+ "2. 选择中间元素作为基准，避免了极端情况下的性能退化\n",
+ "3. 使用列表推导式进行分区操作，代码更简洁\n",
+ "4. 处理了重复元素的情况（通过单独的middle列表）\n",
+ "5. 包含完整的文档字符串和测试示例\n",
+ "\n",
+ "算法时间复杂度平均为O(n log n)，最坏情况下为O(n²)，空间复杂度为O(n)。如果需要原地排序版本（空间复杂度O(log n)），可以实现更复杂的指针交换分区方式。\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "short_term_memory = ShortTermMemory()\n",
+ "\n",
+ "# sub agents\n",
+ "python_coding_agent = Agent(\n",
+ " name=\"python_coder\",\n",
+ " description=\"擅长使用 Python 编程语言来解决问题。\",\n",
+ " instruction=\"\"\"使用 Python 语言来解决问题。\n",
+ " 注意，你生成的代码第一行需要有注释，标明作者是`python-coder`。\"\"\"\n",
+ ")\n",
+ "\n",
+ "java_coding_agent = Agent(\n",
+ " name=\"java_coder\",\n",
+ " description=\"擅长使用 Java 编程语言来解决问题。\",\n",
+ " instruction=\"\"\"使用 Java 语言来解决问题。\n",
+ " 注意，你生成的代码第一行需要有注释，标明作者是`java-coder`。\"\"\"\n",
+ ")\n",
+ "\n",
+ "# root agent\n",
+ "coding_agent = Agent(\n",
+ " name=\"coding_agent\",\n",
+ " description=\"可以调用适合的智能体来解决用户问题。\",\n",
+ " instruction=\"调用适合的智能体来解决用户问题。\",\n",
+ " sub_agents=[python_coding_agent, java_coding_agent]\n",
+ ")\n",
+ "\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=coding_agent,\n",
+ " short_term_memory=ShortTermMemory(),\n",
+ " app_name=app_name,\n",
+ " user_id=user_id,\n",
+ ")\n",
+ "\n",
+ "response = await runner.run(\n",
+ " messages=\"使用 Python 帮我写一段快速排序的代码。\",\n",
+ " session_id=session_id\n",
+ " )\n",
+ "\n",
+ "print(response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "W9ZHmdsabfna"
+ },
+ "source": [
+ "## 可观测性"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "AfY3t76YjY1I"
+ },
+ "source": [
+ "### 本地观测"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "l3JJvH9y2Tgc"
+ },
+ "source": [
+ "可以通过初始化 OpentelemetryTracer 来将 Agent 的调用栈存储为本地文件："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "L3VnmdQd2e9g",
+ "outputId": "1a1332cb-2a41-45a3-b874-b16a778a85b1"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Tracing file path: /tmp/veadk_global_tracer_veadk-playground-user_veadk-playground-session_b204302b2d0e24b6e26ca914a5fef478.json\n",
+ "Tracing file content:\n",
+ "[{'name': 'execute_tool get_city_weather', 'span_id': 179319007772593823, 'trace_id': 236624329413565051863190183785302783096, 'start_time': 1755172431614674977, 'end_time': 1755172431617289457, 'attributes': {'session.id': 'veadk-playground-session', 'user.id': 'veadk-playground-user', 'agent.name': 'veAgent', 'app.name': 'veadk-playground-app', 'gen_ai.system': 'gcp.vertex.agent', 'gen_ai.operation.name': 'execute_tool', 'gen_ai.tool.name': 'get_city_weather', 'gen_ai.tool.description': 'Retrieves the weather information of a given city. the args must in English', 'gen_ai.tool.call.id': 'call_2e7gig0mp86rzc1ffwf5ftdc', 'gcp.vertex.agent.tool_call_args': '{\"city\": \"Beijing\"}', 'gcp.vertex.agent.event_id': '04616e67-6881-43d0-8200-09c7c069be06', 'gcp.vertex.agent.tool_response': '{\"result\": \"Sunny, 25°C\"}', 'gcp.vertex.agent.llm_request': '{}', 'gcp.vertex.agent.llm_response': '{}', 'tool.name': 'get_city_weather', 'tool.description': 'Retrieves the weather information of a given city. the args must in English', 'tool.parameters': '{\"city\": \"Beijing\"}', 'input.value': '{\"city\": \"Beijing\"}', 'input.mime_type': 'application/json', 'output.value': '{\"id\":\"call_2e7gig0mp86rzc1ffwf5ftdc\",\"name\":\"get_city_weather\",\"response\":{\"result\":\"Sunny, 25°C\"}}', 'output.mime_type': 'application/json', 'openinference.span.kind': 'TOOL'}, 'parent_span_id': 2812243689223977179}, {'name': 'call_llm', 'span_id': 2812243689223977179, 'trace_id': 236624329413565051863190183785302783096, 'start_time': 1755172421810196265, 'end_time': 1755172431617490556, 'attributes': {'session.id': 'veadk-playground-session', 'user.id': 'veadk-playground-user', 'gen_ai.system': 'gcp.vertex.agent', 'gen_ai.request.model': 'openai/doubao-seed-1-6-250615', 'gcp.vertex.agent.invocation_id': 'e-cf95076e-458e-4c96-bce8-77b9c80dc8d6', 'gcp.vertex.agent.session_id': 'veadk-playground-session', 'gcp.vertex.agent.event_id': '3899014e-49a2-4ff5-b9ac-9b95c7c03cc0', 'gcp.vertex.agent.llm_request': '{\"model\": \"openai/doubao-seed-1-6-250615\", \"config\": {\"system_instruction\": \"You an AI agent created by the VeADK team.\\\\n\\\\nYou excel at the following tasks:\\\\n1. Data science\\\\n- Information gathering and fact-checking\\\\n- Data processing and analysis\\\\n2. Documentation\\\\n- Writing multi-chapter articles and in-depth research reports\\\\n3. Coding & Programming\\\\n- Creating websites, applications, and tools\\\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\\\n- If necessary, using programming to solve various problems beyond development\\\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\\\n\\\\n\\\\nYou are an agent. Your internal name is \\\\\"veAgent\\\\\".\\\\n\\\\n The description about you is \\\\\"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\\\\\"\", \"tools\": [{\"function_declarations\": [{\"description\": \"Retrieves the weather information of a given city. the args must in English\", \"name\": \"get_city_weather\", \"parameters\": {\"properties\": {\"city\": {\"type\": \"STRING\"}}, \"required\": [\"city\"], \"type\": \"OBJECT\"}}]}], \"labels\": {\"adk_agent_name\": \"veAgent\"}}, \"contents\": [{\"parts\": [{\"text\": \"北京的天气怎么样？\"}], \"role\": \"user\"}]}', 'gcp.vertex.agent.llm_response': '{\"content\":{\"parts\":[{\"function_call\":{\"id\":\"call_2e7gig0mp86rzc1ffwf5ftdc\",\"args\":{\"city\":\"Beijing\"},\"name\":\"get_city_weather\"}}],\"role\":\"model\"},\"partial\":false,\"usage_metadata\":{\"candidates_token_count\":361,\"prompt_token_count\":618,\"total_token_count\":979}}', 'gen_ai.usage.input_tokens': 618, 'gen_ai.usage.output_tokens': 979, 'llm.provider': 'google', 'input.value': '{\"model\": \"openai/doubao-seed-1-6-250615\", \"config\": {\"system_instruction\": \"You an AI agent created by the VeADK team.\\\\n\\\\nYou excel at the following tasks:\\\\n1. Data science\\\\n- Information gathering and fact-checking\\\\n- Data processing and analysis\\\\n2. Documentation\\\\n- Writing multi-chapter articles and in-depth research reports\\\\n3. Coding & Programming\\\\n- Creating websites, applications, and tools\\\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\\\n- If necessary, using programming to solve various problems beyond development\\\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\\\n\\\\n\\\\nYou are an agent. Your internal name is \\\\\"veAgent\\\\\".\\\\n\\\\n The description about you is \\\\\"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\\\\\"\", \"tools\": [{\"function_declarations\": [{\"description\": \"Retrieves the weather information of a given city. the args must in English\", \"name\": \"get_city_weather\", \"parameters\": {\"properties\": {\"city\": {\"type\": \"STRING\"}}, \"required\": [\"city\"], \"type\": \"OBJECT\"}}]}], \"labels\": {\"adk_agent_name\": \"veAgent\"}}, \"contents\": [{\"parts\": [{\"text\": \"北京的天气怎么样？\"}], \"role\": \"user\"}]}', 'input.mime_type': 'application/json', 'llm.tools.0.tool.json_schema': '{\"description\":\"Retrieves the weather information of a given city. the args must in English\",\"name\":\"get_city_weather\",\"parameters\":{\"properties\":{\"city\":{\"type\":\"STRING\"}},\"required\":[\"city\"],\"type\":\"OBJECT\"}}', 'llm.model_name': 'openai/doubao-seed-1-6-250615', 'llm.invocation_parameters': '{\"system_instruction\":\"You an AI agent created by the VeADK team.\\\\n\\\\nYou excel at the following tasks:\\\\n1. Data science\\\\n- Information gathering and fact-checking\\\\n- Data processing and analysis\\\\n2. Documentation\\\\n- Writing multi-chapter articles and in-depth research reports\\\\n3. Coding & Programming\\\\n- Creating websites, applications, and tools\\\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\\\n- If necessary, using programming to solve various problems beyond development\\\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\\\n\\\\n\\\\nYou are an agent. Your internal name is \\\\\"veAgent\\\\\".\\\\n\\\\n The description about you is \\\\\"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\\\\\"\",\"tools\":[{\"function_declarations\":[{\"description\":\"Retrieves the weather information of a given city. the args must in English\",\"name\":\"get_city_weather\",\"parameters\":{\"properties\":{\"city\":{\"type\":\"STRING\"}},\"required\":[\"city\"],\"type\":\"OBJECT\"}}]}],\"labels\":{\"adk_agent_name\":\"veAgent\"}}', 'llm.input_messages.0.message.role': 'system', 'llm.input_messages.0.message.content': 'You an AI agent created by the VeADK team.\\n\\nYou excel at the following tasks:\\n1. Data science\\n- Information gathering and fact-checking\\n- Data processing and analysis\\n2. Documentation\\n- Writing multi-chapter articles and in-depth research reports\\n3. Coding & Programming\\n- Creating websites, applications, and tools\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\n- If necessary, using programming to solve various problems beyond development\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\n\\n\\nYou are an agent. Your internal name is \"veAgent\".\\n\\n The description about you is \"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\"', 'llm.input_messages.1.message.role': 'user', 'llm.input_messages.1.message.contents.0.message_content.text': '北京的天气怎么样？', 'llm.input_messages.1.message.contents.0.message_content.type': 'text', 'output.value': '{\"content\":{\"parts\":[{\"function_call\":{\"id\":\"call_2e7gig0mp86rzc1ffwf5ftdc\",\"args\":{\"city\":\"Beijing\"},\"name\":\"get_city_weather\"}}],\"role\":\"model\"},\"partial\":false,\"usage_metadata\":{\"candidates_token_count\":361,\"prompt_token_count\":618,\"total_token_count\":979}}', 'output.mime_type': 'application/json', 'llm.token_count.total': 979, 'llm.token_count.prompt': 618, 'llm.token_count.completion': 361, 'llm.output_messages.0.message.role': 'model', 'llm.output_messages.0.message.tool_calls.0.tool_call.id': 'call_2e7gig0mp86rzc1ffwf5ftdc', 'llm.output_messages.0.message.tool_calls.0.tool_call.function.name': 'get_city_weather', 'llm.output_messages.0.message.tool_calls.0.tool_call.function.arguments': '{\"city\": \"Beijing\"}', 'agent.name': 'veAgent', 'app.name': 'veadk-playground-app', 'gen_ai.prompt.0.role': 'user', 'gen_ai.prompt.0.content': '[{\"text\": \"\\\\u5317\\\\u4eac\\\\u7684\\\\u5929\\\\u6c14\\\\u600e\\\\u4e48\\\\u6837\\\\uff1f\"}]', 'gen_ai.completion.0.role': 'model', 'gen_ai.completion.0.content': '[{\"function_call\": {\"id\": \"call_2e7gig0mp86rzc1ffwf5ftdc\", \"args\": {\"city\": \"Beijing\"}, \"name\": \"get_city_weather\"}}]', 'gen_ai.usage.prompt_tokens': 618, 'gen_ai.usage.completion_tokens': 361, 'gen_ai.usage.total_tokens': 979, 'gen_ai.usage.cache_read_input_tokens': 0, 'gen_ai.usage.cache_create_input_tokens': 0, 'openinference.span.kind': 'LLM'}, 'parent_span_id': 10693540128041292337}, {'name': 'call_llm', 'span_id': 11991268925671254201, 'trace_id': 236624329413565051863190183785302783096, 'start_time': 1755172431630256802, 'end_time': 1755172440854715605, 'attributes': {'session.id': 'veadk-playground-session', 'user.id': 'veadk-playground-user', 'gen_ai.system': 'gcp.vertex.agent', 'gen_ai.request.model': 'openai/doubao-seed-1-6-250615', 'gcp.vertex.agent.invocation_id': 'e-cf95076e-458e-4c96-bce8-77b9c80dc8d6', 'gcp.vertex.agent.session_id': 'veadk-playground-session', 'gcp.vertex.agent.event_id': '9c464404-92a5-4c52-b616-7e324e33e9fe', 'gcp.vertex.agent.llm_request': '{\"model\": \"openai/doubao-seed-1-6-250615\", \"config\": {\"system_instruction\": \"You an AI agent created by the VeADK team.\\\\n\\\\nYou excel at the following tasks:\\\\n1. Data science\\\\n- Information gathering and fact-checking\\\\n- Data processing and analysis\\\\n2. Documentation\\\\n- Writing multi-chapter articles and in-depth research reports\\\\n3. Coding & Programming\\\\n- Creating websites, applications, and tools\\\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\\\n- If necessary, using programming to solve various problems beyond development\\\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\\\n\\\\n\\\\nYou are an agent. Your internal name is \\\\\"veAgent\\\\\".\\\\n\\\\n The description about you is \\\\\"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\\\\\"\", \"tools\": [{\"function_declarations\": [{\"description\": \"Retrieves the weather information of a given city. the args must in English\", \"name\": \"get_city_weather\", \"parameters\": {\"properties\": {\"city\": {\"type\": \"STRING\"}}, \"required\": [\"city\"], \"type\": \"OBJECT\"}}]}], \"labels\": {\"adk_agent_name\": \"veAgent\"}}, \"contents\": [{\"parts\": [{\"text\": \"北京的天气怎么样？\"}], \"role\": \"user\"}, {\"parts\": [{\"function_call\": {\"id\": \"call_2e7gig0mp86rzc1ffwf5ftdc\", \"args\": {\"city\": \"Beijing\"}, \"name\": \"get_city_weather\"}}], \"role\": \"model\"}, {\"parts\": [{\"function_response\": {\"id\": \"call_2e7gig0mp86rzc1ffwf5ftdc\", \"name\": \"get_city_weather\", \"response\": {\"result\": \"Sunny, 25°C\"}}}], \"role\": \"user\"}]}', 'gcp.vertex.agent.llm_response': '{\"content\":{\"parts\":[{\"text\":\"北京当前天气晴朗，气温25°C。\"}],\"role\":\"model\"},\"partial\":false,\"usage_metadata\":{\"candidates_token_count\":245,\"prompt_token_count\":678,\"total_token_count\":923}}', 'gen_ai.usage.input_tokens': 678, 'gen_ai.usage.output_tokens': 923, 'llm.provider': 'google', 'input.value': '{\"model\": \"openai/doubao-seed-1-6-250615\", \"config\": {\"system_instruction\": \"You an AI agent created by the VeADK team.\\\\n\\\\nYou excel at the following tasks:\\\\n1. Data science\\\\n- Information gathering and fact-checking\\\\n- Data processing and analysis\\\\n2. Documentation\\\\n- Writing multi-chapter articles and in-depth research reports\\\\n3. Coding & Programming\\\\n- Creating websites, applications, and tools\\\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\\\n- If necessary, using programming to solve various problems beyond development\\\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\\\n\\\\n\\\\nYou are an agent. Your internal name is \\\\\"veAgent\\\\\".\\\\n\\\\n The description about you is \\\\\"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\\\\\"\", \"tools\": [{\"function_declarations\": [{\"description\": \"Retrieves the weather information of a given city. the args must in English\", \"name\": \"get_city_weather\", \"parameters\": {\"properties\": {\"city\": {\"type\": \"STRING\"}}, \"required\": [\"city\"], \"type\": \"OBJECT\"}}]}], \"labels\": {\"adk_agent_name\": \"veAgent\"}}, \"contents\": [{\"parts\": [{\"text\": \"北京的天气怎么样？\"}], \"role\": \"user\"}, {\"parts\": [{\"function_call\": {\"id\": \"call_2e7gig0mp86rzc1ffwf5ftdc\", \"args\": {\"city\": \"Beijing\"}, \"name\": \"get_city_weather\"}}], \"role\": \"model\"}, {\"parts\": [{\"function_response\": {\"id\": \"call_2e7gig0mp86rzc1ffwf5ftdc\", \"name\": \"get_city_weather\", \"response\": {\"result\": \"Sunny, 25°C\"}}}], \"role\": \"user\"}]}', 'input.mime_type': 'application/json', 'llm.tools.0.tool.json_schema': '{\"description\":\"Retrieves the weather information of a given city. the args must in English\",\"name\":\"get_city_weather\",\"parameters\":{\"properties\":{\"city\":{\"type\":\"STRING\"}},\"required\":[\"city\"],\"type\":\"OBJECT\"}}', 'llm.model_name': 'openai/doubao-seed-1-6-250615', 'llm.invocation_parameters': '{\"system_instruction\":\"You an AI agent created by the VeADK team.\\\\n\\\\nYou excel at the following tasks:\\\\n1. Data science\\\\n- Information gathering and fact-checking\\\\n- Data processing and analysis\\\\n2. Documentation\\\\n- Writing multi-chapter articles and in-depth research reports\\\\n3. Coding & Programming\\\\n- Creating websites, applications, and tools\\\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\\\n- If necessary, using programming to solve various problems beyond development\\\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\\\n\\\\n\\\\nYou are an agent. Your internal name is \\\\\"veAgent\\\\\".\\\\n\\\\n The description about you is \\\\\"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\\\\\"\",\"tools\":[{\"function_declarations\":[{\"description\":\"Retrieves the weather information of a given city. the args must in English\",\"name\":\"get_city_weather\",\"parameters\":{\"properties\":{\"city\":{\"type\":\"STRING\"}},\"required\":[\"city\"],\"type\":\"OBJECT\"}}]}],\"labels\":{\"adk_agent_name\":\"veAgent\"}}', 'llm.input_messages.0.message.role': 'system', 'llm.input_messages.0.message.content': 'You an AI agent created by the VeADK team.\\n\\nYou excel at the following tasks:\\n1. Data science\\n- Information gathering and fact-checking\\n- Data processing and analysis\\n2. Documentation\\n- Writing multi-chapter articles and in-depth research reports\\n3. Coding & Programming\\n- Creating websites, applications, and tools\\n- Solve problems and bugs in code (e.g., Python, JavaScript, SQL, ...)\\n- If necessary, using programming to solve various problems beyond development\\n4. If user gives you tools, finish various tasks that can be accomplished using tools and available resources\\n\\n\\nYou are an agent. Your internal name is \"veAgent\".\\n\\n The description about you is \"An AI agent developed by the VeADK team, specialized in data science, documentation, and software development.\"', 'llm.input_messages.1.message.role': 'user', 'llm.input_messages.1.message.contents.0.message_content.text': '北京的天气怎么样？', 'llm.input_messages.1.message.contents.0.message_content.type': 'text', 'llm.input_messages.2.message.role': 'model', 'llm.input_messages.2.message.tool_calls.0.tool_call.id': 'call_2e7gig0mp86rzc1ffwf5ftdc', 'llm.input_messages.2.message.tool_calls.0.tool_call.function.name': 'get_city_weather', 'llm.input_messages.2.message.tool_calls.0.tool_call.function.arguments': '{\"city\": \"Beijing\"}', 'llm.input_messages.3.message.role': 'tool', 'llm.input_messages.3.message.name': 'get_city_weather', 'llm.input_messages.3.message.content': '{\"result\": \"Sunny, 25°C\"}', 'output.value': '{\"content\":{\"parts\":[{\"text\":\"北京当前天气晴朗，气温25°C。\"}],\"role\":\"model\"},\"partial\":false,\"usage_metadata\":{\"candidates_token_count\":245,\"prompt_token_count\":678,\"total_token_count\":923}}', 'output.mime_type': 'application/json', 'llm.token_count.total': 923, 'llm.token_count.prompt': 678, 'llm.token_count.completion': 245, 'llm.output_messages.0.message.role': 'model', 'llm.output_messages.0.message.contents.0.message_content.text': '北京当前天气晴朗，气温25°C。', 'llm.output_messages.0.message.contents.0.message_content.type': 'text', 'agent.name': 'veAgent', 'app.name': 'veadk-playground-app', 'gen_ai.prompt.0.role': 'user', 'gen_ai.prompt.0.content': '[{\"text\": \"\\\\u5317\\\\u4eac\\\\u7684\\\\u5929\\\\u6c14\\\\u600e\\\\u4e48\\\\u6837\\\\uff1f\"}]', 'gen_ai.completion.0.role': 'model', 'gen_ai.completion.0.content': '[{\"text\": \"\\\\u5317\\\\u4eac\\\\u5f53\\\\u524d\\\\u5929\\\\u6c14\\\\u6674\\\\u6717\\\\uff0c\\\\u6c14\\\\u6e2925\\\\u00b0C\\\\u3002\"}]', 'gen_ai.usage.prompt_tokens': 678, 'gen_ai.usage.completion_tokens': 245, 'gen_ai.usage.total_tokens': 923, 'gen_ai.usage.cache_read_input_tokens': 0, 'gen_ai.usage.cache_create_input_tokens': 0, 'openinference.span.kind': 'LLM'}, 'parent_span_id': 10693540128041292337}, {'name': 'agent_run [veAgent]', 'span_id': 10693540128041292337, 'trace_id': 236624329413565051863190183785302783096, 'start_time': 1755172421809227259, 'end_time': 1755172440854946446, 'attributes': {'session.id': 'veadk-playground-session', 'user.id': 'veadk-playground-user', 'agent.name': 'veAgent', 'app.name': 'veadk-playground-app', 'gen_ai.system': 'veadk', 'gen_ai.request.model': 'openai/doubao-seed-1-6-250615', 'gen_ai.response.model': 'openai/doubao-seed-1-6-250615', 'gen_ai.request.type': 'completion', 'output.value': '{\"content\":{\"parts\":[{\"text\":\"北京当前天气晴朗，气温25°C。\"}],\"role\":\"model\"},\"partial\":false,\"usage_metadata\":{\"candidates_token_count\":245,\"prompt_token_count\":678,\"total_token_count\":923},\"invocation_id\":\"e-cf95076e-458e-4c96-bce8-77b9c80dc8d6\",\"author\":\"veAgent\",\"actions\":{\"state_delta\":{},\"artifact_delta\":{},\"requested_auth_configs\":{}},\"id\":\"9c464404-92a5-4c52-b616-7e324e33e9fe\",\"timestamp\":1755172431.618551}', 'output.mime_type': 'application/json', 'openinference.span.kind': 'AGENT'}, 'parent_span_id': 4139241635178039544}, {'name': 'invocation [veadk-playground-app]', 'span_id': 4139241635178039544, 'trace_id': 236624329413565051863190183785302783096, 'start_time': 1755172421808738619, 'end_time': 1755172440855020008, 'attributes': {'input.value': '{\"user_id\": \"veadk-playground-user\", \"session_id\": \"veadk-playground-session\", \"new_message\": {\"parts\": [{\"text\": \"北京的天气怎么样？\"}], \"role\": \"user\"}, \"state_delta\": null, \"run_config\": {\"save_input_blobs_as_artifacts\": false, \"support_cfc\": false, \"streaming_mode\": \"StreamingMode.NONE\", \"max_llm_calls\": 500}}', 'input.mime_type': 'application/json', 'user.id': 'veadk-playground-user', 'session.id': 'veadk-playground-session', 'output.value': '{\"content\":{\"parts\":[{\"text\":\"北京当前天气晴朗，气温25°C。\"}],\"role\":\"model\"},\"partial\":false,\"usage_metadata\":{\"candidates_token_count\":245,\"prompt_token_count\":678,\"total_token_count\":923},\"invocation_id\":\"e-cf95076e-458e-4c96-bce8-77b9c80dc8d6\",\"author\":\"veAgent\",\"actions\":{\"state_delta\":{},\"artifact_delta\":{},\"requested_auth_configs\":{}},\"id\":\"9c464404-92a5-4c52-b616-7e324e33e9fe\",\"timestamp\":1755172431.618551}', 'output.mime_type': 'application/json', 'openinference.span.kind': 'CHAIN'}, 'parent_span_id': None}]\n"
+ ]
+ }
+ ],
+ "source": [
+ "import json\n",
+ "\n",
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "from veadk.tools.demo_tools import get_city_weather\n",
+ "from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "tracer = OpentelemetryTracer()\n",
+ "\n",
+ "agent = Agent(tools=[get_city_weather], tracers=[tracer]) # 创建一个配置 tracers 的 Agent\n",
+ "\n",
+ "short_term_memory = ShortTermMemory()\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "# 如果在 agent 中设置了tracer，runner将会自动尝试保存 tracing 文件至`/tmp`中\n",
+ "await runner.run(messages=\"北京的天气怎么样？\", session_id=session_id)\n",
+ "\n",
+ "print(f\"Tracing file path: {tracer._trace_file_path}\")\n",
+ "\n",
+ "with open(tracer._trace_file_path, \"r\") as f:\n",
+ " tracing_content = f.read()\n",
+ "\n",
+ "print(f\"Tracing file content:\\n{json.loads(tracing_content)}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "vX5HiB2O2kfr"
+ },
+ "source": [
+ "### 云端观测"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "9j9aqke52nCz"
+ },
+ "source": [
+ "需要设置上报器（exporter），VeADK 当前支持将 Tracing 数据上报至火山引擎 TLS、火山引擎 APMPlus 以及火山引擎 Coze Loop 平台。它们分别对应不同的上报器。"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "azFOHaFe3C5x"
+ },
+ "source": [
+ "初始化上报器之前需要进行环境变量设置："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 18,
+ "metadata": {
+ "id": "edfntQAt3OCR"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "# TLS 上报器环境变量\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT\"] = \"https://tls-cn-beijing.volces.com:4318/v1/traces\"\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_TLS_REGION\"] = \"cn-beijing\"\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME\"] = \"\"\n",
+ "\n",
+ "# APMPlus 上报器环境变量\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT\"] = \"http://apmplus-cn-beijing.volces.com:4317\"\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME\"] = \"\"\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY\"] = \"\"\n",
+ "\n",
+ "# Coze Loop 上报器环境变量\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT\"] = \"https://api.coze.cn/v1/loop/opentelemetry/v1/traces\"\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME\"] = \"\"\n",
+ "os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "5nWBgrme3OVm"
+ },
+ "source": [
+ "初始化上报器，并装配到 Agent 中："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 19,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "5N9B3j843RtG",
+ "outputId": "1ba8e2f3-1c55-4e0d-c2d5-99fbc6cc256e"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Tracing file path: /tmp/veadk_global_tracer_veadk_playground_user_veadk_playground_session_2a70673f5f428cab82e0c68266a19560.json\n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "from veadk.tools.demo_tools import get_city_weather\n",
+ "from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter\n",
+ "from veadk.tracing.telemetry.exporters.cozeloop_exporter import CozeloopExporter\n",
+ "from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter\n",
+ "from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "exporters = [CozeloopExporter(), APMPlusExporter(), TLSExporter()] # 初始化 tracing 上报器\n",
+ "tracer = OpentelemetryTracer(exporters=exporters)\n",
+ "\n",
+ "agent = Agent(tools=[get_city_weather], tracers=[tracer]) # 创建一个配置 tracers 的 Agent\n",
+ "\n",
+ "short_term_memory = ShortTermMemory()\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "await runner.run(messages=\"北京的天气怎么样？\", session_id=session_id)\n",
+ "\n",
+ "print(f\"Tracing file path: {tracer._trace_file_path}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "dTCATLtR3SQ8"
+ },
+ "source": [
+ "最后，在云端平台可查看 Tracing 数据：\n",
+ "\n",
+ "* Coze Loop 平台：https://www.coze.cn/loop\n",
+ " \n",
+ "\n",
+ "* APMPlus 平台：https://www.volcengine.com/product/apmplus\n",
+ " \n",
+ "\n",
+ "* TLS 平台：https://www.volcengine.com/product/tls\n",
+ "\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "RxwpPU7jbS5b"
+ },
+ "source": [
+ "## 评测"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "IMLeM5Dg3nMd"
+ },
+ "source": [
+ "### 运行时数据转换"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "x_YrYHfk3rm6"
+ },
+ "source": [
+ "可以通过 runtime recorder 将运行时的数据直接保存为 Google ADK 兼容的 Evaluation Set 文件（json 格式）："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "8GUxfrmr364F",
+ "outputId": "c5340de4-1e4c-4673-f060-85cb4622a7e8"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Evaluation file path: /tmp/veadk-playground-app/default.evalset.json\n",
+ "Evaluation file content\n",
+ "{'eval_set_id': 'default', 'name': 'default', 'description': None, 'eval_cases': [{'eval_id': 'veadk_eval_20250814115717', 'conversation': [{'invocation_id': 'e-55f9f9f1-0cd0-45d4-82e9-8d4805215e19', 'user_content': {'parts': [{'video_metadata': None, 'thought': None, 'inline_data': None, 'file_data': None, 'thought_signature': None, 'code_execution_result': None, 'executable_code': None, 'function_call': None, 'function_response': None, 'text': '北京的天气怎么样？'}], 'role': 'user'}, 'final_response': {'parts': [{'video_metadata': None, 'thought': None, 'inline_data': None, 'file_data': None, 'thought_signature': None, 'code_execution_result': None, 'executable_code': None, 'function_call': None, 'function_response': None, 'text': '北京当前天气晴朗，气温25°C。'}], 'role': None}, 'intermediate_data': {'tool_uses': [{'id': 'call_6wbw4k3urxyd4hy8cil83n9m', 'args': {'city': 'Beijing'}, 'name': 'get_city_weather'}], 'intermediate_responses': []}, 'creation_timestamp': 1755172617.382655}], 'session_input': {'app_name': 'veadk-playground-app', 'user_id': 'veadk-playground-user', 'state': {}}, 'creation_timestamp': 1755172637.0875094}, {'eval_id': 'veadk_eval_20250814120810', 'conversation': [{'invocation_id': 'e-e3c0988a-68df-48dc-bc50-8b5e1517af92', 'user_content': {'parts': [{'video_metadata': None, 'thought': None, 'inline_data': None, 'file_data': None, 'thought_signature': None, 'code_execution_result': None, 'executable_code': None, 'function_call': None, 'function_response': None, 'text': '北京的天气怎么样？'}], 'role': 'user'}, 'final_response': {'parts': [{'video_metadata': None, 'thought': None, 'inline_data': None, 'file_data': None, 'thought_signature': None, 'code_execution_result': None, 'executable_code': None, 'function_call': None, 'function_response': None, 'text': '北京当前天气晴朗，气温25°C。'}], 'role': None}, 'intermediate_data': {'tool_uses': [{'id': 'call_jegeujxjilkrbelqnhna61nh', 'args': {'city': 'Beijing'}, 'name': 'get_city_weather'}], 'intermediate_responses': []}, 'creation_timestamp': 1755173274.352123}], 'session_input': {'app_name': 'veadk-playground-app', 'user_id': 'veadk-playground-user', 'state': {}}, 'creation_timestamp': 1755173290.5239134}], 'creation_timestamp': 1755172637.0869107}\n"
+ ]
+ }
+ ],
+ "source": [
+ "import json\n",
+ "\n",
+ "from veadk import Agent, Runner\n",
+ "from veadk.memory.short_term_memory import ShortTermMemory\n",
+ "from veadk.tools.demo_tools import get_city_weather\n",
+ "\n",
+ "app_name = \"veadk_playground_app\"\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "agent = Agent(tools=[get_city_weather])\n",
+ "short_term_memory = ShortTermMemory()\n",
+ "\n",
+ "runner = Runner(\n",
+ " agent=agent,\n",
+ " short_term_memory=short_term_memory,\n",
+ " app_name=app_name,\n",
+ " user_id=user_id\n",
+ " )\n",
+ "\n",
+ "await runner.run(messages=\"北京的天气怎么样？\", session_id=session_id)\n",
+ "\n",
+ "# 调用 runner 中的`save_eval_set`来保存评测集文件到本地\n",
+ "eval_set_path = await runner.save_eval_set(session_id=session_id)\n",
+ "\n",
+ "print(f\"Evaluation file path: {eval_set_path}\")\n",
+ "\n",
+ "with open(eval_set_path, \"r\") as f:\n",
+ " data = json.load(f)\n",
+ "print(f\"Evaluation file content\\n{data}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "gndBGC7m37AA"
+ },
+ "source": [
+ "### 使用评测器进行评测"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "_zqy0RFdby1U"
+ },
+ "source": [
+ "在使用评测之前，需要安装评测相关的依赖："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "hMjgZmiibzPa"
+ },
+ "outputs": [],
+ "source": [
+ "%pip install veadk-python[eval] --quiet"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "EbxQUv5xAoKO"
+ },
+ "source": [
+ "评判模型的环境变量设置："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "W2uWLckfAyWc"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "os.environ[\"MODEL_JUDGE_API_BASE\"] = \"https://ark.cn-beijing.volces.com/api/v3/\"\n",
+ "os.environ[\"MODEL_JUDGE_NAME\"] = \"doubao-seed-1-6-250615\"\n",
+ "os.environ[\"MODEL_JUDGE_API_KEY\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "oHQBJSFD3_xp"
+ },
+ "source": [
+ "以 Deepval 为例："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/",
+ "height": 1000,
+ "referenced_widgets": [
+ "57d290d6262343758157423263a2b652",
+ "76f9bda5cc1049d3a4812292d524ed0f"
+ ]
+ },
+ "id": "ZFSoW4XV4C69",
+ "outputId": "8241750c-e683-479d-ea33-02e19e39bc84"
+ },
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "WARNING:opentelemetry.trace:Overriding of current TracerProvider is not allowed\n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ "✨ You're running DeepEval's latest Base Evaluation [GEval] Metric! (using None (Local Model), strict=False, \n",
+ "async_mode=True)...\n",
+ "
\n"
+ ],
+ "text/plain": [
+ "✨ You're running DeepEval's latest \u001b[38;2;106;0;255mBase Evaluation \u001b[0m\u001b[1;38;2;106;0;255m[\u001b[0m\u001b[38;2;106;0;255mGEval\u001b[0m\u001b[1;38;2;106;0;255m]\u001b[0m\u001b[38;2;106;0;255m Metric\u001b[0m! \u001b[1;38;2;55;65;81m(\u001b[0m\u001b[38;2;55;65;81musing \u001b[0m\u001b[3;38;2;55;65;81mNone\u001b[0m\u001b[38;2;55;65;81m \u001b[0m\u001b[1;38;2;55;65;81m(\u001b[0m\u001b[38;2;55;65;81mLocal Model\u001b[0m\u001b[1;38;2;55;65;81m)\u001b[0m\u001b[38;2;55;65;81m, \u001b[0m\u001b[38;2;55;65;81mstrict\u001b[0m\u001b[38;2;55;65;81m=\u001b[0m\u001b[3;38;2;55;65;81mFalse\u001b[0m\u001b[38;2;55;65;81m, \u001b[0m\n",
+ "\u001b[38;2;55;65;81masync_mode\u001b[0m\u001b[38;2;55;65;81m=\u001b[0m\u001b[3;38;2;55;65;81mTrue\u001b[0m\u001b[1;38;2;55;65;81m)\u001b[0m\u001b[38;2;55;65;81m...\u001b[0m\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/html": [
+ "✨ You're running DeepEval's latest Tool Correctness Metric! (using None, strict=False, async_mode=True)...\n",
+ "
\n"
+ ],
+ "text/plain": [
+ "✨ You're running DeepEval's latest \u001b[38;2;106;0;255mTool Correctness Metric\u001b[0m! \u001b[1;38;2;55;65;81m(\u001b[0m\u001b[38;2;55;65;81musing \u001b[0m\u001b[3;38;2;55;65;81mNone\u001b[0m\u001b[38;2;55;65;81m, \u001b[0m\u001b[38;2;55;65;81mstrict\u001b[0m\u001b[38;2;55;65;81m=\u001b[0m\u001b[3;38;2;55;65;81mFalse\u001b[0m\u001b[38;2;55;65;81m, \u001b[0m\u001b[38;2;55;65;81masync_mode\u001b[0m\u001b[38;2;55;65;81m=\u001b[0m\u001b[3;38;2;55;65;81mTrue\u001b[0m\u001b[1;38;2;55;65;81m)\u001b[0m\u001b[38;2;55;65;81m...\u001b[0m\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "application/vnd.jupyter.widget-view+json": {
+ "model_id": "57d290d6262343758157423263a2b652",
+ "version_major": 2,
+ "version_minor": 0
+ },
+ "text/plain": [
+ "Output()"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/html": [
+ "\n"
+ ],
+ "text/plain": []
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\n",
+ "======================================================================\n",
+ "\n",
+ "Metrics Summary\n",
+ "\n",
+ " - ✅ Base Evaluation [GEval] (score: 1.0, threshold: 0.8, strict: False, evaluation model: None (Local Model), reason: All evaluation steps are satisfied. The Actual Output ('北京当前天气晴朗，气温为25°C。'), Input ('北京的天气怎么样？'), and Expected Output ('北京当前天气晴朗，气温25°C。') are all human-readable (coherent, no garbled text). Both Actual and Expected Outputs are relevant to the Input, which asks about Beijing's weather., error: None)\n",
+ " - ✅ Tool Correctness (score: 1.0, threshold: 0.5, strict: False, evaluation model: None, reason: All expected tools ['get_city_weather'] were called (order not considered)., error: None)\n",
+ "\n",
+ "For test case:\n",
+ "\n",
+ " - input: 北京的天气怎么样？\n",
+ " - actual output: 北京当前天气晴朗，气温为25°C。\n",
+ " - expected output: 北京当前天气晴朗，气温25°C。\n",
+ " - context: ['actual_conversation_history: Empty', 'expect_conversation_history: Empty']\n",
+ " - retrieval context: None\n",
+ "\n",
+ "======================================================================\n",
+ "\n",
+ "Overall Metric Pass Rates\n",
+ "\n",
+ "Base Evaluation [GEval]: 100.00% pass rate\n",
+ "Tool Correctness: 100.00% pass rate\n",
+ "\n",
+ "======================================================================\n",
+ "\n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "✓ Evaluation completed 🎉! (time taken: 24.09s | token cost: 0.0 USD)\n",
+ "» Test Results (1 total tests):\n",
+ " » Pass Rate: 100.0% | Passed: 1 | Failed: 0\n",
+ "\n",
+ " ================================================================================ \n",
+ "\n",
+ "» What to share evals with your team, or a place for your test cases to live? ❤️ 🏡\n",
+ " » Run 'deepeval view' to analyze and save testing results on Confident AI.\n",
+ "\n",
+ "\n",
+ "
\n"
+ ],
+ "text/plain": [
+ "\n",
+ "\n",
+ "\u001b[38;2;5;245;141m✓\u001b[0m Evaluation completed 🎉! \u001b[1m(\u001b[0mtime taken: \u001b[1;36m24.\u001b[0m09s | token cost: \u001b[1;36m0.0\u001b[0m USD\u001b[1m)\u001b[0m\n",
+ "» Test Results \u001b[1m(\u001b[0m\u001b[1;36m1\u001b[0m total tests\u001b[1m)\u001b[0m:\n",
+ " » Pass Rate: \u001b[1;36m100.0\u001b[0m% | Passed: \u001b[1;32m1\u001b[0m | Failed: \u001b[1;31m0\u001b[0m\n",
+ "\n",
+ " ================================================================================ \n",
+ "\n",
+ "» What to share evals with your team, or a place for your test cases to live? ❤️ 🏡\n",
+ " » Run \u001b[1;32m'deepeval view'\u001b[0m to analyze and save testing results on \u001b[38;2;106;0;255mConfident AI\u001b[0m.\n",
+ "\n",
+ "\n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/plain": [
+ "EvaluationResult(test_results=[TestResult(name='test_case_0', success=True, metrics_data=[MetricData(name='Base Evaluation [GEval]', threshold=0.8, success=True, score=1.0, reason=\"All evaluation steps are satisfied. The Actual Output ('北京当前天气晴朗，气温为25°C。'), Input ('北京的天气怎么样？'), and Expected Output ('北京当前天气晴朗，气温25°C。') are all human-readable (coherent, no garbled text). Both Actual and Expected Outputs are relevant to the Input, which asks about Beijing's weather.\", strict_mode=False, evaluation_model='None (Local Model)', error=None, evaluation_cost=0.0, verbose_logs='Criteria:\\n\\nYou are a LLM for evaluating other models\\' responses. Note:\\n- The response maybe generated by some uncertainty tools (e.g., online-search, random number), you just need to consider whether the response is human-readable, rather than focus on the specific content. Because the specific content maybe different at different time.\\n \\n \\nEvaluation Steps:\\n[\\n \"Check if the Actual Output is human-readable (coherent, no garbled text).\",\\n \"Verify that the Input is a human-readable prompt/query.\",\\n \"Confirm the Expected Output is human-readable (specific content may vary).\",\\n \"Ensure both Actual and Expected Outputs are human-readable in relation to the Input.\"\\n] \\n \\nRubric:\\nNone \\n \\nScore: 1.0'), MetricData(name='Tool Correctness', threshold=0.5, success=True, score=1.0, reason=\"All expected tools ['get_city_weather'] were called (order not considered).\", strict_mode=False, evaluation_model=None, error=None, evaluation_cost=None, verbose_logs='Expected Tools:\\n[\\n ToolCall(\\n name=\"get_city_weather\",\\n input_parameters={\\n \"city\": \"Beijing\"\\n }\\n )\\n] \\n \\nTools Called:\\n[\\n ToolCall(\\n name=\"get_city_weather\",\\n input_parameters={\\n \"city\": \"Beijing\"\\n }\\n )\\n]')], conversational=False, multimodal=False, input='北京的天气怎么样？', actual_output='北京当前天气晴朗，气温为25°C。', expected_output='北京当前天气晴朗，气温25°C。', context=['actual_conversation_history: Empty', 'expect_conversation_history: Empty'], retrieval_context=None, additional_metadata={'latency': '22402.586698532104'})], confident_link=None)"
+ ]
+ },
+ "execution_count": 37,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "from deepeval.metrics import GEval, ToolCorrectnessMetric\n",
+ "from deepeval.test_case import LLMTestCaseParams\n",
+ "\n",
+ "from veadk import Agent\n",
+ "from veadk.tools.demo_tools import get_city_weather\n",
+ "from veadk.config import getenv\n",
+ "from veadk.evaluation.deepeval_evaluator import DeepevalEvaluator\n",
+ "from veadk.prompts.prompt_evaluator import eval_principle_prompt\n",
+ "\n",
+ "agent = Agent(tools=[get_city_weather])\n",
+ "\n",
+ "evaluator = DeepevalEvaluator(agent=agent,\n",
+ " judge_model_api_key=getenv(\"MODEL_JUDGE_API_KEY\"))\n",
+ "\n",
+ "judge_model = evaluator.judge_model # 如果你希望使用方舟作为 judge model，那么 evaluator 会帮你自动初始化\n",
+ "\n",
+ "metrics = [\n",
+ " GEval(\n",
+ " threshold=0.8,\n",
+ " name=\"Base Evaluation\",\n",
+ " criteria=eval_principle_prompt,\n",
+ " evaluation_params=[\n",
+ " LLMTestCaseParams.INPUT,\n",
+ " LLMTestCaseParams.ACTUAL_OUTPUT,\n",
+ " LLMTestCaseParams.EXPECTED_OUTPUT,\n",
+ " ],\n",
+ " model=judge_model, # 这里需要传入 judge model\n",
+ " ),\n",
+ " ToolCorrectnessMetric(\n",
+ " threshold=0.5\n",
+ " ),\n",
+ "]\n",
+ "\n",
+ "await evaluator.eval(eval_set_file_path=eval_set_path, metrics=metrics)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "JoEskSzcjV-T"
+ },
+ "source": [
+ "## Prompt 优化"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "AlE2IeVtknQK"
+ },
+ "source": [
+ "使用火山引擎 PromptPilot 来进行 Agent 的系统提示词（System Prompt）优化。"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "9Zi94vc0kshG"
+ },
+ "outputs": [],
+ "source": [
+ "# 安装火山引擎提供的依赖\n",
+ "%pip install agent-pilot-sdk>=0.0.9"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "5IjI4lrHSZcD"
+ },
+ "source": [
+ "设置 KEY 来访问服务："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "5yOKQ9KISdYb"
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "os.environ[\"AGENT_PILOT_API_KEY\"] = \"\""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "J2xkK82b4MAG"
+ },
+ "source": [
+ "定义一个简单的 Agent，并且让它携带天气查询的工具，体验 Prompt 优化前后的差异。"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "U1r9txhY4TRz"
+ },
+ "outputs": [],
+ "source": [
+ "from veadk import Agent\n",
+ "from veadk.tools.demo_tools import get_city_weather\n",
+ "\n",
+ "agent = Agent(instruction=\"你是一个智能体\", tools=[get_city_weather])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "VG4opU834T5g"
+ },
+ "source": [
+ "使用 Prompt Pilot 进行优化："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "zA-z9b_X4W9m",
+ "outputId": "a82d959f-12dd-47fe-f1d0-a2fa76c42f44"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Optimized prompt for agent veAgent:\n",
+ "# Role\n",
+ "你是veAgent，是由VeADK团队开发的AI智能体，专长于数据科学、文档编写和软件开发领域。\n",
+ "\n",
+ "# Task Requirements\n",
+ "## 基于你的角色和对话历史，合理推断并延续对话。需考虑以下方面：\n",
+ "- **对话风格**：语言表达应专业、准确、清晰，符合技术领域的交流风格，避免模糊或歧义的表述。\n",
+ "- **沟通目的**：围绕用户在数据科学、文档编写和软件开发方面的问题展开对话，提供专业的建议、解决方案或相关信息。不偏离用户的问题核心，确保对话的连贯性和有效性。\n",
+ "- **专业能力展现**：在涉及数据科学、文档编写和软件开发的专业知识时，提供准确、详细且有价值的内容。若用户需求涉及特定工具或技术，可结合自身专长进行解答。\n",
+ "\n",
+ "## 额外要求\n",
+ "- **简洁高效**：回答应简洁明了，避免冗长复杂的句子和不必要的修饰，确保信息能够高效传达。\n",
+ "- **专业态度**：始终保持专业的态度，不随意发表没有依据的观点。对于不熟悉的领域，坦诚告知用户，并提供可能的解决途径。 \n"
+ ]
+ }
+ ],
+ "source": [
+ "from veadk.cli.services.agentpilot.agentpilot import AgentPilot\n",
+ "\n",
+ "agent_pilot = AgentPilot(api_key=os.getenv(\"AGENT_PILOT_API_KEY\"))\n",
+ "\n",
+ "refined_prompt = agent_pilot.optimize(agents=[agent])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "3zPzrXMv3ToL"
+ },
+ "source": [
+ "## 云端部署"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "bejpQneN6XxA"
+ },
+ "source": [
+ "为体验部署相关功能，你需要安装依赖包："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "JZQPRAe96W7y"
+ },
+ "outputs": [],
+ "source": [
+ "%pip install veadk-python[cli] --quiet"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "WUFS6ZET3fsh"
+ },
+ "source": [
+ "### 部署到火山引擎 FaaS 平台"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "vaR4B8ff3j5_"
+ },
+ "source": [
+ "详见[部署上云](https://volcengine.github.io/veadk-python/deploy.html)。"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "M0x2xbyh3uRF"
+ },
+ "source": [
+ "### 端云协同"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "IbCOhiuB3zvH"
+ },
+ "source": [
+ "VeADK 提供了在本地直接调用/操作部署在火山引擎 FaaS 平台的 Agent 的便捷接口，方便你与云端 Agent 协作。"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "cQat873c4BY7"
+ },
+ "source": [
+ "**以 A2A 方式调用部署的 Agent**"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "Q2BxyDeL4hsc"
+ },
+ "outputs": [],
+ "source": [
+ "# 部署在 VeFaaS 上的应用名称（Application name）\n",
+ "vefaas_application_name = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "AncPEwMz4HDX"
+ },
+ "outputs": [],
+ "source": [
+ "from veadk.cloud.cloud_app import CloudApp\n",
+ "\n",
+ "# 设置会话属性\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "cloud_app = CloudApp(vefaas_application_name=vefaas_application_name)\n",
+ "\n",
+ "print(f\"VeFaaS 应用 ID: {cloud_app.vefaas_application_id}\")\n",
+ "\n",
+ "# 发送消息\n",
+ "response_message = await cloud_app.message_send(\n",
+ " message=\"你好，我是一名 Agent 开发者。\",\n",
+ " user_id=user_id,\n",
+ " session_id=session_id\n",
+ " )\n",
+ "\n",
+ "print(f\"返回的消息源: {cloud_app.vefaas_endpoint}\")\n",
+ "print(f\"返回的消息内容: {response_message.parts[0].root.text}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "7OFbdR2J4HhN"
+ },
+ "source": [
+ "**以 MCP 方式调用部署的Agent**"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "ztWHDL71PL2l"
+ },
+ "source": [
+ "使用此方式需安装 `fastmcp` 库："
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "9fOVlphPPMZt"
+ },
+ "outputs": [],
+ "source": [
+ "%pip install fastmcp --quiet"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "QjeJ5l034P7r"
+ },
+ "outputs": [],
+ "source": [
+ "# 部署在 VeFaaS 上的应用名称（Application name）\n",
+ "vefaas_application_name = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "SiszeafO6Iav"
+ },
+ "outputs": [],
+ "source": [
+ "from veadk.cloud.cloud_app import CloudApp\n",
+ "from fastmcp.client import Client\n",
+ "\n",
+ "# 设置会话属性\n",
+ "user_id = \"veadk_playground_user\"\n",
+ "session_id = \"veadk_playground_session\"\n",
+ "\n",
+ "cloud_app = CloudApp(vefaas_application_name=vefaas_application_name)\n",
+ "\n",
+ "endpoint = cloud_app._get_vefaas_endpoint()\n",
+ "print(f\"VeFaaS 应用 Endpoint: {endpoint}\")\n",
+ "\n",
+ "client = Client(f\"{endpoint}/mcp\")\n",
+ "\n",
+ "async with client:\n",
+ " # 列出所有工具\n",
+ " tools = await client.list_tools()\n",
+ " print(f\"云部署的 MCP 工具: {tools}\")\n",
+ "\n",
+ " # 通过 MCP 的方式调用云端 Agent\n",
+ " res = await client.call_tool(\n",
+ " \"run_agent\",\n",
+ " {\n",
+ " \"user_input\": \"你好，我是一名 Agent 开发者。\",\n",
+ " \"session_id\": session_id,\n",
+ " \"user_id\": user_id,\n",
+ " },\n",
+ " )\n",
+ " print(f\"返回的消息内容: {res}\")"
+ ]
+ }
+ ],
+ "metadata": {
+ "colab": {
+ "provenance": [],
+ "toc_visible": true
+ },
+ "kernelspec": {
+ "display_name": "veadk-python",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "name": "python",
+ "version": "3.10.18"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}