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

Queries the 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:GetContextStore

get

*ContextStore

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

None

Request syntax

GET /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. The name must be 2 to 64 characters in length.	my-context-store

Request parameters

Parameter

Type

Required

Description

Example

No parameters required.

Response elements

Element	Type	Description	Example
	object	The response data.
requestId	string	The request ID, which is used to locate the request during troubleshooting.	9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M
contextStoreName	string	The name of the context store.	my-context-store
agentSpace	string	The name of the AgentSpace to which the context store belongs.	my-agent-space
regionId	string	The region ID of the context store.	cn-hangzhou
contextType	string	The type of the context store, such as experience (experience store) or memory (memory store).	experience
description	string	The description of the context store.	My context store
status	string	The status of the context store. Valid values: ACTIVE, INITIALIZING, and FAILED.	ACTIVE
config	object	The configuration of the context store.
auditLogStore	object	The location of the Simple Log Service (SLS) audit logs for the experience store, which is read by the console by using the existing GetLogs permission.
project	string	The name of the SLS project where the audit logs of the experience store are stored.	agentloop-xxx
logstore	string	The name of the Logstore for the audit logs of the experience store.	experience_audit
runtimeRecallEnabled	boolean	Specifies whether runtime recall is allowed for the experience store. This parameter is returned only for the experience type.
runtimeRecallRevision	integer	The version of the runtime recall property, which is read-only. When you update the switch, a concurrency check is performed by using expectedRuntimeRecallRevision.	1
innerSource	object	The system-assigned coordinates of the event Logstore for the memory type, which is located in the SLS project bound to the AgentSpace.
project	string	The name of the SLS project.	agentloop-xxx
logstore	string	The name of the event Logstore.	memory_events_0a1b2c3d
source	object	The datasource config passed by the user, which serves only as the root identity of the data source.
type	string	The source type, which can be trajectory or dataset. For the experience type, if this parameter is not passed, trajectory is used. For Dataset, the datasetName, format, and binding at this level are used. The default is manual, and versionPolicy.mode=follow continuously processes and automatically applies to the experience store. For the memory type, if this parameter is not passed, it indicates manual (only AddContexts writes). Otherwise, the trajectory or dataset sub-configuration with the same name is used. This parameter cannot be changed after creation.	dataset
datasetName	string	The name of the source dataset for the experience type in the current AgentSpace.	reviewed_trajectories
format	string	The input format of the dataset. For the experience store, the dataset source is atif.	atif
binding	object	The DatasetBinding v1 shared with the optimization task, which retains fixed column validation, supplementary column usage, and all or window selection.	{"version":1,"selection":{"mode":"all"}}
maxRecords	integer	The maximum number of records read in a single dataset operation. Valid values: 1 to 1000.	1000
versionPolicy	object	The continuous consumption configuration for the native experience store dataset. The default is manual. The follow mode only allows binding.selection.mode=all and consumes by append sequence number. This parameter cannot be changed after creation.
mode	string	The continuous consumption mode, which is fixed to follow.	follow
startSeq	string	The initial consumed append sequence number, which is a decimal string of a non-negative int64. Default value: 0. The __dataset_seq field is used, and the business timestamp is not used as the consumption checkpoint.	0
agentSpace	string	The AgentSpace where the trace data source is located, which is the same as the AgentSpace to which it belongs upon creation.	my-agent-space
startTime	string	The start time for data backfilling, in ISO 8601 UTC format.	2026-01-01T00:00:00Z
trajectory	object	The trajectory datasource config for the memory type. This parameter is required when the type is memory and source.type is trajectory.
logstore	string	The name of the trajectory Logstore. Default value: agent-trajectory. This parameter cannot be changed after creation.	agent-trajectory
startTime	string	The start time for trajectory consumption, in ISO 8601 UTC format. If not specified, the default is the creation time.	2026-10-01T00:00:00Z
filter	object	The trajectory filter conditions. Conditions are combined with AND, and items within a list are combined with OR.
serviceNames	array	The list of service names. A single trailing asterisk (*) is supported. An explicitly empty list returns a 400 error.	["crm-service","app-*"]
	string	The name of the service.	crm-service
