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

Creates a context store.

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:CreateContextStore

create

*ContextStore

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

None

Request syntax

POST /agentspace/{agentSpace}/contextstore 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

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The request body.
contextStoreName	string	Yes	The name of the context store. The name must be globally unique within the AgentSpace and 2 to 64 characters in length.	my-context-store
contextType	string	Yes	The type of the context store. Example values include experience (experience store) and memory (memory store).	experience
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, including data sources and metadata field mappings.
source	object	No	The datasource config, which serves only as the root identity for the data source. This is an optional block.
type	string	No	The data source type for the memory type. Valid values: trajectory and dataset. If this parameter is not specified, the value is manual, which means data is written only through AddContexts. This parameter cannot be modified after creation.	trajectory
datasetName	string	No	The name of the dataset source for the experience. The dataset must reside in the current AgentSpace. This parameter is provided only when the source type is dataset for an experience.	reviewed_trajectories
format	string	No	The input format of the dataset. For dataset sources in the experience library, only atif is supported, and the fixed columns are the same as those in optimization tasks.	atif
binding	object	No	The DatasetBinding v1 shared with optimization tasks. It includes version, selection (all/window and structured filters), and customFields. It is validated by the server and does not accept SQL or column mappings.	{"version":1,"selection":{"mode":"all"}}
maxRecords	integer	No	The maximum number of records to read per batch from the dataset. Valid values: 1 to 1000. Default value: 1000. In manual mode, exceeding the limit causes a failure. In follow mode, bounded pagination is used to continue consumption.	1000
versionPolicy	object	No	The continuous consumption configuration for datasets in the native experience library. The default mode is manual. The follow mode only allows binding.selection.mode=all and consumes data by append sequence number. This configuration cannot be modified after creation.
mode	string	No	The continuous consumption mode. The value is fixed to follow.	follow
startSeq	string	No	The initial consumed append sequence number. It is a decimal string of a non-negative int64 value. Default value: 0. The __dataset_seq field is used, and the business timestamp is not used as the consumption checkpoint.	0
agentSpace	string	No	The AgentSpace where the trace data source resides. If this parameter is not specified, the default value is the AgentSpace in the current path. Cross-AgentSpace is not supported in the current phase. If specified, the value must be the same as the path AgentSpace. Otherwise, a 400 parameter error is returned. This parameter cannot be modified after creation.	my-agent-space
startTime	string	No	The start time for data backfill in ISO 8601 UTC format. If this parameter is not specified, the backfill starts from the current time.	2026-01-01T00:00:00Z
trajectory	object	No	The trajectory datasource config. This parameter is required when the source type is trajectory.
logstore	string	No	The name of the trajectory Logstore. Default value: agent-trajectory. This parameter cannot be modified after creation.	agent-trajectory
startTime	string	No	The start time for trajectory consumption in ISO 8601 UTC format. If this parameter is not specified, the default value is the creation time.	2026-10-01T00:00:00Z
filter	object	No	The trajectory filter conditions. Conditions are combined with AND, and 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 means degraded trajectories are included.	false
query	string	No	The native Simple Log Service (SLS) query statement. It is combined with the preceding conditions using AND.	tool_names:"search_order"
scopeMappingVersion	integer	No	The default mapping version for the trajectory identity. Version 1 retains the legacy rules. Version 2 reads user.id and enduser.id from agent attributes. The version is frozen upon creation.	2
scopeMapping	object	No	The scope field mapping. The value is a JSONPath expression, and only the $.a.b and $.a[0] formats are supported.
userId	string	No	The JSONPath for userId. By default, no mapping is applied.	$.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. Default value: $.trajectory_id.	$.trajectory_id
pollIntervalSeconds	integer	No	The polling interval in seconds. Valid values: 60 to 3600. Default value: 300.	300
dataset	object	No	The dataset datasource config. This parameter is required when the source type is dataset.
datasetName	string	No	The name of the dataset in the same AgentSpace. This parameter cannot be modified after creation.	trajectory-with-crm-profile
schemaContract	string	No	The row schema contract for the dataset. In the current phase, the value is fixed to MemorySourceV1.	MemorySourceV1
versionPolicy	object	No	The version consumption policy for the dataset.
mode	string	No	The version consumption mode. Valid values: follow, which consumes data incrementally by __dataset_seq, and fixed, which consumes the specified ACTIVE version in full at once.	follow
startSeq	integer	No	The start __dataset_seq for the follow mode.	0
version	string	No	The dataset version specified for the fixed mode.	v3
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.
	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 write path, such as metadata.customerTier.	metadata.customerTier
