文档中心

向量数据库VikingDB

会话 (Sessions)

add_message-添加消息

概述

/api/v1/sessions/{id}/messages 接口用于向指定会话追加一条消息。
接口提供两种消息写入方式：

简单文本模式：传 content 字符串，适合纯文本用户问题或助手回复。
Parts 模式：传 parts 数组，适合混合文本、上下文引用、图片和工具调用/结果。

如果 content 与 parts 同时存在，服务端使用 parts，忽略 content。推荐调用方只传其中一种，避免读代码的人误判真实入库内容。

前置条件

完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口写入消息。

请求接口

URI

/api/v1/sessions/{id}/messages
统一资源标识符。

请求方法

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

请求头

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

请求参数

Path 参数

参数	类型	必填	说明
session_id	string	是	Session 标识。若该 Session 不存在，首次 add_message 会自动创建。

Body 参数

参数	类型	必填	说明
role	string	是	消息角色。使用 user 或 assistant；工具调用与工具结果仍放在这两种角色的消息中，不要自造 tool 角色。
content	string	条件必填	简单文本模式的消息正文。content 与 parts 至少提供一个；两者同时存在时 parts 优先。
parts	array	条件必填	结构化消息内容。当前开源实现支持 text、context、image_url、tool。建议至少包含一个 Part。
created_at	string	否	消息发生时间，建议使用带时区的 ISO 8601，例如 2026-08-31T14:30:00+08:00。省略时由服务端写入当前 UTC 时间。
peer_id	string	否	稳定的交互对象标识。开源扩展字段；只允许字母、数字、下划线、点、@、连字符，不能为 . 或 ..，最多一个 @。
turn_id	string	否	对话轮次标识。可把同一用户请求、助手步骤和工具返回归到同一个 turn。开源扩展字段。
message_kind	string	否	消息语义类型：user_query、assistant_step、tool_transport、checkpoint。服务端按原值保存，不会根据 role 或 Part 自动推导。
source_message_ids	array	否	生成当前消息所依据的源消息 ID，用于 checkpoint 或派生消息的来源追踪。它不是幂等键。

Part 列表对象类型总览

type	承载内容	典型场景	关键字段
text	纯文本片段	问题、回答、说明文字	text
context	OpenViking 上下文引用与摘要	声明回复引用了某份资源、记忆或 Skill	uri、context_type、abstract
image_url	图片 URL 或 OpenViking 图片 URI	带图片的用户输入；记忆提取时可由 VLM 转为描述	image_url.url、image_url.detail
tool	工具调用、状态、输入与输出	保存 Agent 的工具执行轨迹	tool_id、tool_name、tool_input、tool_output、tool_status

text part

字段	类型	必填	说明
type	string	是	固定为 text。
text	string	建议必填	文本内容。当前开源解析器缺省为空字符串，但空文本通常没有业务意义。

示例：

{
  "type": "text",
  "text": "请总结这份认证指南的关键步骤。"
}

context part

字段	类型	必填	说明
type	string	是	固定为 context。
uri	string	建议必填	被引用对象的 viking:// URI。若非空，服务端会解析路径变量并校验当前请求是否有权访问。
context_type	string	否	memory、resource 或 skill；默认 memory。
abstract	string	建议必填	该上下文的简短摘要。OpenViking 组装提示词与估算文本 Token 时使用 abstract，而不是把 URI 本身当作正文。

示例：

{
  "type": "context",
  "uri": "viking://resources/docs/auth/",
  "context_type": "resource",
  "abstract": "认证指南：介绍 API Key、Bearer Token 和租户身份头的配置方式。"
}

说明

uri 用于来源追踪和后续读取，abstract 用于当前消息的可读摘要，两者不要只填其一。
abstract 应是 L0 级别的短摘要，不要复制整篇资源；需要完整内容时再通过 read 等接口按 URI 读取。
不要引用当前 API Key 无权限访问的 viking:// URI，否则会被 URI 权限校验拒绝。

Image_url Part

字段	类型	必填	说明
type	string	是	固定为 image_url。
image_url	string	object	是
image_url.url	string	对象形式必填	非空图片地址。可使用后端能够访问的 HTTP(S) URL，或当前请求有权限访问的 viking:// 图片 URI。
image_url.detail	string	否	传给下游图像模型的细节偏好。常用 auto、low、high，用于为多模态记忆抽取定义LLM 图像理解的细节度。高细节度会带来更多token消耗。

示例：

{
  "type": "image_url",
  "image_url": "https://example.com/studio-layout.png"
}

Tool part