agentNames	array	The list of agent names. An explicitly empty list returns a 400 error.	["sales-copilot"]
	string	The name of the agent.	sales-copilot
minStepCount	integer	The minimum number of steps, which must be greater than or equal to 0.	2
excludeDegraded	boolean	Specifies whether to exclude degraded trajectories. Default value: false, which means degraded trajectories are included.	false
query	string	The native SLS query statement, which is combined with the preceding conditions using AND.	tool_names:"search_order"
scopeMappingVersion	integer	The default mapping version for trajectory identity. Valid values: 1: Retains legacy rules. 2: Reads user.id or enduser.id from agent attributes. The version is frozen upon creation.	2
scopeMapping	object	The scope field mapping. Dot paths, array indices, and quoted property keys are supported. An empty string indicates no mapping.
userId	string	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	The JSONPath for agentId. Default value: $.agent_name.	$.agent_name
appId	string	The JSONPath for appId. Default value: $.service_names[0].	$.service_names[0]
runId	string	The JSONPath for runId. By default, this field is not mapped to prevent memory isolation by a single trajectory.	$.trajectory_id
pollIntervalSeconds	integer	The polling interval in seconds. Valid values: 60 to 3600. Default value: 300.	300
dataset	object	The Dataset datasource config for the memory type. This parameter is required when the memory type is used and source.type is set to dataset.
datasetName	string	The name of the dataset in the same AgentSpace. This parameter cannot be modified after creation.	trajectory-with-crm-profile
schemaContract	string	The row schema contract of the dataset. The value is fixed to MemorySourceV1 in the current phase.	MemorySourceV1
versionPolicy	object	The version consumption policy of the dataset.
mode	string	The version consumption mode. Valid values: follow: Consumes data incrementally based on __dataset_seq. fixed: Consumes the specified ACTIVE version in full at once.	follow
startSeq	integer	The starting __dataset_seq for the follow mode.	0
version	string	The dataset version specified for the fixed mode.	v3
filter	object	The row filter conditions.
where	string	The subset of the pipeline where clause, which is pushed down to SQL.	appId = 'crm-service'
customFields	array<object>	The list of custom field declarations.
	object	The custom field declaration.
sourceField	string	The name of the source field.	customerTier
usage	string	The usage of the field. Valid values: extraction-input: Participates in extraction. ignore: Ignored.	extraction-input
target	string	The target write path, such as metadata.customerTier.	metadata.customerTier
description	string	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	Specifies whether the field is a sensitive field.	false
pollIntervalSeconds	integer	The polling interval in seconds. Valid values: 60 to 3600. Default value: 300.	300
miningTaskName	string	The name of the internal running task associated with the server. Continuous databases use this for read-only viewing of consumption records, while manual databases can run limited mining. This value is not inferred by the client and cannot replace the ingestion and recall criteria of the native experience database.	experience-review-library
serviceNames	array	The list of service names, which works with source.agentSpace to locate the trace data source. This parameter cannot be modified in the current phase.	["order-service","payment-service"]
	string	The name of the service.	order-service
metadataField	object	The metadata field mapping. The key is the business field and the value is the storage field.	{"userId":"user_id","sessionId":"session_id"}
	string	The name of the storage field in the metadata field mapping.	user_id
miningInterval	string	The experience mining interval. Valid values: 1h, 6h, 12h, and 1d. Default value: 1d. Valid values: 1h 6h 12h 1d	1d
extractionPolicy	object	The extraction policy for the memory type.
preset	string	The preset policy. Valid values: fact, toc-profile, tob-digital-twin, and custom. Default value: fact.	fact
customInstructions	string	The custom extraction instructions. This parameter is required when preset is set to custom. Length: 1 to 8000 characters.	Extract only user product preferences
categories	array	The list of memory categories.	["preference","profile"]
	string	The name of the category.	preference
