UpdateContextStore-AgentLoop(AgentLoop)-阿里云帮助中心

Updates the context store configuration.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

agentloop:UpdateContextStore

update

*ContextStore

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

None

Request syntax

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

Path Parameters

Parameter	Type	Required	Description	Example
agentSpace	string	Yes	The name of the AgentSpace. The name must be 2 to 64 characters in length.	my-agent-space
contextStoreName	string	Yes	The name of the context store to be updated. The name must be 2 to 64 characters in length.	my-context-store

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The request body.
description	string	No	The description of the context store, which helps business users understand its purpose.	My context store
config	object	No	The context library configuration. If specified, the entire configuration is overwritten. If not specified, the original configuration is retained.
runtimeRecallEnabled	boolean	No	Specifies whether runtime recall is enabled for the experience library. When modifying this property, you must pass expectedRuntimeRecallRevision and submit only this property in the config.
metadataField	object	No	The metadata field mapping. The key is the business field and the value is the storage field.	{"userId":"user_id","sessionId":"session_id"}
	string	No	The name of the storage field in the metadata field mapping.	user_id
source	object	No	The datasource config. This serves only as the root identity for the datasource.
startTime	string	No	The start time for data backfill in ISO 8601 UTC format.	2026-01-01T00:00:00Z
agentSpace	string	No	The AgentSpace where the trace data source is located. Cross-AgentSpace operations are not supported in the current version. If specified, the value must be equal to the path AgentSpace. Otherwise, a 400 parameter error is returned. The AgentSpace cannot be changed after creation.	my-agent-space
trajectory	object	No	The updatable items for the trajectory data source. The source.type cannot be changed after creation.
logstore	string	No	The name of the trajectory Logstore. Default value: agent-trajectory. This cannot be changed after creation.	agent-trajectory
filter	object	No	The trajectory filter conditions. Conditions are combined with AND, while items within a list are combined with OR.
serviceNames	array	No	The list of service names. A single trailing asterisk (*) is supported. An explicitly empty list returns a 400 error.	["crm-service","app-*"]
	string	No	The service name.	crm-service
agentNames	array	No	The list of agent names. An explicitly empty list returns a 400 error.	["sales-copilot"]
	string	No	The agent name.	sales-copilot
minStepCount	integer	No	The minimum number of steps. The value must be greater than or equal to 0.	2
excludeDegraded	boolean	No	Specifies whether to exclude degraded trajectories. Default value: false, which includes degraded trajectories.	false
query	string	No	The native Simple Log Service (SLS) query statement. This is combined with the preceding conditions using AND.	tool_names:"search_order"
scopeMappingVersion	integer	No	The default mapping version for trajectory identity. Version 1 retains the legacy rules. Version 2 reads user.id or enduser.id from agent attributes. The version is frozen upon creation.	2
scopeMapping	object	No	The scope field mapping. Dot paths, array subscripts, and quoted property keys are supported. An empty string indicates no mapping.
userId	string	No	The JSONPath for userId. By default, version 1 does not map this field, and version 2 sequentially retrieves user.id and enduser.id from agent attributes.	$.trajectory_extensions.user_id
agentId	string	No	The JSONPath for agentId. Default value: $.agent_name.	$.agent_name
appId	string	No	The JSONPath for appId. Default value: $.service_names[0].	$.service_names[0]
runId	string	No	The JSONPath for runId. By default, this field is not mapped to prevent memory isolation by a single trajectory.	$.trajectory_id
pollIntervalSeconds	integer	No	The polling interval in seconds. Valid values: 60 to 3600.	300
dataset	object	No	The updatable items for the dataset data source. The datasetName cannot be changed after creation.
filter	object	No	The row filter conditions.
where	string	No	The subset of the pipeline where clause, which is pushed down to SQL.	appId = 'crm-service'
customFields	array<object>	No	The list of custom field declarations. If specified, the entire list is overwritten.
	object	No	The custom field declaration.
sourceField	string	No	The name of the source field.	customerTier
usage	string	No	The usage of the field. Valid values: extraction-input (participates in extraction) and ignore (ignored).	extraction-input
target	string	No	The target path for writing data, such as metadata.customerTier.	metadata.customerTier
description	string	No	The description of the field. This is required when usage is set to extraction-input.	Customer tier
sensitive	boolean	No	Specifies whether the field is sensitive.	false
pollIntervalSeconds	integer	No	The polling interval in seconds. Valid values: 60 to 3600.	300
extractionPolicy	object	No	The extraction policy for the memory type.
preset	string	No	The preset policy. Valid values: fact, toc-profile, tob-digital-twin, and custom. Default value: fact.	fact
customInstructions	string	No	The custom extraction instructions. This is required when preset is set to custom. The length must be 1 to 8,000 characters.	Extract only user product preferences
categories	array	No	The list of memory categories.	["preference","profile"]
	string	No	The category name.	preference
excludeRules	array	No	The list of exclude rules. Content that matches these rules is not extracted.	["Password","ID number"]
	string	No	The exclude rule.	Password
model	object	No	The extraction model configuration.
name	string	No	The name of the extraction model. Currently, only qwen3.8-flash is supported, which uses internal platform credentials. Valid values: qwen3.8-flash	qwen3.8-flash
extractionPolicies	array<object>	No	The list of extraction policies. You can specify 1 to 10 policies. During an update, compatible fields returned as-is are ignored. The strategyVersion field indicates the snapshot version of the overall database configuration.
	array<object>	No	The independent extraction policy.
