使用 MySQL 存储

mysql 后端把会话存储到 MySQL 数据库。多个智能体实例可连接同一数据库，实现会话共享与分布式持久化。

何时使用

生产环境、多实例或分布式部署；
需要由统一的 MySQL 集中管理会话数据。

依赖

安装 veadk-python 后已包含所需数据库驱动。运行示例前创建数据库和账号，授予会话表的创建、读写权限，并确认运行环境可连接数据库地址；VeADK 不创建数据库实例或数据库本身通过环境变量提供连接信息；密码由部署环境的密钥配置注入

export DATABASE_MYSQL_HOST="127.0.0.1"
export DATABASE_MYSQL_USER="veadk"
export DATABASE_MYSQL_DATABASE="veadk_sessions"

另需设置 DATABASE_MYSQL_PASSWORD。这些连接参数适用于自建数据库、火山引擎和 BytePlus 的可达数据库实例，不自动选择云厂商或区域

使用示例

连接信息通过 config.yaml（或对应环境变量）提供，不要把密码写进代码。

import asyncio

from veadk.memory.short_term_memory import ShortTermMemory

stm = ShortTermMemory(backend="mysql")

async def main():
    try:
        await stm.create_session(
            app_name="memory_demo", user_id="user_42", session_id="chat_01"
        )
        session = await stm.session_service.get_session(
            app_name="memory_demo", user_id="user_42", session_id="chat_01"
        )
        assert session is not None
        print(session.id)
    finally:
        await stm.session_service.close()

asyncio.run(main())

成功后输出 chat_01，表示会话已创建并可读回；示例不调用模型。实际对话时将同一 stm 传给 Runner(short_term_memory=stm, agent=agent)，并保持应用、用户和会话标识一致如需透传连接池等 SQLAlchemy 驱动参数，可使用 db_kwargs：

stm = ShortTermMemory(
    backend="mysql",
    db_kwargs={"pool_size": 10, "pool_recycle": 3600},
)

也可以用 backend_configs 在代码中直接注入 MysqlConfig，覆盖环境变量（不推荐把密码写进代码）：

import os

from veadk.configs.database_configs import MysqlConfig

stm = ShortTermMemory(
    backend="mysql",
    backend_configs={
        "mysql_config": MysqlConfig(
            host="127.0.0.1",
            user="veadk",
            password=os.environ["DATABASE_MYSQL_PASSWORD"],
            database="veadk_sessions",
        )
    },
)

参数

ShortTermMemory 构造参数（mysql 场景）

参数	类型	默认值	对 mysql 是否生效	说明
`backend`	`str`	`"local"`	生效	设为 `"mysql"` 选择本后端
`backend_configs`	`dict`	`{}`	生效	MySQL 专用配置；可包含 `mysql_config`（一个 `MysqlConfig` 实例），用于覆盖默认从环境变量读取的配置
`db_kwargs`	`dict`	`{}`	生效	传给 SQLAlchemy 引擎，常用于连接池设置，如 `pool_size`、`pool_recycle`、`pool_pre_ping` 等
`db_url`	`str`	`""`	生效（覆盖）	直接给出连接串。一旦设置，将忽略 `backend` 与 `backend_configs`，并采用 `db_url` 与 `db_kwargs`
`local_database_path`	`str`	`/tmp/veadk_local_database.db`	不生效	仅 `sqlite` 使用
`after_load_memory_callback`	`Callable \| None`	`None`	生效	同步读取回调；接收 `Session` 或 `None`，以及查询时的参数，建议使用 `def callback(session, args, *kwargs)`
`after_create_session_callback`	`Callable \| None`	`None`	生效	通过 `ShortTermMemory.create_session()` 首次创建会话后触发；支持同步或异步回调，接收新建的 `Session`

MysqlConfig 字段与环境变量

配置类 MysqlConfig 的环境变量前缀为 DATABASE_MYSQL_。

config.yaml

database:
  mysql:
    host:       # 主机或 IP
    user:
    password:
    database:
    charset: utf8

配置项	环境变量	类型	默认值	说明
`host`	`DATABASE_MYSQL_HOST`	`str`	`""`	数据库主机或 IP
`user`	`DATABASE_MYSQL_USER`	`str`	`""`	用户名
`password`	`DATABASE_MYSQL_PASSWORD`	`str`	`""`	密码
`database`	`DATABASE_MYSQL_DATABASE`	`str`	`""`	数据库名
`charset`	`DATABASE_MYSQL_CHARSET`	`str`	`utf8`	配置字段默认值；当前会话连接不传递此字段。若需指定字符集，使用 `db_kwargs={"connect_args": {"charset": "utf8mb4"}}`
`secret_token`	`DATABASE_MYSQL_SECRET_TOKEN`	`str`	`""`	MySQL 鉴权用的 STS 临时令牌，暂未支持

VeADK 会选择与当前 Google ADK 版本兼容的 MySQL 驱动，并自动编码用户名与密码中的特殊字符。可在火山引擎开通 MySQL 数据库。

MysqlConfig 不含端口字段，连接使用 MySQL 的默认端口。若需要非默认端口或更精细的连接控制，请改用 db_url 直接提供完整连接串。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

依赖

使用示例

参数

ShortTermMemory 构造参数（mysql 场景）

MysqlConfig 字段与环境变量

​何时使用

​依赖

​使用示例

​参数

​ShortTermMemory 构造参数（mysql 场景）

​MysqlConfig 字段与环境变量

何时使用

依赖

使用示例

参数

ShortTermMemory 构造参数（mysql 场景）

MysqlConfig 字段与环境变量