excludeRules	array	The list of exclusion rules. Content that matches these rules is not extracted.	["Password", "ID number"]
	string	The exclusion rule.	Password
model	object	The configuration of the extraction model.
name	string	The name of the extraction model. Currently, only qwen3.8-flash is supported, and internal platform credentials are used. Valid values: qwen3.8-flash	qwen3.8-flash
extractionPolicies	array<object>	The extraction policies. A total of 1 to 10 policies can be configured. The strategyVersion field indicates the snapshot version of the global configuration.
	array<object>	The extraction policy.
strategyId	string	The stable ID of the extraction policy. It must start with a letter and can contain only letters, digits, underscores, and hyphens. The maximum length is 64 characters. The ID must be unique within the same context library and remains unchanged when the name or instructions are modified.	preferences
name	string	The display name of the extraction policy.	User preferences
enabled	boolean	Specifies whether to execute this policy for new input. Default value: true. Disabling the policy does not delete historical memories.	true
preset	string	The preset policy. Valid values: fact, toc-profile, tob-digital-twin, and custom. Default value: fact.	fact
customInstructions	string	The custom extraction instructions. This parameter is required when preset is set to custom. Length: 1 to 8000 characters.	Extract only user product preferences
categories	array	The list of memory categories.	["preference","profile"]
	string	The name of the category.	preference
excludeRules	array	The list of exclusion rules. Content that matches these rules is not extracted.	["Password", "ID number"]
	string	The exclusion rule.	Password
model	object	The configuration of the extraction model.
name	string	The name of the extraction model. Currently, only qwen3.8-flash is supported, and internal platform credentials are used. Valid values: qwen3.8-flash	qwen3.8-flash
storagePolicy	object	The independent storage rules for this policy. If this parameter is omitted, the original value is retained. A new policy uses the default value. Repeatedly confirmed memories refresh the validity period by default.
mode	string	The storage mode. Valid values: event (event append) and upsert (merge and update). Default value: upsert.	upsert
mergeKey	string	The merge key for the upsert mode. Valid values: factKey, semantic, and both. Default value: semantic.	semantic
similarityThreshold	number	The similarity threshold for semantic merging. Valid values: 0 to 1. Default value: 0.4.	0.4
allowedActions	array	The allowed storage actions. By default, all actions are allowed, including ADD, UPDATE, MERGE, and DELETE.	["ADD","UPDATE","MERGE","DELETE"]
	string	The storage action.	ADD
dedupe	boolean	Specifies whether to enable deduplication in event mode. Default value: true.	true
humanEditProtection	boolean	Specifies whether to enable human edit protection. Default value: true. When enabled, automatic extraction does not overwrite manually modified memories.	true
ttlDays	integer	The number of days before a memory expires. A value of 0 indicates that the memory does not expire.	0
storagePolicy	object	The storage policy for the memory type.
mode	string	The storage mode. Valid values: event (event append) and upsert (merge and update). Default value: upsert.	upsert
mergeKey	string	The merge key for the upsert mode. Valid values: factKey, semantic, and both. Default value: semantic.	semantic
similarityThreshold	number	The similarity threshold for semantic merging. Valid values: 0 to 1. Default value: 0.4.	0.4
allowedActions	array	The allowed storage actions. By default, all actions are allowed, including ADD, UPDATE, MERGE, and DELETE.	["ADD","UPDATE","MERGE","DELETE"]
	string	The storage action.	ADD
dedupe	boolean	Specifies whether to enable deduplication in event mode. Default value: true.	true
humanEditProtection	boolean	Specifies whether to enable human edit protection. Default value: true. When enabled, automatic extraction does not overwrite manually modified memories.	true
ttlDays	integer	The number of days before a memory expires. A value of 0 indicates that the memory does not expire.	0
storageModes	array	The actual storage modes of each policy. A hybrid library includes both event and upsert modes.
	string	The storage mode.	upsert