description	string	No	The description of the field. This parameter is required when usage is set to extraction-input and is appended to the extraction prompt.	Customer tier
sensitive	boolean	No	Specifies whether the field is a sensitive field.	false
pollIntervalSeconds	integer	No	The polling interval in seconds. Valid values: 60 to 3600. Default value: 300.	300
serviceNames	array	No	The list of service names. This parameter is required and cannot be empty. It works with source.agentSpace to locate the trace data source. The trajectory extraction service uses agentSpace to query the bound CMS workspace and project/logstore, and then filters the data by serviceName. This parameter cannot be modified after creation (no modification entry is available in the current release).	["order-service","payment-service"]
	string	No	The service name.	order-service
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
miningInterval	string	No	The experience mining interval, which controls how often experience mining is executed. Valid values: 1h, 6h, 12h, and 1d. Default value: 1d. This parameter cannot be modified after creation. Valid values: 1h 6h 12h 1d	1d
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 parameter 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 name of the category.	preference
excludeRules	array	No	The list of exclusion rules. Content that matches the rules is not extracted.	["Password","ID number"]
	string	No	The exclusion rule.	Password
model	object	No	The configuration of the extraction model.
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. Compatible fields returned as-is during updates are ignored. strategyVersion indicates the snapshot version of the entire 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 value 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 parameter 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 name of the category.	preference
excludeRules	array	No	The list of exclusion rules. Content that matches the rules is not extracted.	["Password","ID number"]
	string	No	The exclusion rule.	Password
model	object	No	The configuration of the extraction model.
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 rule for this policy. If omitted, the original value is retained. New policies use the default value. Repeatedly confirmed memories refresh the validity period by default.
mode	string	No	The storage mode. Valid values: event (event append) and upsert (merge and update). Default value: upsert.	upsert
mergeKey	string	No	The upsert merge key. Valid values: factKey, semantic, and both. Default value: semantic.	semantic
similarityThreshold	number	No	The semantic merge similarity threshold. Valid values: 0 to 1. Default value: 0.4.	0.4
allowedActions	array	No	The allowed storage actions. Default value: all. Valid values: 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 human edit protection. Default value: true. If 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) and upsert (merge and update). Default value: upsert.	upsert
mergeKey	string	No	The upsert merge key. Valid values: factKey, semantic, and both. Default value: semantic.	semantic
similarityThreshold	number	No	The semantic merge similarity threshold. Valid values: 0 to 1. Default value: 0.4.	0.4
allowedActions	array	No	The allowed storage actions. Default value: all. Valid values: 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 human edit protection. Default value: true. If 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	The list of scope fields where at least one must be non-empty. Valid values for elements: userId, agentId, appId, and runId.	["userId"]
	string	No	The name of the scope field.	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 recording mode for retrieval queries. Valid values: raw (plaintext) and hash (HMAC only). Default value: raw.	raw
droppedCandidates	boolean	No	Specifies whether to write item events for dropped retrieval candidates. Default value: false.	false
clientToken	string	No	The idempotency token, a unique string generated by the client to ensure the idempotency of the creation operation.	a1b2c3d4-1234-5678-90ab-cdef12345678

Response elements

Element	Type	Description	Example
	object	The response data.
requestId	string	The request ID, used to locate the request during troubleshooting.	9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M
strategyVersion	integer	The version number of the currently effective policy (memory type).	1

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.