尧图网站建设 
OpenViking Agent Evolution API 实战查询 Experience 应用轨迹与结果分布【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文围绕 OpenViking 的 Agent Evolution API 展开讲解如何通过 HTTP 接口查询某条 Experience 被 Agent 实际应用后的 Trajectory 记录与五种结果状态分布并结合仓库源码剖析其基于精确标量标签聚合的底层实现。读完本文你将掌握这两个端点的完整参数语义、curl 调用方式、响应解读方法以及 Experience → Trajectory 血缘链路在提交阶段是如何生成、在查询阶段是如何被精确还原的。背景Experience 与 Trajectory 的血缘关系在 OpenViking 中会话提交commit会从对话中抽取长期记忆其中与Agent 进化直接相关的是三种记忆类型cases可训练、可评估的任务案例trajectories可复用的操作契约存放在viking://user/{user_id}/memories/trajectories/experiences可复用的执行经验存放在viking://user/{user_id}/memories/experiences/。记忆的完整类型列表见 记忆 API。Agent Evolution 的核心思想是一条 Experience经验在被实际读取并应用于后续任务后会产生对应的 Trajectory操作轨迹。这条经验被应用的血缘链路lineage记录在会话提交阶段并可通过 Agent Evolution API 反向查询——即给定一条 Experience 的 URI找出哪些 Trajectory 曾成功读取过它以及这些应用最终的结果分布。会话提交如何生成这些记忆可参考 会话 API 中的memory_policy与auto_commit_policy配置。接口概览与调用前提Agent Evolution API 当前仅提供 HTTP API位于路由前缀/api/v1/agent-evolution下共两个端点端点方法功能/api/v1/agent-evolution/experiences/trajectoriesGET分页返回成功读取过指定 Experience 的 Trajectory/api/v1/agent-evolution/experiences/outcomesGET统计应用过指定 Experience 的 Trajectory 在五种结果状态下的数量两个查询仅匹配当前调用用户空间内的 Experience 和 Trajectory并强制校验 URI 归属。调用时需携带 API Key请求头X-API-Key或Authorization: Bearer服务默认监听http://localhost:1933。查询 Experience 应用轨迹参数详解参数类型必填默认值说明experience_uristring是-当前用户空间内的 Experience 文件 URIlimitinteger否50单页数量范围为 11000offsetinteger否0从零开始的结果偏移量start_datestring否-Trajectory 创建日期下界包含UTCYYYY-MM-DDend_datestring否-Trajectory 创建日期上界包含UTCYYYY-MM-DD从路由实现openviking/server/routers/agent_evolution.py可以看到limit的上下界11000与offset的非负约束由 FastAPI 的Query(ge..., le...)在参数层强制校验服务层openviking/service/agent_evolution_service.py中的DEFAULT_TRAJECTORY_PAGE_LIMIT 50与MAX_TRAJECTORY_PAGE_LIMIT 1000是这两个边界的真正来源。超出范围会抛出InvalidArgumentError对应 HTTP 400 类错误。调用示例GET /api/v1/agent-evolution/experiences/trajectories?experience_uri{experience_uri}limit50offset0start_date2026-08-01end_date2026-08-10curl -X GET http://localhost:1933/api/v1/agent-evolution/experiences/trajectories?experience_uriviking://user/default/memories/experiences/exchange.mdlimit50offset0start_date2026-08-01end_date2026-08-10 \ -H X-API-Key: your-key响应结构{ status: ok, result: { experience_uri: viking://user/default/memories/experiences/exchange.md, items: [ { uri: viking://user/default/memories/trajectories/exchange_20260805020000.md, name: exchange_20260805020000.md, description: 处理换货请求, created_at: 2026-08-05T02:00:00Z, updated_at: 2026-08-05T02:00:00Z } ], total: 1, limit: 50, offset: 0, has_more: false }, time: 0.01 }响应字段说明items中仅返回索引记录实际存在的uri、name、description、created_at、updated_at五个字段服务层定义了_TRAJECTORY_OUTPUT_FIELDS白名单逐字段取存在值因此旧索引缺少某个字段时不会返回null占位total为符合条件的总记录数与limit/offset无关has_more offset len(items) total用于驱动前端继续翻页结果按updated_at降序排列order_byupdated_at、order_descTrue最新的应用轨迹排在最前。查询 Experience 应用结果分布五种结果状态状态含义success应用成功failure应用失败partial部分成功unknown结果未知unfinished未完成会话中断等这五种状态在源码中定义为元组TRAJECTORY_OUTCOMES (success, failure, partial, unknown, unfinished)见 openviking/session/memory/experience_lineage.py顺序即响应中返回的顺序。注意旧版创建且尚未重新索引的 Trajectory 没有 outcome 标签因此不会计入分布。此外normalize_trajectory_outcome会把任何不在五元组内的值规整为unknown保证聚合口径收敛。调用示例与响应GET /api/v1/agent-evolution/experiences/outcomes?experience_uri{experience_uri}start_date2026-08-01end_date2026-08-10curl -X GET http://localhost:1933/api/v1/agent-evolution/experiences/outcomes?experience_uriviking://user/default/memories/experiences/exchange.mdstart_date2026-08-01end_date2026-08-10 \ -H X-API-Key: your-key{ status: ok, result: { experience_uri: viking://user/default/memories/experiences/exchange.md, outcome_distribution: [ {outcome: success, count: 4}, {outcome: failure, count: 1}, {outcome: partial, count: 0}, {outcome: unknown, count: 0}, {outcome: unfinished, count: 0} ] }, time: 0.01 }结果固定包含全部五种outcome键count 可为 0便于调用方直接按索引或键名消费无需担心缺失项。例如上例中处理换货请求这一经验共被应用 5 次其中 4 次成功、1 次失败可以据此判断该经验是否需要修正或补充。源码级原理精确标量标签聚合不做语义检索只做精确血缘过滤服务层类名AgentEvolutionService的 docstring 明确写着 Serve exact, non-semantic Agent Evolution lineage queries。两次查询都基于同一组精确标量条件见_experience_trajectory_conditionsPathScope(uri, trajectory_root, depth1)限定在当前用户命名空间viking://user/{user_id}/memories/trajectories下一层Eq(context_type, memory)与Eq(level, 2)限定为记忆层级的 L2 轨迹索引Eq(search_tags, experience_source_tag(experience_uri))精确匹配该 Experience 被读取的来源标签可选TimeRange(created_at, ...)按创建时间过滤。其中experience_source_tag会把 Experience URI 编码为形如...1的kv标签由于严格的标签归一化只接受小写URI 中的大写字母、%、等字符会按 UTF-8 逐字节转义为%xx见_escape_search_tag_key从而在标签上无损保留 URI 身份。结果分布查询则在此基础上为五种 outcome 各追加一个Eq(search_tags, trajectory_outcome_tag(outcome))条件即trajectory_outcomesuccess这类标量标签。这意味着查询完全不读取 Trajectory 文件本体仅靠索引中的精确标签做计数与过滤因此对大规模轨迹数据也能保持高效。测试用例 tests/service/test_agent_evolution_service.py 断言了上述过滤器的精确形状包括同一search_tags列表字段上同时叠加来源标签与结果标签test_get_experience_outcome_distribution_counts_two_tags_on_same_list_field。日期过滤的 UTC 边界处理start_date/end_date按 UTCYYYY-MM-DD解析语义为两端都包含。实现细节_trajectory_created_at_range下界映射为当日00:00:0000:00由于底层TimeRange使用排他上界上界会被推进一天再使用。例如end_date2026-08-10实际映射为2026-08-11T00:00:0000:00排他从而在语义上包含 8 月 10 日全天日期必须严格符合YYYY-MM-DDdate.fromisoformat后再比对规范化字符串格式不符或start_date end_date都会以InvalidArgumentError拒绝。对应测试见test_list_trajectories_by_experience_filters_created_at_by_utc_date与test_list_trajectories_by_experience_rejects_invalid_date_range。并发查询与计数轨迹列表asyncio.gather并发执行vikingdb.filter(...)与vikingdb.count(...)一次请求同时拿到当前页数据与总数避免两次串行往返结果分布对五种 outcome并发发起五个vikingdb.count再用zip(..., strictTrue)对齐到TRAJECTORY_OUTCOMES顺序保证响应键序稳定。Experience 读取轨迹是如何产生的血缘标签的写入端在会话提交阶段collect_read_experience_urisopenviking/session/memory/experience_lineage.py遍历提交消息中的工具调用识别所有读取类工具——包括read、multi_read、openviking_read、ov_read及mcp__openviking__(read|multi_read)等 MCP 形态——并只统计工具状态为completed的成功读取。读取失败如输出中出现(nothing found at {uri})或ERROR:标记的 URI 会被剔除。也就是说Agent Evolution 血缘只记录真正读到了内容的经验应用这保证了轨迹列表与结果分布的口径可信。归属与权限校验canonical_experience_uri强制要求 URI 以viking://开头且路径段必须严格匹配[user, user_id, memories, experiences]同时排除.abstract.md、.overview.md、.relations.json等 sidecar 文件。URI 不属于当前用户时例如查询viking://user/bob/...接口会直接以InvalidArgumentError拒绝——对应测试test_list_trajectories_by_experience_rejects_other_user_uri与test_get_experience_outcome_distribution_rejects_other_user_uri。此外Experience URI 若指向目录而非文件同样会被拒绝。全局开关与 SDK 支持Agent Evolution 的生成写入侧由一个部署级开关控制配置于ServerConfigagent-evolution-global-switch-design.md{ server: { agent_evolution: { enabled: false } } }默认值为false。该开关控制会话提交是否允许生成或更新cases、trajectories、experiences三类记忆关闭开关不会删除已有文件也不会阻止已有 Experience 被检索或读取。运行期配置由 openviking/server/agent_evolution_config.py 的AgentEvolutionConfigProvider提供它合并 ov.conf 默认值与账户级持久化覆盖并在配置读取失败时回退到最近一次有效值保证线上行为稳定。在查询侧本文主题这两个端点不受开关影响随时可用于血缘追溯。Go SDK 已提供原生封装sdk/go/agent_evolution.goListExperienceTrajectories(ctx, experienceURI, opts)与GetExperienceOutcomes(ctx, experienceURI, opts)内部等价于上述 HTTP 调用。相关文档会话 - 提交会话并生成 Agent Evolution 记忆cases/trajectories/experiences记忆 - 记忆类型、读取与召回Agent Evolution 全局开关设计 - 部署级开关与提交行为服务层实现 - 查询核心逻辑血缘工具函数 - 标签构造与读取轨迹采集服务层测试 - 过滤器、日期边界与分页行为验证【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking Agent Evolution API 实战：查询 Experience 应用轨迹与结果分布
OpenViking Agent Evolution API 实战查询 Experience 应用轨迹与结果分布【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文围绕 OpenViking 的 Agent Evolution API 展开讲解如何通过 HTTP 接口查询某条 Experience 被 Agent 实际应用后的 Trajectory 记录与五种结果状态分布并结合仓库源码剖析其基于精确标量标签聚合的底层实现。读完本文你将掌握这两个端点的完整参数语义、curl 调用方式、响应解读方法以及 Experience → Trajectory 血缘链路在提交阶段是如何生成、在查询阶段是如何被精确还原的。背景Experience 与 Trajectory 的血缘关系在 OpenViking 中会话提交commit会从对话中抽取长期记忆其中与Agent 进化直接相关的是三种记忆类型cases可训练、可评估的任务案例trajectories可复用的操作契约存放在viking://user/{user_id}/memories/trajectories/experiences可复用的执行经验存放在viking://user/{user_id}/memories/experiences/。记忆的完整类型列表见 记忆 API。Agent Evolution 的核心思想是一条 Experience经验在被实际读取并应用于后续任务后会产生对应的 Trajectory操作轨迹。这条经验被应用的血缘链路lineage记录在会话提交阶段并可通过 Agent Evolution API 反向查询——即给定一条 Experience 的 URI找出哪些 Trajectory 曾成功读取过它以及这些应用最终的结果分布。会话提交如何生成这些记忆可参考 会话 API 中的memory_policy与auto_commit_policy配置。接口概览与调用前提Agent Evolution API 当前仅提供 HTTP API位于路由前缀/api/v1/agent-evolution下共两个端点端点方法功能/api/v1/agent-evolution/experiences/trajectoriesGET分页返回成功读取过指定 Experience 的 Trajectory/api/v1/agent-evolution/experiences/outcomesGET统计应用过指定 Experience 的 Trajectory 在五种结果状态下的数量两个查询仅匹配当前调用用户空间内的 Experience 和 Trajectory并强制校验 URI 归属。调用时需携带 API Key请求头X-API-Key或Authorization: Bearer服务默认监听http://localhost:1933。查询 Experience 应用轨迹参数详解参数类型必填默认值说明experience_uristring是-当前用户空间内的 Experience 文件 URIlimitinteger否50单页数量范围为 11000offsetinteger否0从零开始的结果偏移量start_datestring否-Trajectory 创建日期下界包含UTCYYYY-MM-DDend_datestring否-Trajectory 创建日期上界包含UTCYYYY-MM-DD从路由实现openviking/server/routers/agent_evolution.py可以看到limit的上下界11000与offset的非负约束由 FastAPI 的Query(ge..., le...)在参数层强制校验服务层openviking/service/agent_evolution_service.py中的DEFAULT_TRAJECTORY_PAGE_LIMIT 50与MAX_TRAJECTORY_PAGE_LIMIT 1000是这两个边界的真正来源。超出范围会抛出InvalidArgumentError对应 HTTP 400 类错误。调用示例GET /api/v1/agent-evolution/experiences/trajectories?experience_uri{experience_uri}limit50offset0start_date2026-08-01end_date2026-08-10curl -X GET http://localhost:1933/api/v1/agent-evolution/experiences/trajectories?experience_uriviking://user/default/memories/experiences/exchange.mdlimit50offset0start_date2026-08-01end_date2026-08-10 \ -H X-API-Key: your-key响应结构{ status: ok, result: { experience_uri: viking://user/default/memories/experiences/exchange.md, items: [ { uri: viking://user/default/memories/trajectories/exchange_20260805020000.md, name: exchange_20260805020000.md, description: 处理换货请求, created_at: 2026-08-05T02:00:00Z, updated_at: 2026-08-05T02:00:00Z } ], total: 1, limit: 50, offset: 0, has_more: false }, time: 0.01 }响应字段说明items中仅返回索引记录实际存在的uri、name、description、created_at、updated_at五个字段服务层定义了_TRAJECTORY_OUTPUT_FIELDS白名单逐字段取存在值因此旧索引缺少某个字段时不会返回null占位total为符合条件的总记录数与limit/offset无关has_more offset len(items) total用于驱动前端继续翻页结果按updated_at降序排列order_byupdated_at、order_descTrue最新的应用轨迹排在最前。查询 Experience 应用结果分布五种结果状态状态含义success应用成功failure应用失败partial部分成功unknown结果未知unfinished未完成会话中断等这五种状态在源码中定义为元组TRAJECTORY_OUTCOMES (success, failure, partial, unknown, unfinished)见 openviking/session/memory/experience_lineage.py顺序即响应中返回的顺序。注意旧版创建且尚未重新索引的 Trajectory 没有 outcome 标签因此不会计入分布。此外normalize_trajectory_outcome会把任何不在五元组内的值规整为unknown保证聚合口径收敛。调用示例与响应GET /api/v1/agent-evolution/experiences/outcomes?experience_uri{experience_uri}start_date2026-08-01end_date2026-08-10curl -X GET http://localhost:1933/api/v1/agent-evolution/experiences/outcomes?experience_uriviking://user/default/memories/experiences/exchange.mdstart_date2026-08-01end_date2026-08-10 \ -H X-API-Key: your-key{ status: ok, result: { experience_uri: viking://user/default/memories/experiences/exchange.md, outcome_distribution: [ {outcome: success, count: 4}, {outcome: failure, count: 1}, {outcome: partial, count: 0}, {outcome: unknown, count: 0}, {outcome: unfinished, count: 0} ] }, time: 0.01 }结果固定包含全部五种outcome键count 可为 0便于调用方直接按索引或键名消费无需担心缺失项。例如上例中处理换货请求这一经验共被应用 5 次其中 4 次成功、1 次失败可以据此判断该经验是否需要修正或补充。源码级原理精确标量标签聚合不做语义检索只做精确血缘过滤服务层类名AgentEvolutionService的 docstring 明确写着 Serve exact, non-semantic Agent Evolution lineage queries。两次查询都基于同一组精确标量条件见_experience_trajectory_conditionsPathScope(uri, trajectory_root, depth1)限定在当前用户命名空间viking://user/{user_id}/memories/trajectories下一层Eq(context_type, memory)与Eq(level, 2)限定为记忆层级的 L2 轨迹索引Eq(search_tags, experience_source_tag(experience_uri))精确匹配该 Experience 被读取的来源标签可选TimeRange(created_at, ...)按创建时间过滤。其中experience_source_tag会把 Experience URI 编码为形如...1的kv标签由于严格的标签归一化只接受小写URI 中的大写字母、%、等字符会按 UTF-8 逐字节转义为%xx见_escape_search_tag_key从而在标签上无损保留 URI 身份。结果分布查询则在此基础上为五种 outcome 各追加一个Eq(search_tags, trajectory_outcome_tag(outcome))条件即trajectory_outcomesuccess这类标量标签。这意味着查询完全不读取 Trajectory 文件本体仅靠索引中的精确标签做计数与过滤因此对大规模轨迹数据也能保持高效。测试用例 tests/service/test_agent_evolution_service.py 断言了上述过滤器的精确形状包括同一search_tags列表字段上同时叠加来源标签与结果标签test_get_experience_outcome_distribution_counts_two_tags_on_same_list_field。日期过滤的 UTC 边界处理start_date/end_date按 UTCYYYY-MM-DD解析语义为两端都包含。实现细节_trajectory_created_at_range下界映射为当日00:00:0000:00由于底层TimeRange使用排他上界上界会被推进一天再使用。例如end_date2026-08-10实际映射为2026-08-11T00:00:0000:00排他从而在语义上包含 8 月 10 日全天日期必须严格符合YYYY-MM-DDdate.fromisoformat后再比对规范化字符串格式不符或start_date end_date都会以InvalidArgumentError拒绝。对应测试见test_list_trajectories_by_experience_filters_created_at_by_utc_date与test_list_trajectories_by_experience_rejects_invalid_date_range。并发查询与计数轨迹列表asyncio.gather并发执行vikingdb.filter(...)与vikingdb.count(...)一次请求同时拿到当前页数据与总数避免两次串行往返结果分布对五种 outcome并发发起五个vikingdb.count再用zip(..., strictTrue)对齐到TRAJECTORY_OUTCOMES顺序保证响应键序稳定。Experience 读取轨迹是如何产生的血缘标签的写入端在会话提交阶段collect_read_experience_urisopenviking/session/memory/experience_lineage.py遍历提交消息中的工具调用识别所有读取类工具——包括read、multi_read、openviking_read、ov_read及mcp__openviking__(read|multi_read)等 MCP 形态——并只统计工具状态为completed的成功读取。读取失败如输出中出现(nothing found at {uri})或ERROR:标记的 URI 会被剔除。也就是说Agent Evolution 血缘只记录真正读到了内容的经验应用这保证了轨迹列表与结果分布的口径可信。归属与权限校验canonical_experience_uri强制要求 URI 以viking://开头且路径段必须严格匹配[user, user_id, memories, experiences]同时排除.abstract.md、.overview.md、.relations.json等 sidecar 文件。URI 不属于当前用户时例如查询viking://user/bob/...接口会直接以InvalidArgumentError拒绝——对应测试test_list_trajectories_by_experience_rejects_other_user_uri与test_get_experience_outcome_distribution_rejects_other_user_uri。此外Experience URI 若指向目录而非文件同样会被拒绝。全局开关与 SDK 支持Agent Evolution 的生成写入侧由一个部署级开关控制配置于ServerConfigagent-evolution-global-switch-design.md{ server: { agent_evolution: { enabled: false } } }默认值为false。该开关控制会话提交是否允许生成或更新cases、trajectories、experiences三类记忆关闭开关不会删除已有文件也不会阻止已有 Experience 被检索或读取。运行期配置由 openviking/server/agent_evolution_config.py 的AgentEvolutionConfigProvider提供它合并 ov.conf 默认值与账户级持久化覆盖并在配置读取失败时回退到最近一次有效值保证线上行为稳定。在查询侧本文主题这两个端点不受开关影响随时可用于血缘追溯。Go SDK 已提供原生封装sdk/go/agent_evolution.goListExperienceTrajectories(ctx, experienceURI, opts)与GetExperienceOutcomes(ctx, experienceURI, opts)内部等价于上述 HTTP 调用。相关文档会话 - 提交会话并生成 Agent Evolution 记忆cases/trajectories/experiences记忆 - 记忆类型、读取与召回Agent Evolution 全局开关设计 - 部署级开关与提交行为服务层实现 - 查询核心逻辑血缘工具函数 - 标签构造与读取轨迹采集服务层测试 - 过滤器、日期边界与分页行为验证【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考