scopePolicy	object	The scope constraint policy.
requiredAnyOf	array	The scope fields that require at least one non-empty value. Valid values: userId, agentId, appId, and runId.	["userId"]
	string	The name of the scope field.	userId
audit	object	The audit configuration.
retentionDays	integer	The number of days to retain audit logs. Valid values: 1 to 180. Default value: 30.	30
queryMode	string	The query recording mode for recall. Valid values: raw (plaintext) and hash (HMAC only). Default value: raw.	raw
droppedCandidates	boolean	Specifies whether to write item events for dropped candidates during recall. Default value: false.	false
strategyVersion	integer	The currently effective strategy version number for the memory type.	1
outputDataset	object	The location of the memory output dataset for the memory type.
agentSpace	string	The AgentSpace where the dataset is located.	my-agent-space
datasetName	string	The name of the dataset.	memory-my-context-store
schemaContract	string	The row schema contract of the dataset.	MemoryRecordV1
schemaVersion	integer	The schema version.	1
sourceStatus	object	The running status of the data source for the memory type and experience dataset follow. The experience library submits a checkpoint only after it is published and automatically applied. The checkpoint is retained when the process is paused or restarted.
state	string	The state of the data source. Valid values: Validating, Ready, Running, Retrying, Paused, SourceSchemaChanged, and Failed.	Running
checkpoint	object	The processing progress. For memory trajectory, the value is {processTimeNs, watermarkMs}. For dataset, the value is {seq}. For manual, the value is {}. For experience dataset follow, the seq uses an exact int64 decimal string.
	any	The field values of the checkpoint.	1788796800000
currentWindow	object	The current reserved sequence window {after,until,runId} for experience dataset follow. All sequence numbers are decimal strings. A failure does not advance the submitted checkpoint.
	string	The field values of the window. The after and until fields are decimal strings of __dataset_seq, and the read range is (after, until]. The runId is the optimization run ID corresponding to the window.	9007199254740993
lastRunId	string	The run ID of the last successful automatic application to the native experience library. This is for audit purposes only.	opr-example
lastWindowAt	string	The time when the window was last processed, in ISO 8601 UTC format.	2026-10-01T08:00:00Z
lastError	string	The last desensitized error message. This field is empty when the status is normal.	Data source read timeout
retryCount	integer	The number of consecutive retries.	0
observability	object	The observability resource coordinates for the memory type.
auditLogstore	string	The name of the audit Logstore.	memory-audit
eventsLogstore	string	The name of the event Logstore.	memory_events_0a1b2c3d
project	string	The Simple Log Service (SLS) project where both resources are located, which is the project bound to the AgentSpace.	agentloop-xxx
createTime	string	The time when the context library was created, in ISO 8601 UTC format.	2026-01-01T00:00:00Z
updateTime	string	The time when the context library was last updated, in ISO 8601 UTC format.	2026-01-02T00:00:00Z

Examples

Success response

JSON format