strategyId	string	No	The ID of the extraction policy. This parameter is optional. If omitted, the default value is default. The ID must start with a letter and can contain only letters, digits, underscores, and hyphens. It can be up to 64 characters in length. After default processing, the ID must be unique within the same database. Modifying the name or instructions does not change this ID.	preferences
name	string	No	The display name of the extraction policy.	User preferences
enabled	boolean	No	Specifies whether to execute this policy for new input. Default value: true. Disabling the policy does not delete historical memories.	true
preset	string	No	The preset policy. Valid values: fact, toc-profile, tob-digital-twin, and custom. Default value: fact.	fact
customInstructions	string	No	The custom extraction instructions. This is required when preset is set to custom. The length must be 1 to 8,000 characters.	Extract only user product preferences
categories	array	No	The list of memory categories.	["preference","profile"]
	string	No	The category name.	preference
excludeRules	array	No	The list of exclude rules. Content that matches these rules is not extracted.	["Password","ID number"]
	string	No	The exclude rule.	Password
model	object	No	The extraction model configuration.
name	string	No	The name of the extraction model. Currently, only qwen3.8-flash is supported, which uses internal platform credentials. Valid values: qwen3.8-flash	qwen3.8-flash
storagePolicy	object	No	The independent storage rules for this policy. If omitted, the original value is retained. New policies use the default value. By default, the validity period is refreshed for repeatedly confirmed memories.
mode	string	No	The storage mode. Valid values: event: event append upsert: merge and update Default value: upsert.	upsert
mergeKey	string	No	The merge key for the upsert mode. Valid values: factKey semantic both Default value: semantic.	semantic
similarityThreshold	number	No	The similarity threshold for semantic merging. Valid values: 0 to 1. Default value: 0.4.	0.4
allowedActions	array	No	The allowed storage actions. By default, all actions are allowed, including ADD, UPDATE, MERGE, and DELETE.	["ADD","UPDATE","MERGE","DELETE"]
	string	No	The action.	ADD
dedupe	boolean	No	Specifies whether to enable deduplication in event mode. Default value: true.	true
humanEditProtection	boolean	No	Specifies whether to enable manual edit protection. Default value: true. When enabled, automatic extraction does not overwrite manually modified memories.	true
ttlDays	integer	No	The number of days before a memory expires. A value of 0 indicates that the memory does not expire.	0
storagePolicy	object	No	The storage policy for the memory type.
mode	string	No	The storage mode. Valid values: event: event append upsert: merge and update Default value: upsert.	upsert
mergeKey	string	No	The merge key for the upsert mode. Valid values: factKey semantic both Default value: semantic.	semantic
similarityThreshold	number	No	The similarity threshold for semantic merging. Valid values: 0 to 1. Default value: 0.4.	0.4
allowedActions	array	No	The allowed storage actions. By default, all actions are allowed, including ADD, UPDATE, MERGE, and DELETE.	["ADD","UPDATE","MERGE","DELETE"]
	string	No	The action.	ADD
dedupe	boolean	No	Specifies whether to enable deduplication in event mode. Default value: true.	true
humanEditProtection	boolean	No	Specifies whether to enable manual edit protection. Default value: true. When enabled, automatic extraction does not overwrite manually modified memories.	true
ttlDays	integer	No	The number of days before a memory expires. A value of 0 indicates that the memory does not expire.	0
scopePolicy	object	No	The scope constraint policy.
requiredAnyOf	array	No	At least one scope field must be non-empty. Valid element values are userId, agentId, appId, and runId.	["userId"]
	string	No	The scope field name.	userId
audit	object	No	The audit configuration.
retentionDays	integer	No	The number of days to retain audit logs. Valid values: 1 to 180. Default value: 30.	30
queryMode	string	No	The method used to record retrieved queries. Valid values: raw (plaintext) and hash (HMAC only). Default value: raw.	raw
droppedCandidates	boolean	No	Specifies whether to write item events for dropped candidates during retrieval. Default value: false.	false
contextType	string	No	The context library type. It is generally immutable after creation and is provided only for exception correction.	experience
expectedRuntimeRecallRevision	integer	No	Required when modifying the runtime recall switch. The value must be equal to the config.runtimeRecallRevision value returned by GetContextStore. A conflict returns a 409 error.	1
reason	string	No	The audit reason for modifying the runtime recall switch. The maximum length is 2,000 characters.	Suspend runtime recall while adjusting experience content
status	string	No	The mining status of the experience library. This field applies only to the experience type. The specific valid values and combination constraints are defined by the server.	Paused
changeNote	string	No	The description of the policy change. A new policy version is created when policy fields in the config are modified.	Relax the similarity threshold
clientToken	string	No	The idempotency token. This is a unique string generated by the client to ensure the idempotence of the update operation.	a1b2c3d4-1234-5678-90ab-cdef12345678

Response elements

Element	Type	Description	Example
	object	The response data.
config	object	The attributes returned after the runtime recall switch is updated. This block is not returned for other library update operations.
runtimeRecallEnabled	boolean	Specifies whether runtime recall is allowed after the experience library is updated.
runtimeRecallRevision	integer	The version of the runtime recall attributes that takes effect after the current update.	1
requestId	string	The request ID. It is used to locate the request when you troubleshoot issues.	9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M
strategyVersion	integer	The strategy version number that takes effect after the update for the memory type. If the strategy remains unchanged, the version is the same as the one before the update.	2

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.