文档中心

向量数据库VikingDB

会话 (Sessions)

create_session-创建会话

概述

/api/v1/sessions 接口用于创建一条新的会话记录。会话是 OpenViking 中承载消息、归档、记忆提取和上下文组装的基础单元。
你可以让系统自动生成 session_id，也可以显式指定一个业务侧自定义会话 ID，便于后续与外部会话系统进行映射。

前置条件

完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口创建会话。建议同时明确当前请求所属的 agent_id，用于隔离不同 Agent 的会话上下文。

请求接口

URI

/api/v1/sessions
统一资源标识符。

请求方法

POST
客户端对服务器请求的操作类型。

请求头

参数	值	说明
Content-Type	`application/json`	请求消息类型
Authorization	`Bearer {api_key}`	鉴权

请求参数

参数	类型	必选	备注
`session_id`	string	否	自定义 Session ID。省略或传 `null` 时由服务端生成。
`memory_policy`	object 或 null	否	该 Session 后续 Commit 的默认记忆抽取策略。省略或传 `null` 表示使用用户或服务端默认策略。只能在创建时设置，Patch 接口不支持修改。
`auto_commit_policy`	object 或 null	否	自动 Commit 策略。传 object 表示启用；显式传 `null` 表示禁用；省略时默认禁用，但服务端配置 `memory.session_auto_commit.default_enabled=true` 时例外。
`memory_extraction_config`	object 或 null	否	可变的记忆抽取配置。目前支持 `events.tags`；省略或传 `null` 表示不设置默认标签。

memory_policy 参数

字段	类型	默认值	说明
`self.enabled`	boolean	`true`	是否在 / memories/ 主目录写入记忆。
`peer.enabled`	boolean	`true`	是否在 / peers / 写入交互对象相关记忆。
`working_memory.enabled`	boolean	`true`	是否生成归档摘要；传 `false` 可跳过 Working Memory 摘要。 Working Memory 可在每次归档的 session history 中使用 L1 Overview 读取
`memory_types`	string[] 或 null	`null`	限制本次 Session 可抽取的记忆类型。省略或传 `null` 表示允许全部已启用类型。 `memory_types` 必须使用当前 Registry 中已启用的类型。内置启用类型包括 `profile`、`preferences`、`entities`、`events`、`identity`、`soul`、`cases`、`trajectories` 和 `experiences`

auto_commit_policy 参数

传入 object 即启用自动 Commit。未传字段由默认值补齐；超出范围的整数会被截断到边界值。object 内的字段不能传 null，如需关闭自动 Commit，应将整个 auto_commit_policy 设为 null。

字段	类型	默认值	范围	说明
`pending_token_threshold`	integer	150000	0–1000000	未提交 pending token 严格大于该值后触发。传 0 关闭该触发器。
`message_count_threshold`	integer	100	0–1000	Live message 数严格大于该值后触发。传 0 关闭该触发器。
`keep_recent_count`	integer	0	0–1000	阈值触发时保留的最近消息数；idle 触发会忽略该值并归档全部积压消息。
`min_commit_interval_seconds`	integer	0	0–604800	两次自动 Commit 的最小间隔；0 表示不节流。

memory_extraction_config 参数

字段	类型	必填	说明
`events.tags`	string[]	否	事件记忆默认标签，每项采用严格 `key=value` 格式。系统会去除首尾空格、转为小写，并按 key 去重；重复 key 保留最后一个 value。例如：["team=support", "channel=web"]

响应消息

字段	类型	说明
`status`	string	成功时为 `ok`。
`result.session_id`	string	创建后的 Session ID。
`result.uri`	string	Session 的 canonical user URI。
`result.user`	object	归属用户，包含 `account_id`(数据空间) 和 `user_id`（目录所属user）。
`result.auto_commit_policy`	object 或 null	补齐默认值后的最终生效策略；禁用时为 `null`。
`result.memory_extraction_config`	object	最终生效配置，目前固定返回 `events.tags` 数组。

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
INVALID_ARGUMENT	请求体格式非法或 `session_id` 不符合约束

完整示例

示例一：自动生成会话 ID

curl -X POST "https://xxx/api/v1/sessions" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{}'

示例二：创建指定 ID 的会话

curl -X POST 'http://127.0.0.1:1933/api/v1/sessions' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-user-key' \
  -d '{
    "session_id": "support-agent-20260821",
    "memory_policy": {
      "self": {"enabled": true},
      "peer": {"enabled": true},
      "working_memory": {"enabled": true},
      "memory_types": ["profile", "preferences", "events"]
    },
    "auto_commit_policy": {
      "pending_token_threshold": 150000,
      "message_count_threshold": 100,
      "idle_timeout_seconds": 86400,
      "keep_recent_count": 10,
      "min_commit_interval_seconds": 300
    },
    "memory_extraction_config": {
      "events": {
        "tags": ["team=support", "channel=web"]
      }
    },
    "telemetry": {"summary": true}
  }'

响应示例

{
  "status": "ok",
  "result": {
    "session_id": "support-agent-20260821",
    "uri": "viking://user/alice/sessions/support-agent-20260821",
    "user": {
      "account_id": "acme",
      "user_id": "alice"
    },
    "auto_commit_policy": {
      "pending_token_threshold": 150000,
      "message_count_threshold": 100,
      "idle_timeout_seconds": 86400,
      "keep_recent_count": 10,
      "min_commit_interval_seconds": 300
    },
    "memory_extraction_config": {
      "events": {
        "tags": ["team=support", "channel=web"]
      }
    }
  },
  "telemetry": {
    "id": "tm_xxx",
    "summary": {
      "operation": "session.create",
      "status": "ok"
    }
  }
}

参数、示例与排错补充

返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
自定义输入参数缺少格式限制：session_id 长度 1–64 个字符，只能包含字母、数字、连字符和下划线。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.09.03 14:54:33

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

请求参数 #

memory_policy 参数

auto_commit_policy 参数

memory_extraction_config 参数

响应消息 #

常见错误码 #

完整示例 #

示例一：自动生成会话 ID #

示例二：创建指定 ID 的会话 #

响应示例 #

参数、示例与排错补充 #