UpdateContextStore - 修改上下文库配置-Agent 观测与优化 AgentLoop(AgentLoop)-阿里云帮助中心

修改上下文库配置

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

agentloop:UpdateContextStore

update

*ContextStore

acs:agentloop:{#regionId}:{#accountId}:agentspace/{#AgentSpaceName}/contextstore/{#ContextStoreName}

无

请求语法

PUT /agentspace/{agentSpace}/contextstore/{contextStoreName} HTTP/1.1

路径参数

名称	类型	必填	描述	示例值
agentSpace	string	是	AgentSpace 名称，长度 2-64 字符	my-agent-space
contextStoreName	string	是	待更新的上下文库名称，长度 2-64 字符	my-context-store

请求参数

名称	类型	必填	描述	示例值
body	object	否	请求体
changeNote	string	否	策略变更说明；config 中策略字段有变化时写入新策略版本	放宽相似度阈值
config	object	否	上下文库配置，传入即整体覆盖；不传则保持原配置
audit	object	否	审计配置
droppedCandidates	boolean	否	召回被丢弃的候选是否也写 item 事件，默认 false	false
queryMode	string	否	召回 query 记录方式：raw（明文）/ hash（仅 HMAC），默认 raw	raw
retentionDays	integer	否	审计日志保留天数，取值 1-180，默认 30	30
extractionPolicy	object	否	抽取策略（memory 类型）
categories	array	否	记忆分类列表	["preference","profile"]
	string	否	分类名	preference
customInstructions	string	否	自定义抽取指令，preset=custom 时必填，长度 1-8000	只抽取用户的产品偏好
excludeRules	array	否	排除规则列表，命中的内容不抽取	["密码","证件号"]
	string	否	排除规则	密码
model	object	否	抽取模型配置
name	string	否	抽取模型名称，当前仅支持 qwen3.8-flash，使用平台内部凭据	qwen3.8-flash
preset	string	否	预设策略：fact / toc-profile / tob-digital-twin / custom，默认 fact	fact
metadataField	object	否	元数据字段映射，key 为业务字段，value 为存储字段	{"userId":"user_id","sessionId":"session_id"}
	string	否
scopePolicy	object	否	scope 约束策略
requiredAnyOf	array	否	至少需要其中一个 scope 字段非空；元素取值 userId / agentId / appId / runId	["userId"]
	string	否	scope 字段名	userId
source	object	否	数据源配置，仅作为数据源根标识
agentSpace	string	否	trace 数据源所在的 AgentSpace；本期不支持跨 AgentSpace，若传入必须等于 path AgentSpace，否则返回 400 参数错误。AgentSpace 创建后不可变更	my-agent-space
dataset	object	否	Dataset 数据源可更新项（datasetName 创建后不可变更）
customFields	array<object>	否	自定义字段声明列表，传入即整体覆盖
	object	否	自定义字段声明
description	string	否	字段说明，usage=extraction-input 时必填	客户等级
sensitive	boolean	否	是否敏感字段	false
sourceField	string	否	源字段名	customerTier
target	string	否	写入目标路径，例如 metadata.customerTier	metadata.customerTier
usage	string	否	用途：extraction-input（参与抽取）/ ignore（忽略）	extraction-input
filter	object	否	行过滤条件
where	string	否	Pipeline where 子集，下推到 SQL	appId = 'crm-service'
pollIntervalSeconds	integer	否	轮询间隔秒数，取值 60-3600	300
startTime	string	否	数据回灌起始时间，ISO 8601 UTC 格式	2026-01-01T00:00:00Z
trajectory	object	否	轨迹数据源可更新项（source.type 创建后不可变更）
filter	object	否	轨迹过滤条件；各条件之间 AND，列表内 OR
agentNames	array	否	Agent 名列表；显式空列表返回 400	["sales-copilot"]
	string	否	Agent 名	sales-copilot
excludeDegraded	boolean	否	是否排除 degraded 轨迹，默认 false（包含降级轨迹）	false
minStepCount	integer	否	最小步数，大于等于 0	2
query	string	否	原生 SLS 检索语句，与以上条件 AND	tool_names:"search_order"
serviceNames	array	否	服务名列表，支持单尾缀 *；显式空列表返回 400	["crm-service","app-*"]
	string	否	服务名	crm-service
logstore	string	否	轨迹 Logstore 名称，默认 agent-trajectory；创建后不可变更	agent-trajectory
pollIntervalSeconds	integer	否	轮询间隔秒数，取值 60-3600	300
scopeMapping	object	否	scope 字段映射，值为 JSONPath（仅支持 $.a.b 与 $.a[0] 形式）
agentId	string	否	agentId 的 JSONPath，默认 $.agent_name	$.agent_name
appId	string	否	appId 的 JSONPath，默认 $.service_names[0]	$.service_names[0]
runId	string	否	runId 的 JSONPath，默认 $.trajectory_id	$.trajectory_id
userId	string	否	userId 的 JSONPath；缺省不映射	$.trajectory_extensions.user_id
storagePolicy	object	否	存储策略（memory 类型）
allowedActions	array	否	允许的存储动作，默认全部：ADD / UPDATE / MERGE / DELETE	["ADD","UPDATE","MERGE","DELETE"]
	string	否	动作	ADD
dedupe	boolean	否	event 模式是否去重，默认 true	true
humanEditProtection	boolean	否	人工编辑保护，默认 true；开启后自动抽取不覆盖人工修改过的记忆	true
mergeKey	string	否	upsert 合并键：factKey / semantic / both，默认 semantic	semantic
mode	string	否	存储模式：event（事件追加）/ upsert（合并更新），默认 upsert	upsert
similarityThreshold	number	否	语义合并相似度阈值，取值 0-1，默认 0.4	0.4
ttlDays	integer	否	记忆过期天数，0 表示不过期	0
contextType	string	否	上下文库类型；创建后通常不可变更，提供该字段仅用于异常修正	experience
description	string	否	上下文库描述，便于业务方理解用途	我的上下文库
status	string	否	运行状态：memory 类型为 Active（运行）/ Paused（暂停数据源消费与抽取）；experience 类型为经验库挖掘状态，具体合法值及组合约束由服务端定义	Active
clientToken	string	否	幂等 Token，客户端生成的唯一字符串，保证更新操作幂等	a1b2c3d4-1234-5678-90ab-cdef12345678

返回参数

名称	类型	描述	示例值
	object	响应数据
requestId	string	请求 Id，用于排查问题时定位本次请求	9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M
strategyVersion	integer	更新后生效的策略版本号（memory 类型）；策略未变化时与更新前相同	2

示例

正常返回示例

JSON格式

{
  "requestId": "9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M",
  "strategyVersion": 2
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。