{
  "requestId": "9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M",
  "contextStoreName": "my-context-store",
  "agentSpace": "my-agent-space",
  "regionId": "cn-hangzhou",
  "contextType": "experience",
  "description": "My context store",
  "status": "ACTIVE",
  "config": {
    "auditLogStore": {
      "project": "agentloop-xxx",
      "logstore": "experience_audit"
    },
    "runtimeRecallEnabled": false,
    "runtimeRecallRevision": 1,
    "innerSource": {
      "project": "agentloop-xxx",
      "logstore": "memory_events_0a1b2c3d"
    },
    "source": {
      "type": "dataset",
      "datasetName": "reviewed_trajectories",
      "format": "atif",
      "binding": {
        "version": 1,
        "selection": {
          "mode": "all"
        }
      },
      "maxRecords": 1000,
      "versionPolicy": {
        "mode": "follow",
        "startSeq": "0"
      },
      "agentSpace": "my-agent-space",
      "startTime": "2026-01-01T00:00:00Z",
      "trajectory": {
        "logstore": "agent-trajectory",
        "startTime": "2026-10-01T00:00:00Z",
        "filter": {
          "serviceNames": [
            "crm-service"
          ],
          "agentNames": [
            "sales-copilot"
          ],
          "minStepCount": 2,
          "excludeDegraded": false,
          "query": "tool_names:\"search_order\""
        },
        "scopeMappingVersion": 2,
        "scopeMapping": {
          "userId": "$.trajectory_extensions.user_id",
          "agentId": "$.agent_name",
          "appId": "$.service_names[0]",
          "runId": "$.trajectory_id"
        },
        "pollIntervalSeconds": 300
      },
      "dataset": {
        "datasetName": "trajectory-with-crm-profile",
        "schemaContract": "MemorySourceV1",
        "versionPolicy": {
          "mode": "follow",
          "startSeq": 0,
          "version": "v3"
        },
        "filter": {
          "where": "appId = 'crm-service'"
        },
        "customFields": [
          {
            "sourceField": "customerTier",
            "usage": "extraction-input",
            "target": "metadata.customerTier",
            "description": "Customer tier",
            "sensitive": false
          }
        ],
        "pollIntervalSeconds": 300
      }
    },
    "miningTaskName": "experience-review-library",
    "serviceNames": [
      "order-service"
    ],
    "metadataField": {
      "key": "user_id"
    },
    "miningInterval": "1d",
    "extractionPolicy": {
      "preset": "fact",
      "customInstructions": "Extract only user product preferences",
      "categories": [
        "preference"
      ],
      "excludeRules": [
        "Password"
      ],
      "model": {
        "name": "qwen3.8-flash"
      }
    },
    "extractionPolicies": [
      {
        "strategyId": "preferences",
        "name": "User preferences",
        "enabled": true,
        "preset": "fact",
        "customInstructions": "Extract only user product preferences",
        "categories": [
          "preference"
        ],
        "excludeRules": [
          "Password"
        ],
        "model": {
          "name": "qwen3.8-flash"
        },
        "storagePolicy": {
          "mode": "upsert",
          "mergeKey": "semantic",
          "similarityThreshold": 0.4,
          "allowedActions": [
            "ADD"
          ],
          "dedupe": true,
          "humanEditProtection": true,
          "ttlDays": 0
        }
      }
    ],
    "storagePolicy": {
      "mode": "upsert",
      "mergeKey": "semantic",
      "similarityThreshold": 0.4,
      "allowedActions": [
        "ADD"
      ],
      "dedupe": true,
      "humanEditProtection": true,
      "ttlDays": 0
    },
    "storageModes": [
      "upsert"
    ],
    "scopePolicy": {
      "requiredAnyOf": [
        "userId"
      ]
    },
    "audit": {
      "retentionDays": 30,
      "queryMode": "raw",
      "droppedCandidates": false
    },
    "strategyVersion": 1,
    "outputDataset": {
      "agentSpace": "my-agent-space",
      "datasetName": "memory-my-context-store",
      "schemaContract": "MemoryRecordV1",
      "schemaVersion": 1
    },
    "sourceStatus": {
      "state": "Running",
      "checkpoint": {
        "key": "1788796800000"
      },
      "currentWindow": {
        "key": "9007199254740993"
      },
      "lastRunId": "opr-example",
      "lastWindowAt": "2026-10-01T08:00:00Z",
      "lastError": "Data source read timeout",
      "retryCount": 0
    },
    "observability": {
      "auditLogstore": "memory-audit",
      "eventsLogstore": "memory_events_0a1b2c3d",
      "project": "agentloop-xxx"
    }
  },
  "createTime": "2026-01-01T00:00:00Z",
  "updateTime": "2026-01-02T00:00:00Z"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.