Skip to content

Commit 36ada01

Browse files
YumengBaoYumengBao
committed
feat: add runtime & memory tutorials
1 parent 7dbff6d commit 36ada01

File tree

5 files changed

+2070
-0
lines changed

5 files changed

+2070
-0
lines changed

‎01-tutorials/01-AgentKit-Runtime/00_configuration_and_credentials.ipynb‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# AgentKit SDK 教程 00: 配置与凭证\n",
8+
"\n",
9+
"欢迎来到 AgentKit SDK！本教程是所有新用户的**第一站**，将引导你完成 AgentKit 的环境配置。\n",
10+
"\n",
11+
"在本 Notebook 中，你将学会：\n",
12+
"\n",
13+
"1. 理解 AgentKit 中的两种关键凭证（环境变量）；\n",
14+
"2. 如何为 SDK 与 CLI 配置云服务访问凭证；\n",
15+
"3. 如何为 Agent 运行时配置模型访问等环境变量。\n",
16+
"\n",
17+
"完成本教程后，你的开发环境将准备就绪，可以顺利运行其他所有教程。"
18+
]
19+
},
20+
{
21+
"cell_type": "markdown",
22+
"metadata": {},
23+
"source": [
24+
"## 1. 两种关键凭证及其用途\n",
25+
"\n",
26+
"在 AgentKit 中，我们主要和两类环境变量（凭证）打交道，清晰地理解它们的区别非常重要：\n",
27+
"\n",
28+
"### 第一类：SDK 与 CLI 的云服务访问凭证\n",
29+
"\n",
30+
"- **用途**：当你在本地（比如本 Notebook 或终端）运行 `agentkit` 命令或调用 AgentKit SDK 时，需要用这类凭证来**授权你访问火山引擎的云服务**。这些操作包括创建/管理镜像仓库（CR）、持续集成流水线（CodePipeline）、对象存储（TOS）以及部署 Agent 所需的 Runtime 资源。\n",
31+
"- **变量名**：`VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY`, `VOLCENGINE_REGION`。\n",
32+
"- **配置场景**：主要用于本地开发环境，是你作为“开发者”的身份凭证。\n",
33+
"\n",
34+
"### 第二类：Agent 运行时的环境变量\n",
35+
"\n",
36+
"- **用途**：当你的 Agent **代码在云上（Runtime）或本地（Docker）运行时**，需要用这类凭证来**访问外部服务**，最常见的就是访问方舟（Ark）大模型。\n",
37+
"- **变量名**：例如 `MODEL_AGENT_NAME`, `MODEL_AGENT_API_KEY` 等，具体变量名取决于你的 Agent 代码实现。\n",
38+
"- **配置场景**：这些变量需要被注入到 Agent 的运行环境中（容器），是你“Agent”的身份凭证。\n",
39+
"\n",
40+
"简单来说：第一类是你开发时用的，第二类是你的 Agent 运行时用的。下面我们分别介绍如何配置它们。"
41+
]
42+
},
43+
{
44+
"cell_type": "markdown",
45+
"metadata": {},
46+
"source": [
47+
"## 2. 配置 SDK 与 CLI 的云服务访问凭证\n",
48+
"\n",
49+
"我们推荐使用 `agentkit` 命令行工具来全局管理你的云服务凭证。这种方式最安全、便捷，且一次配置，到处生效。\n",
50+
"\n",
51+
"### 推荐方式：使用 `agentkit config` 命令\n",
52+
"\n",
53+
"打开你的终端，执行以下命令，将 `YOUR_ACCESS_KEY` 和 `YOUR_SECRET_KEY` 替换为你的真实凭证：\n",
54+
"\n",
55+
"```bash\n",
56+
"agentkit config --global --set volcengine.access_key=YOUR_ACCESS_KEY\n",
57+
"agentkit config --global --set volcengine.secret_key=YOUR_SECRET_KEY\n",
58+
"agentkit config --global --set volcengine.region=cn-beijing # 或其他区域\n",
59+
"```\n",
60+
"\n",
61+
"执行完毕后，AgentKit 会将你的凭证安全地存储在全局配置文件 `~/.agentkit/config.yaml` 中。SDK 和 CLI 会自动读取，无需再进行其他操作。\n",
62+
"\n",
63+
"### 备选方式：使用环境变量\n",
64+
"\n",
65+
"如果你不希望创建全局配置文件，也可以在运行 SDK/CLI 的终端中设置环境变量。\n",
66+
"\n",
67+
"```bash\n",
68+
"export VOLCENGINE_ACCESS_KEY=\"YOUR_ACCESS_KEY\"\n",
69+
"export VOLCENGINE_SECRET_KEY=\"YOUR_SECRET_KEY\"\n",
70+
"export VOLCENGINE_REGION=\"cn-beijing\"\n",
71+
"```\n",
72+
"\n",
73+
"> **注意**：这种方式只在当前终端会话中有效。如果打开新的终端，需要重新设置。"
74+
]
75+
},
76+
{
77+
"cell_type": "markdown",
78+
"metadata": {},
79+
"source": [
80+
"## 3. 配置 Agent 运行时的环境变量\n",
81+
"\n",
82+
"Agent 运行时的环境变量通过项目配置文件 `agentkit.yaml` 中的 `runtime_envs` 字段来管理。这样可以确保每次部署时，正确的环境变量都会被注入到你的 Agent 运行环境中。\n",
83+
"\n",
84+
"### 配置方式：修改 `agentkit.yaml`\n",
85+
"\n",
86+
"当你使用 `sdk.init_project` 创建一个新项目后，会得到一个 `agentkit.yaml` 文件。你可以通过 `AgentConfig` 类来以编程方式修改它。\n",
87+
"\n",
88+
"下面是一个示例，演示如何为一个 Agent 项目添加访问方舟模型所需的环境变量：\n"
89+
]
90+
},
91+
{
92+
"cell_type": "code",
93+
"execution_count": null,
94+
"metadata": {},
95+
"outputs": [],
96+
"source": [
97+
"from pathlib import Path\n",
98+
"from agentkit.toolkit import sdk\n",
99+
"from agentkit.toolkit.sdk import AgentConfig\n",
100+
"\n",
101+
"# 1. 准备一个示例项目（如果不存在）\n",
102+
"project_root = Path(\"tutorial_projects/t00-config-demo\")\n",
103+
"if not project_root.exists():\n",
104+
" sdk.init_project(project_name=project_root.name, template=\"basic\", project_root=str(project_root))\n",
105+
" print(f\"示例项目已创建在: {project_root.resolve()}\")\n",
106+
"else:\n",
107+
" print(f\"示例项目已存在: {project_root.resolve()}\")\n",
108+
"\n",
109+
"# 2. 加载项目配置\n",
110+
"config = AgentConfig.load(project_root)\n",
111+
"\n",
112+
"# 3. 添加或更新运行时环境变量\n",
113+
"config.add_runtime_env(\"MODEL_AGENT_NAME\", \"your-model-agent-name\")\n",
114+
"config.add_runtime_env(\"MODEL_AGENT_API_KEY\", \"your-model-agent-api-key\")\n",
115+
"\n",
116+
"# 4. 保存配置\n",
117+
"config.save()\n",
118+
"\n",
119+
"print(\"已成功向 agentkit.yaml 中写入运行时环境变量:\")\n",
120+
"print(config.runtime_envs)"
121+
]
122+
},
123+
{
124+
"cell_type": "markdown",
125+
"metadata": {},
126+
"source": [
127+
"> **提示**：\n",
128+
"> - `your-model-agent-name` 和 `your-model-agent-api-key` 需要替换为你的模型终端节点和对应的 API Key。\n",
129+
"> - 当你的 Agent 部署在**云上 Runtime** 并使用 veADK 时，AgentKit 会自动为你注入访问火山引擎服务的临时 AK/SK，因此你**不需要**在 `runtime_envs` 中手动配置 `VOLCENGINE_*` 变量。\n",
130+
"> - 当你的 Agent 在**本地 Docker** 中运行时，如果 Agent 代码需要访问火山引擎服务（例如，调用 veadk），则建议将第一类凭证也添加到 `runtime_envs` 中。\n",
131+
"\n",
132+
"### 如何在本地运行的 Docker 中传递凭证？\n",
133+
"\n",
134+
"如果你使用 `local` 策略在本地 Docker 中运行 Agent，并且你的 Agent 代码需要访问火山引擎云服务，你可以这样做：\n"
135+
]
136+
},
137+
{
138+
"cell_type": "code",
139+
"execution_count": null,
140+
"metadata": {},
141+
"outputs": [],
142+
"source": [
143+
"import os\n",
144+
"\n",
145+
"# 假设你的 AK/SK 已经配置在环境变量中\n",
146+
"ak = os.environ.get(\"VOLCENGINE_ACCESS_KEY\")\n",
147+
"sk = os.environ.get(\"VOLCENGINE_SECRET_KEY\")\n",
148+
"region = os.environ.get(\"VOLCENGINE_REGION\", \"cn-beijing\")\n",
149+
"\n",
150+
"if ak and sk:\n",
151+
" config = AgentConfig.load(project_root)\n",
152+
" \n",
153+
" # 获取 local 策略的配置，并为其添加环境变量\n",
154+
" local_strategy_config = config.get_strategy_config(\"local\") or {}\n",
155+
" runtime_envs = local_strategy_config.get(\"runtime_envs\", {})\n",
156+
" runtime_envs.update({\n",
157+
" \"VOLCENGINE_ACCESS_KEY\": ak,\n",
158+
" \"VOLCENGINE_SECRET_KEY\": sk,\n",
159+
" \"VOLCENGINE_REGION\": region\n",
160+
" })\n",
161+
" \n",
162+
" config.update_strategy_config({\"runtime_envs\": runtime_envs}, strategy_name=\"local\")\n",
163+
" config.save()\n",
164+
" \n",
165+
" print(\"已将本地 AK/SK 写入 local 策略的 runtime_envs 中。\")\n",
166+
"else:\n",
167+
" print(\"未在环境变量中找到 VOLCENGINE_ACCESS_KEY 或 VOLCENGINE_SECRET_KEY。\")\n",
168+
" print(\"如果你需要在本地 Docker 中访问云服务，请先配置好第一类凭证。\")"
169+
]
170+
},
171+
{
172+
"cell_type": "markdown",
173+
"metadata": {},
174+
"source": [
175+
"## 总结\n",
176+
"\n",
177+
"恭喜你！现在你已经掌握了 AgentKit 中两类凭证的配置方法。\n",
178+
"\n",
179+
"- **SDK/CLI 凭证**：通过 `~/.agentkit/config.yaml` 或环境变量配置，用于开发。\n",
180+
"- **Agent 运行时凭证**：通过 `agentkit.yaml` 的 `runtime_envs` 配置，用于 Agent 运行。\n",
181+
"\n",
182+
"有了这些知识，你就可以顺利地进行后续的 Agent 开发与部署了。现在，请继续学习其他教程！"
183+
]
184+
}
185+
],
186+
"metadata": {
187+
"kernelspec": {
188+
"display_name": "Python 3",
189+
"language": "python",
190+
"name": "python3"
191+
},
192+
"language_info": {
193+
"name": "python",
194+
"version": "3.8.10"
195+
}
196+
},
197+
"nbformat": 4,
198+
"nbformat_minor": 2
199+
}

0 commit comments

Comments
 (0)