文档中心

AgentKit

会话管理

快速搭建并使用会话管理

本文以创建 Serverless PostgreSQL 类型的会话资源和 VeADK（Python）为主，面向第一次接触 AgentKit 的新手用户，带您从零跑通“创建会话资源 → 在 Agent 中集成会话资源 → 调用并验证”的完整操作流程。

适用场景

访问压力较小、负载波动明显，或希望减少数据库运维成本的场景。

前提条件

在开始操作前，请确保已完成如下全部准备工作，不满足会导致后续操作流程无法完成。

已开通 AgentKit 服务。若未开通，请登录 AgentKit 控制台，根据系统引导开通产品。

已登录火山引擎控制台获取 AK/SK，进入 API 访问密钥页面，创建并获取 Access Key ID 和 Secret Access Key。

已基于 VeADK 构建 Agent，并部署至 AgentKit 智能体运行时。

本实践基于 AgentKit CLI 预置模板 Basic Agent App（采用VeADK 框架）创建项目，并已将 Agent 部署至 AgentKit 智能体运行时。详情请参见使用 AgentKit CLI 开发并部署智能体。

将会话管理集成至 AgentKit

步骤一：创建会话资源

在左侧导航树中，选择“基础组件 > 会话管理”。

单击“创建资源”按钮，在创建页面参照下表完成参数配置，配置完成后单击“创建”按钮，完成操作。

首次创建资源，系统会提示开通 Serverless PostgreSQL（AIDAP）服务，请根据页面提示完成开通后再继续创建。

说明

如果您需要导入已有数据库作为会话资源，详情请参见导入会话资源。

参数	说明	示例
名称	自定义会话资源名称。默认随机生成Agentkit_Session_字符串，创建成功后，不支持修改。	Agentkit_Session_rmqp81p
类型	当前仅支持 Serverless PostgreSQL。火山引擎 Serverless PostgreSQL 是免运维、弹性按量计费的轻量化 PG 数据库，在 AgentKit 会话管理中存储智能体对话短期上下文，适配系统压力小、需要弹性扩缩资源的业务场景。	Serverless PostgreSQL
访问模式	选择新建会话资源被访问的方式。公网访问：通过公网访问会话资源，默认访问方式，不支持取消。私网访问：通过私网访问会话资源，安全性更高。下拉选择目标私有网络（VPC）和子网，每个可用区仅支持选择一个子网。	公网访问

步骤二：配置本地环境变量并在 Agent 中接入会话管理

本文使用 AgentKit CLI 构建的 Agent 项目结构主要文件如下所示：

.dockerignore：用于记录构建 Docker 时需要忽略的文件或目录路径。Docker 构建时， COPY . . 命令会忽略记录在本文件中的文件及目录，减小镜像体积并避免敏感信息泄露。

agentkit.yaml ：AgentKit 项目的配置文件，定义了项目元信息、运行时环境变量、云部署参数等。

requirements.txt：用于声明 Agent 所需的 Python 包依赖。Docker 构建时，将通过 RUN uv pip install -r requirements.txt 将其安装到容器镜像中。

simple_agent.py ：Agent 应用入口文件，定义了 Agent 的行为包括接收用户请求、与模型对话、返回流式响应等。

此时，只需对 Agent 进行以下修改：

为 Agent 文件添加会话管理ShortTermMemory。

将获取的会话管理环境变量添加到agentkit.yaml。

修改步骤如下：

在会话资源 Agentkit_Session_wqp4kou 的“集成信息”页签下，获取环境变量配置信息。

获取数据库密码。

在集成代码页面，单击“原始数据库”按钮，跳转至该会话资源数据库的分支总览页面。

选择“算力”页签，单击“连接”按钮。

在连接字符串模块的Parameters页签中获取数据库密码。

（可选）如果尚未获取火山引擎 AK/SK，请先进入 API 访问密钥页面创建并复制 Access Key ID 和 Secret Access Key。若已完成，请跳过本步骤。了解更多

集成会话管理。

在本地环境设置环境变量

（可选）若您退出了虚拟环境，请执行如下命令重新激活。若未退出，请跳过本步骤。

source .venv/bin/activate

输入如下命令设置环境变量，添加 AK/SK 信息，其中<your_access_key>、<your_secret_key>需替换为实际的 AK/SK 信息。

注意

由于 AK/SK 属于高敏感凭据，直接写入.env等静态配置文件存在泄露风险，在本地开发环境中配置 AK/SK 时，推荐通过终端会话级环境变量导出的方式管理。

终端会话级环境变量为一次性配置，仅对当前终端窗口生效，关闭终端窗口后重新打开或开启新的终端窗口后，均需重新配置。

export VOLCENGINE_ACCESS_KEY=<your_access_key>
export VOLCENGINE_SECRET_KEY=<your_secret_key>

执行命令cd <Agent项目根目录>进入 Agent 项目根目录，<Agent项目根目录>需替换为您的实际根目录路径。

为agentkit.yaml文件添加上述步骤中获取到的会话管理环境变量信息。

执行以下命令，打开AgentKit 项目的配置文件。

vim agentkit.yaml

按i键进入编辑模式，填写会话管理环境变量信息。

launch_types:
cloud:
runtime_envs:
DATABASE_POSTGRESQL_HOST: <your postgresql host>
DATABASE_POSTGRESQL_USER: <your postgresql user>
DATABASE_POSTGRESQL_DATABASE: <your postgresql database>
DATABASE_POSTGRESQL_PASSWORD: <your postgresql password>

