Skip to content

chore: update tutorial with tool links #254

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 27, 2025
Merged

chore: update tutorial with tool links #254

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
47e1495
chore: update tutorial with tool links
BhAem Oct 24, 2025
544d7f4
add viking url
BhAem Oct 25, 2025
135bf9e
add more links and explaination
BhAem Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 37 additions & 66 deletions veadk_tutorial.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,13 @@
"### 环境变量"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"这里以[方舟大模型平台](https://console.volcengine.com/ark/region:ark+cn-beijing/overview)为例，使用到的模型需要提前在方舟控制台进行[开通操作](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement)。"
]
},
{
"cell_type": "code",
"execution_count": null,
Expand All @@ -92,7 +99,7 @@
"source": [
"import os\n",
"\n",
"os.environ[\"MODEL_AGENT_NAME\"] = \"doubao-seed-1-6-250615\" # <-- 火山方舟大模型名称\n",
"os.environ[\"MODEL_AGENT_NAME\"] = \"doubao-seed-1-6-251015\" # <-- 火山方舟大模型名称\n",
"\n",
"os.environ[\"MODEL_AGENT_API_KEY\"] = \"\" # <-- 设置火山方舟的API KEY来访问模型\n",
"\n",
Expand All @@ -116,49 +123,7 @@
"source": [
"### 快速开始\n",
"\n",
"初始化Agent过程中，你可以不传入任何参数，VeADK 会自动读取环境变量。查看[完整的 Agent 参数](https://volcengine.github.io/veadk-python/agent/agent#%E9%80%89%E9%A1%B9)。"
]
},
{
"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—creating AI Agents is such an exciting and dynamic field. Whether you're building task-specific assistants, multi-modal agents, or complex autonomous systems, there’s always so much to explore, from architecture design to tool integration, decision-making logic, or user interaction optimization. \n",
"\n",
"Are you currently working on a specific Agent project? For example, is it focused on a niche domain (like data analysis, customer support, or coding assistance), or are you tackling broader challenges like long-term memory management, multi-agent collaboration, or reliable tool usage? If you’ve hit any roadblocks—whether technical (e.g., framework selection, API integration bugs) or conceptual (e.g., balancing autonomy vs. user control)—feel free to share details. I’d love to brainstorm solutions or offer insights based on my experience with data science, coding, and documentation! 😊\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`以实现多租户隔离。"
"初始化Agent过程中，你可以不传入任何参数，VeADK 会自动读取环境变量，点击查看[完整的 Agent 参数](https://volcengine.github.io/veadk-python/agent/agent#%E9%80%89%E9%A1%B9)。生产环境下**使用`Runner`来运行 Agent**，通过`app_name`、`user_id`以及`session_id`以实现多租户隔离。"
]
},
{
Expand Down Expand Up @@ -222,7 +187,7 @@
"id": "U3yLU8WndkTj"
},
"source": [
"初始化 Agent 时，你可以使用`tools`字段来挂载工具："
"初始化 Agent 时，你可以使用`tools`字段来挂载工具。VeADK 中集成了多个[内置工具](https://volcengine.github.io/veadk-python/tools/builtin-tools)，如下以一个查询天气的 demo 工具为例："
]
},
{
Expand Down Expand Up @@ -280,7 +245,7 @@
"id": "JDtvFNcAy9FK"
},
"source": [
"使用`web_search`工具："
"使用[`web_search`工具](https://www.volcengine.com/docs/85508/1650263)，使用前需提前开通[相应权限](https://www.volcengine.com/docs/85508/1544858) (简单起见，可以直接给用到的测试账号赋予[AdministratorAccess超管权限](https://console.volcengine.com/iam/policymanage/System/AdministratorAccess?tab=auth))，提前[创建并填写火山引擎的 AK 和 SK](https://www.volcengine.com/docs/6291/65568)："
]
},
{
Expand Down Expand Up @@ -355,7 +320,7 @@
"id": "IoTXmqz8zAvp"
},
"source": [
"尝试使用`VeSearch`工具："
"尝试使用[`VeSearch`工具](https://www.volcengine.com/docs/85508/1512748)，使用前需进行[工具创建](https://console.volcengine.com/ask-echo/my-agent)，并填写如下 `VeSearch`工具的 ENDPOINT (ID) 和 API KEY："
]
},
{
Expand Down Expand Up @@ -494,7 +459,8 @@
"name": "stdout",
"output_type": "stream",
"text": [
"Hello VeADK! It's great to meet you. As veAgent, the AI agent developed by the VeADK team, I’m here to assist with whatever you need—whether it’s data science tasks like information gathering or analysis, creating detailed documentation, coding (Python, JavaScript, SQL, etc.), solving development problems, or using tools to tackle various tasks. Just let me know how I can help today! 😊Of course! You introduced yourself as VeADK earlier. It's great to have you here—feel free to let me know what you need help with today, and I’ll do my best to assist! 😊\n"
"Hello VeADK! It's wonderful to meet you. I'm veAgent, the AI agent developed by the VeADK team. Whether you need help with data science tasks, documentation writing, coding and programming, or using tools to accomplish specific goals, feel free to let me know—I’m here to assist! 😊\n",
"Of course I remember! Your name is VeADK. It's nice to connect with you again—feel free to let me know what I can help with today! 😊\n"
]
}
],
Expand All @@ -516,7 +482,13 @@
")\n",
"\n",
"response = await runner.run(\n",
" messages=[\"我叫VeADK\", \"你还记得我叫什么吗？\"], session_id=session_id\n",
" messages=\"我叫VeADK\", session_id=session_id\n",
")\n",
"\n",
"print(response)\n",
"\n",
"response = await runner.run(\n",
" messages=\"你还记得我叫什么吗？\", session_id=session_id\n",
")\n",
"\n",
"print(response)"
Expand All @@ -533,7 +505,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"使用 MySQL 作为短期记忆的数据库后端："
"使用 [MySQL](https://www.volcengine.com/docs/6313) 作为短期记忆的数据库后端，使用前[创建 MySQL](https://www.volcengine.com/product/rds-mysql) 并填写如下信息："
]
},
{
Expand Down Expand Up @@ -631,7 +603,7 @@
"id": "hMrtrd2DxUar"
},
"source": [
"使用 OpenSearch 作为长期记忆的数据库后端："
"使用 [OpenSearch](https://www.volcengine.com/docs/6465/?lang=zh) 作为长期记忆的数据库后端，使用前[创建 OpenSearch](https://www.volcengine.com/product/es) 并填写如下信息："
]
},
{
Expand Down Expand Up @@ -726,7 +698,7 @@
"id": "aEFDAJdtiiz1"
},
"source": [
"使用 Viking Memory 作为长期记忆的后端："
"使用 [记忆库/Viking Memory](https://www.volcengine.com/docs/84313/1860687) 作为长期记忆的后端，使用前[创建 记忆库/Viking Memory](https://console.volcengine.com/vikingdb/region:vikingdb+cn-beijing/home?) 并填写如下信息："
]
},
{
Expand Down Expand Up @@ -856,7 +828,7 @@
"id": "8N01Na5az3iR"
},
"source": [
"使用 OpenSearch 作为知识库的后端："
"使用 [OpenSearch](https://www.volcengine.com/product/es) 作为知识库的后端："
]
},
{
Expand Down Expand Up @@ -972,7 +944,7 @@
"id": "V87HcIZXlijp"
},
"source": [
"使用 Viking DB 作为知识库的后端："
"使用 [知识库/Viking DB](https://www.volcengine.com/docs/84313/1254463) 作为后端，使用前[创建 知识库/Viking DB](https://console.volcengine.com/vikingdb/region:vikingdb+cn-beijing/home?) 和 [TOS](https://www.volcengine.com/docs/6349/74830) 并填写如下信息："
]
},
{
Expand Down Expand Up @@ -1373,7 +1345,7 @@
"id": "9j9aqke52nCz"
},
"source": [
"需要设置上报器（exporter），VeADK 当前支持将 Tracing 数据上报至火山引擎 TLS、火山引擎 APMPlus 以及火山引擎 Coze Loop 平台。它们分别对应不同的上报器。"
"需要设置上报器（exporter），VeADK 当前支持将 Tracing 数据上报至[火山引擎 Coze Loop](https://www.coze.cn/loop)、[火山引擎 TLS](https://www.volcengine.com/product/tls) 以及 [火山引擎 APMPlus](https://www.volcengine.com/product/apmplus) 平台。它们分别对应不同的上报器。"
]
},
{
Expand All @@ -1382,7 +1354,7 @@
"id": "azFOHaFe3C5x"
},
"source": [
"初始化上报器之前需要进行环境变量设置："
"初始化上报器之前需要进行环境变量设置，相应的获取方式可参考 [Coze Loop](https://loop.coze.cn/open/docs/cozeloop/veadk_trace_report)、[TLS](https://www.volcengine.com/docs/6470/72004)、[APMPlus](https://www.volcengine.com/docs/6431/1469364)："
]
},
{
Expand All @@ -1394,27 +1366,26 @@
"outputs": [],
"source": [
"import os\n",
"# Coze Loop 上报器环境变量\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT\"] = (\n",
" \"https://api.coze.cn/v1/loop/opentelemetry/v1/traces\"\n",
")\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME\"] = \"\" # 工作空间/workspace id\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY\"] = \"\" # 令牌/token\n",
"\n",
"# TLS 上报器环境变量\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT\"] = (\n",
" \"https://tls-cn-beijing.volces.com:4318/v1/traces\"\n",
")\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_TLS_REGION\"] = \"cn-beijing\"\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME\"] = \"\"\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME\"] = \"\" # TLS 主题/topic id\n",
"\n",
"# APMPlus 上报器环境变量\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT\"] = (\n",
" \"http://apmplus-cn-beijing.volces.com:4317\"\n",
")\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\"] = (\n",
" \"https://api.coze.cn/v1/loop/opentelemetry/v1/traces\"\n",
")\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME\"] = \"\"\n",
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY\"] = \"\""
"os.environ[\"OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY\"] = \"\" # app key"
]
},
{
Expand Down Expand Up @@ -1840,7 +1811,7 @@
"source": [
"# 部署在 VeFaaS 上的应用名称（Application name）及鉴权 Token\n",
"vefaas_application_name = \"\"\n",
"vefaas_application_token = \"\"\n"
"vefaas_application_token = \"\""
]
},
{
Expand Down