字段	类型	必填	说明
type	string	是	固定为 tool。
tool_id	string	建议必填	本次工具调用 ID。同一调用的开始、状态变化和结果应保持一致。
tool_name	string	建议必填	工具名称，例如 search_web。
tool_uri	string	否	工具文件或定义的 viking:// URI；非空时会进行 URI 解析与权限校验。
skill_uri	string	否	触发本次调用的 Skill URI；非空时会进行 URI 解析与权限校验。
tool_input	object	null	否
tool_output	string	否	工具输出正文。大结果可由 Session 的工具结果外置策略转存。
tool_status	string	否	建议使用 pending、running、completed、error；默认 pending。可仅上传工具执行完成完成态、失败态的结果，可节省工具调用过程中因等待时间较长导致的 message 过多，消耗更多 session 记忆抽取 token。
duration_ms	number	否	工具执行耗时，单位毫秒。
prompt_tokens	integer	否	工具或工具代理使用的输入 Token。
completion_tokens	integer	否	工具或工具代理使用的输出 Token。

示例：

{
  "type": "tool",
  "tool_id": "call_123",
  "tool_name": "search_web",
  "skill_uri": "viking://~/skills/search-web/",
  "tool_input": {
    "query": "OAuth best practices"
  },
  "tool_status": "completed",
  "tool_output": "检索到 8 条结果，核心结论为……",
  "duration_ms": 684.5,
  "prompt_tokens": 72,
  "completion_tokens": 210
}

推荐同一工具调用使用一致的 tool_id。若要分别保存“开始执行”和“执行完成”两个状态，可追加两条消息或两个 tool Part，并保持 tool_id 不变、更新 tool_status 与 tool_output。

响应消息

字段	类型	说明
status	string	成功时为 ok。
result.session_id	string	本次写入的 Session ID。
result.message_count	integer	写入完成后，Session 当前保留的消息总数。
result.pending_tokens	integer	写入后、尚未归档消息的估算 Token 数，供自动提交策略判断。最新版开源字段；官网当前页面未列出。

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
INVALID_ARGUMENT	未提供 `content` 和 `parts`，或请求体格式错误

完整示例

示例一：简单模式写入文本消息

curl -X POST "https://xxx/api/v1/sessions/a1b2c3d4/messages" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "How do I authenticate users?"
  }'

示例二：Parts 模式写入结构化消息

curl -X POST "${BASE_URL}/api/v1/sessions/session-demo-001/messages" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "assistant",
    "turn_id": "turn-20260831-001",
    "message_kind": "tool_transport",
    "parts": [
      {
        "type": "text",
        "text": "我已检查认证文档和错误码。"
      },
      {
        "type": "tool",
        "tool_id": "call_auth_docs_001",
        "tool_name": "read",
        "tool_input": {
          "uri": "viking://resources/docs/auth/"
        },
        "tool_status": "completed",
        "tool_output": "401 表示凭证缺失或无效；403 表示已识别身份但没有目标资源权限。"
      }
    ]
  }'

执行成功返回：

{
  "status": "ok",
  "result": {
    "session_id": "session-demo-001",
    "message_count": 3,
    "pending_tokens": 286
  }
}

实践指引

如何选择 content 与 parts

场景	推荐方式	原因
只有一段纯文本	content	结构最简单，兼容官网托管版的基础契约。
文本中要携带来源引用	text + context	同时保存可读文本、来源 URI 和摘要。
带图片的问题	text + image_url	保持问题与图片的顺序关系，便于后续 VLM 理解。
抽取 Agent 经验记忆，采集 Agent 工具执行轨迹	text + tool	保留调用 ID、参数、状态、结果和用量。

消息建模建议

role 只用 user、assistant；工具类型放进 Part，不新增 role。
同一对话轮次使用稳定 turn_id；工具请求与工具结果使用稳定 tool_id。
需要追踪派生关系时再写 source_message_ids，不要把它当作请求去重的主键。
context.abstract 控制在可独立理解的短摘要；URI 指向真实来源。
图片 URL 必须能被 OpenViking 服务端或配置的图像模型访问。临时签名 URL 的有效期应覆盖后续记忆提取时间。
工具输出可能很大时，不要在客户端任意截断并丢失来源；优先使用服务端的工具结果外置能力，或同时保留摘要、哈希和存储 URI。
网络超时重试前，先读取 Session 最近消息或在业务侧维护请求去重记录，避免重复追加。

参数、示例与排错补充

枚举型参数列举不全：role 的完整取值为 user、assistant 和 system，分别表示用户消息、助手消息和系统指令。
请求参数描述不完整或有歧义：parts 为对象数组；每项 type 必填。type=text 时 text:string 必填；type=resource/image 时 uri:string 必填。
返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
请求示例与请求参数说明不符：当前接口一次只追加一条消息，请求体必须包含 role，并在 content 与 parts 中二选一；批量 /messages/batch 示例已移出本文。
标识型参数缺少获取规则：会话 id/session_id 从创建会话接口的 result.id（或记忆库 AddSession 返回值）取得，也可由列出会话接口查询；不要把示例 ID 用于生产请求。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.08.31 22:03:42

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

请求参数 #

Path 参数

Body 参数

Part 列表对象类型总览

响应消息 #

常见错误码 #

完整示例 #

示例一：简单模式写入文本消息 #

示例二：Parts 模式写入结构化消息 #

实践指引 #

如何选择 content 与 parts #

消息建模建议 #

#

参数、示例与排错补充 #

概述