参数	说明
<your postgresql host>	替换为会话管理数据库的HOST，此信息已在上述操作中获取。
<your postgresql user>	替换为会话管理数据库的用户名，此信息已在上述操作中获取。
<your postgresql database>	替换为会话管理数据库的名称，此信息已在上述操作中获取。
<your postgresql password>	替换为会话管理数据库的密码，此信息已在上述操作中获取。注意密码需用单引号包裹，屏蔽 Shell 对%、$等特殊字符的转义处理，确保原始密码原样传入；避免裸写密码或仅使用双引号，防止字符被解析导致密码校验失败。

按esc键退出编辑模式，然后输入:wq保存退出。

在 Agent 中添加记忆库相关配置。

执行以下命令，打开 Agent 应用入口文件。

vim simple_agent.py

按i键进入编辑模式，在代码中加入下方高亮部分内容。完整接入方式请参见在 Agent 中集成会话管理。

# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import logging
import os

from veadk import Agent, Runner

from agentkit.apps import AgentkitSimpleApp
from veadk.prompts.agent_default_prompt import DEFAULT_DESCRIPTION, DEFAULT_INSTRUCTION
from veadk.memory.short_term_memory import ShortTermMemory

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

app = AgentkitSimpleApp()

agent_name = "Agent"
description = DEFAULT_DESCRIPTION
system_prompt = DEFAULT_INSTRUCTION

tools = []

# from veadk.tools.builtin_tools.web_search import web_search
# tools.append(web_search)
#会话管理
short_term_memory = ShortTermMemory(
backend="postgresql", # 指定 ShortTermMemory 的存储方式
)

agent = Agent(
name=agent_name,
description=description,
instruction=system_prompt,
tools=tools,
)
runner = Runner(
agent=agent,
short_term_memory=short_term_memory,
app_name="simple_agent",
)

@app.entrypoint
async def run(payload: dict, headers: dict) -> str:
prompt = payload["prompt"]
user_id = headers["user_id"]
session_id = headers["session_id"]

logger.info(
f"Running agent with prompt: {prompt}, user_id: {user_id}, session_id: {session_id}"
)
response = await runner.run(messages=prompt, user_id=user_id, session_id=session_id)

logger.info(f"Run response: {response}")
return response

@app.ping
def ping() -> str:
return "pong!"

if __name__ == "__main__":
app.run(host="0.0.0.0", port=8000)

按esc键退出编辑模式，然后输入:wq保存退出。

步骤三：部署至云上 AgentKit 智能体运行时

说明

本文已明确使用 AgentKit CLI 构建了 Agent 并部署至 AgentKit 智能体运行时，因此在 Agent 代码中集成记忆库后，可以直接执行agentkit launch命令。

执行以下命令，将集成记忆库的 Agent 应用构建并部署到 AgentKit 智能体运行时。

agentkit launch

当回显智能体运行时状态为 Ready 时，则表示部署成功。

进入 AgentKit 智能体运行时页面，单击目标智能体运行时名称，选择版本管理页签，查看已部署的智能体运行时发布记录及版本信息。

您可以通过控制台“在线测试”或通过invoke命令验证 Agent 能否正常访问会话管理。

在线测试
使用 AgentKit CLI 命令
进入智能体运行时页面，单击目标智能体运行时操作列的“在线测试”按钮。
在 Body 类型模块中，选择 raw 并输入测试参数（本文调整 Prompt 为“你什么时候买了冰激凌”），单击“调试”按钮发起 POST 请求。更多调试参数详情，请参见调用 Agent。

在调试结果模块，确认状态码为 200，并验证返回内容符合预期。
说明
该结果仅表示Agent能正常访问，并不能验证Agent具备短期记忆管理能力。

进入会话管理页面，单击 Agentkit_Session_wqp4kou 会话资源，并单击页面右上角的“原始数据库”按钮。

在AIDAP页面，选择“表管理 > events”。

若表中有刚发起 Prompt 时指定的userid（默认为defaultUser）、session_id（默认为defaultSession）及 event_data数据，则表示能访问会话资源。
在本地虚拟环境中执行如下命令，发送 Prompt。

agentkit invoke "查询CodingPlan信息"

若返回信息中显示Invocation successful，则表示请求成功。
说明
该结果仅表示 Agent 能正常访问，并不能验证 Agent 具备短期记忆管理能力。

进入会话管理页面，单击 Agentkit_Session_wqp4kou 会话资源，并单击页面右上角的“原始数据库”按钮。

在 AIDAP 页面，选择“表管理 > events”。

若表中有刚发起 Prompt 时的userid（默认为agentkit_user）、session_id（默认为agentkit_sample_session）及 event_data数据，则表示能访问会话资源。

管理Serverless PostgreSQL会话资源

说明

本实践仅为您介绍搭建 AgentKit 会话资源后的相关管理操作，如需完整管理会话资源的各项信息，请参见 PostgreSQL 引擎用户指南。

删除会话资源

注意

本操作用于删除在 AgentKit 控制台创建的会话资源。删除后，会话资源及其相关数据将被全部删除，且无法恢复，请谨慎操作。

如果删除的是导入的会话资源，例如在Serverless PostgreSQL平台或 RDS PostgreSQL平台或 RDS MySQL平台创建后导入到 AgentKit 的会话资源，本操作仅解除该会话资源与 AgentKit 的关联，不会删除原平台中的资源。如需彻底删除会话资源，请前往对应的创建平台操作。

在左侧导航树中，选择“会话管理”。

单击目标会话资源操作列的“删除”按钮，完成操作。

最近更新时间：2026.09.02 15:50:12

这个页面对您有帮助吗？

有用

无用