GetManagedAgent
Queries the latest configuration, Harness, skill versions, configuration processing status, and running instance statistics of a managed Harness agent.
Operation description
Queries the configuration, skill versions, and running status of a managed Harness agent to view the current configuration and its processing results.
Configuration and running status
This operation returns the latest submitted configuration, which may still be processing. Use the following fields to determine the update progress and running status:
| Field | Purpose |
latestSpecVersion | The latest submitted expected configuration version. |
latestVersionStatus | The processing status of the expected version. |
status | The overall status of the agent. |
sandboxPhaseCounts | The current snapshot of the number of instances in each phase. |
Successful configuration processing does not mean that all old instances have been replaced. To view specific instances or active sessions, call ListSandboxes and ListSandboxSessions respectively.
Harness and skill versions
harness.type indicates the runtime framework determined at creation. For qodercli, connectorServiceAccountKey returns the ID of the bound account key record, not the original key.
configuredSkills are explicitly configured skills. skills contains the aggregated results of templates and explicit configurations. resolvedVersion is the current target version, and appliedVersion is the version that has taken effect at runtime. These two may differ during an update. fromTemplate=true indicates that the skill comes from a template.
If the queried agent does not exist, has been deleted, or does not belong to the specified workspace, a resource not found error is returned.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:GetManagedAgent |
get |
*ManagedAgent
|
None | None |
Request syntax
GET /workspaces/{workspaceId}/managed-agents/{agentId} HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| workspaceId |
string |
Yes |
The workspace ID. |
ws-1 |
| agentId |
string |
Yes |
The ID of the managed Harness agent. |
agent-1 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
No parameters required.
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| requestId |
string |
The request ID. |
1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| message |
string |
The request processing result message. |
success |
| httpStatusCode |
integer |
The HTTP status code. A value of 200 indicates success. |
200 |
| code |
string |
The business status code. A value of SUCCESS indicates success. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. |
true |
| data |
object |
The details of the managed Harness agent. |
|
| contextConfiguration |
object |
The target configuration accepted by the managed agent, which does not necessarily mean it has taken effect at runtime. This field is used in the detail responses of CreateManagedAgent, UpdateManagedAgent, and GetManagedAgent. In the configuration of a fixed version, it represents the configuration snapshot saved for that version. A returned object with enabled:false indicates that the configuration is disabled. The absence of the entire object indicates that the response does not provide the configuration. |
|
| enabled |
boolean |
Read-only. When the configuration object is returned, this field indicates the enablement status of the configuration. A value of false indicates that the configuration is disabled. The absence of the entire configuration object indicates that the response does not provide the configuration, which cannot be treated as false. |
true |
| bindings |
array<object> |
Read-only resource references. This field may be omitted when no selection is made. A disabled configuration can still retain a non-empty selection. You cannot determine whether the configuration is enabled solely based on whether the array is empty. |
|
|
object |
|||
| type |
string |
Read-only string. The currently known types are KNOWLEDGE_BASE (knowledge base) and DATA_CONNECTOR (data connector). The response may be extended with new types. The client should retain unknown values and should not fail to parse the entire response due to unknown types. The new request types are subject to the actual support scope of the server. |
KNOWLEDGE_BASE |
| resourceId |
string |
The ID of the context resource in the current workspace. |
kb-example |
| effectiveContextConfiguration |
object |
Read-only. This field is provided only by GetManagedAgent when an effective version exists, corresponding to the configuration snapshot of effectiveSpecVersion. It remains the original effective configuration when a new version is being prepared or fails to be released. It is not returned before the first time it takes effect, or in the configuration of CreateManagedAgent, UpdateManagedAgent, and fixed versions. Omission does not indicate that it is disabled, and the client must not automatically supplement it with enabled:false. |
|
| enabled |
boolean |
Read-only. When the configuration object is returned, this field indicates the enablement status of the configuration. A value of false indicates that the configuration is disabled. The absence of the entire configuration object indicates that the response does not provide the configuration, which cannot be treated as false. |
true |
| bindings |
array<object> |
Read-only resource references. This field may be omitted when no selection is made. A disabled configuration can still retain a non-empty selection. You cannot determine whether the configuration is enabled solely based on whether the array is empty. |
|
|
object |
|||
| type |
string |
Read-only string. The currently known types are KNOWLEDGE_BASE (knowledge base) and DATA_CONNECTOR (data connector). The response may be extended with new types. The client should retain unknown values and should not fail to parse the entire response due to unknown types. The new request types are subject to the actual support scope of the server. |
KNOWLEDGE_BASE |
| resourceId |
string |
The ID of the context resource in the current workspace. |
kb-example |
| agenticFsMounts |
array<object> |
The NAS storage mount configuration. Currently, the AgenticFS type is supported, which is used to mount file directories in access points to agent runtime instances. A maximum of 10 NAS mounts are allowed in total with ossMounts. |
|
|
object |
|||
| server |
string |
The domain name of the access point. This field is required and verified by the backend for each mount item. It does not include the protocol, port, or path. Use the DomainName from the NAS ListAccessPoints response. |
ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com |
| path |
string |
The existing non-empty relative directory under the access point. This field is required and verified by the backend for each mount item. Root directories, absolute paths, or parent directory segments are not allowed. |
workspace/data |
| mountPath |
string |
The absolute mount path in the container, such as /data/train. Mount targets must not be duplicated or form parent-child overrides, and must avoid platform-reserved directories. |
/mnt/agenticfs/data |
| readOnly |
boolean |
Specifies whether the mount is read-only. If omitted, the default value is false. This is not the read-only policy of the RAM role. |
false |
| agentId |
string |
The ID of the managed Harness agent. |
agent-1 |
| workspaceId |
string |
The workspace ID. |
ws-1 |
| name |
string |
The name of the managed Harness agent. |
my-agent |
| description |
string |
The description of the managed Harness agent. |
Agent for code review |
| status |
string |
The status of the managed Harness agent. Valid values:
|
Running |
| harness |
object |
The agent runtime framework. |
|
| type |
string |
The type of the runtime framework. Valid values:
|
qodercli |
| configuration |
object |
The configuration of the runtime framework. |
|
| connectorServiceAccountKey |
string |
The ID of the connector account key record bound to qodercli. This is not the original service account key. |
key-xxxx |
| connectorServiceAccountName |
string |
The name of the connector account bound to qodercli. |
my-connector-key |
| version |
string |
The Harness version corresponding to the pool target image. |
202611031754 |
| outdatedInstanceCount |
integer |
The total number of instances that are not aligned with the pool target image tag. |
2 |
| latestSpecVersion |
integer |
The latest specification version number. |
1 |
| latestVersionStatus |
string |
The status of the latest version. Valid values:
|
succeeded |
| createMode |
string |
The creation mode. |
Managed |
| deployType |
string |
The deployment type. |
Managed |
| accessMode |
string |
The inbound access mode. Valid values:
|
API_KEY |
| accessScope |
string |
The user access scope. Valid values:
|
ALL |
| createdAt |
string |
The creation time in RFC 3339 format. |
2026-01-01T00:00:00Z |
| updatedAt |
string |
The update time in RFC 3339 format. |
2026-01-01T00:00:00Z |
| regionId |
string |
The region ID. |
cn-hangzhou |
| sandboxPhaseCounts |
object |
The instance counts of managed Harness agents by sandbox phase. Current keys: PENDING (creating or initializing), RUNNING (running), HIBERNATING (hibernating), HIBERNATED (hibernated), RESUMING (resuming), TERMINATING (terminating), and FAILED (failed at runtime). Only phases that actually occur are returned, and missing keys are treated as 0. This field is a dynamic mapping and new keys may be added in the future. The frontend can use FAILED > 0 to determine whether abnormal instances exist. |
|
|
integer |
The number of instances in the corresponding sandbox running phase. |
1 |
|
| model |
object |
The model configuration information. |
|
| modelConnectionId |
string |
The model connection ID. |
mc-1 |
| modelName |
string |
The upstream model name. |
qwen-max |
| quota |
object |
The model token quota configuration and usage status for the current period. This field is empty if no quota is configured. |
|
| enabled |
boolean |
Indicates whether the quota is enabled. This field is not returned if no quota is configured. |
true |
| limitType |
string |
The quota limit type. Currently, only token is supported. Valid values:
|
token |
| usageLimit |
integer |
The maximum number of tokens allowed to be consumed in a single period. |
1000000 |
| periodType |
string |
The quota statistical period. Valid values:
Valid values:
|
day |
| ruleStatus |
string |
The gateway quota rule status. This field is read-only and returned by the backend. |
ACTIVE |
| usedAmount |
integer |
The number of tokens consumed in the current period. This field is read-only and returned by the backend. |
12345 |
| overLimit |
boolean |
Indicates whether the quota is exceeded in the current period. This field is read-only and returned by the backend. |
false |
| thinkingLevel |
string |
The thinking level. Valid values: off, low, medium, high, xhigh, and max. If not set, the default thinking level (default) is used. In the response, this field may be missing, null, or an empty string, all of which indicate default. The specific effect depends on the support of the selected Harness and model. Valid values:
|
high |
| instruction |
string |
The agent instruction used to guide the behavior of the agent. |
You are a code review assistant |
| promptVariables |
array<object> |
The prompt variable declarations. |
|
|
object |
|||
| name |
string |
The variable name. |
brand |
| defaultValue |
string |
The default value. |
default |
| description |
string |
The variable description. |
desc |
| template |
object |
The template configuration information. |
|
| aiRegistry |
object |
The AI registry template configuration. |
|
| name |
string |
The name of the template in the AI registry. |
code-review-template |
| version |
string |
The version of the template in the AI registry. |
1.0.0 |
| runtime |
object |
The runtime configuration information. |
|
| compute |
object |
The compute configuration. |
|
| computeClass |
string |
The compute specifications. Valid values:
|
STANDARD |
| sessionPolicy |
object |
The session policy configuration. |
|
| type |
string |
The session policy type. Valid values:
|
DISABLED |
| headerName |
string |
The HTTP header name used for session affinity. This field takes effect when sessionPolicy.type is set to ISOLATED_HEADER_FIELD. |
X-Session-Id |
| hpa |
object |
The sandbox auto scaling and session configuration. |
|
| enabled |
boolean |
Indicates whether elastic auto scaling is enabled in the current configuration. |
|
| minSandboxCount |
integer |
The minimum number of instances in the current configuration. |
1 |
| maxSandboxCount |
integer |
The maximum number of instances in the current configuration. |
3 |
| maxConcurrentSessionsPerSandbox |
integer |
The maximum number of concurrent sessions per instance in the current configuration. |
5 |
| sessionTtlSeconds |
integer |
The maximum idle time for a session in the current configuration, in seconds. |
3600 |
| environment |
object |
The environment configuration information. |
|
| variables |
array<object> |
The list of environment variables. |
|
|
object |
|||
| name |
string |
The name of the environment variable. |
API_KEY |
| value |
string |
The value of the environment variable. |
sk-xxxx |
| credentialReferences |
array<object> |
The list of credential references. |
|
|
object |
|||
| credentialId |
string |
The credential ID. |
cred-1 |
| network |
object |
The network configuration information. |
|
| accessInternet |
object |
The public network access configuration. |
|
| enabled |
boolean |
Indicates whether Internet access is allowed. |
false |
| accessVpc |
object |
The VPC access configuration. |
|
| enabled |
boolean |
Specifies whether access to the VPC is allowed. |
true |
| ossMounts |
array<object> |
The list of OSS mounts. A maximum of 10 items are allowed. |
|
|
object |
|||
| bucketName |
string |
The name of the OSS bucket. This field is required and validated by the backend for each mount item. |
bucket-001 |
| path |
string |
The non-empty relative directory prefix in the currently configured bucket. |
datasets |
| mountPath |
string |
The absolute mount path in the container, such as /data/train. Mount targets must not be duplicated or form parent-child overrides, and must avoid platform-reserved directories. |
/mnt/oss/datasets |
| readOnly |
boolean |
Specifies whether to mount as read-only. Default value: false. |
|
| tools |
array<object> |
The list of tool configurations. |
|
|
object |
|||
| name |
string |
The name of the tool. |
code-reviewer |
| type |
string |
The type of the tool. Valid values:
|
MCP |
| skills |
array<object> |
The list of skill configurations. |
|
|
array<object> |
|||
| name |
string |
The name of the skill. |
code-analysis |
| version |
string |
The current target version for compatibility with legacy clients. New clients use resolvedVersion and determine the runtime effective version based on appliedVersion. |
1.0.0 |
| sourceType |
string |
The source type of the skill. REFERENCE references the AI Registry, and STATIC is statically provided with the deployment artifact. Valid values:
|
REFERENCE |
| versionSelector |
object |
The version selector for the skill reference. Supports LABEL for tags and VERSION for specific versions. If omitted, LABEL/latest is used. STATIC sources do not provide a selector. |
|
| type |
string |
The type of the version selector. LABEL selects by tag, and VERSION selects by specific version. Valid values:
|
LABEL |
| value |
string |
The value of the selector. For LABEL, it is the tag name (such as latest). For VERSION, it is the specific version number. |
latest |
| fromTemplate |
boolean |
Specifies whether it is from a fixed template. This field is read-only, and template items cannot be removed. |
false |
| resolvedVersion |
string |
The current target version. This field is read-only. |
1.0.0 |
| appliedVersion |
string |
The effective version at runtime. This field is read-only. |
1.0.0 |
| configuredSkills |
array<object> |
The explicitly configured skills. |
|
|
array<object> |
|||
| name |
string |
The name of the skill in the Workspace AI Registry. |
web-search |
| version |
string |
The legacy compatibility field. New requests use sourceType and versionSelector. |
1.0.0 |
| sourceType |
string |
The source type of the skill. REFERENCE references the AI Registry, and STATIC is statically provided with the deployment artifact. Valid values:
|
REFERENCE |
| versionSelector |
object |
The version selector for the skill reference. Supports LABEL for tags and VERSION for specific versions. If omitted, LABEL/latest is used. STATIC sources do not provide a selector. |
|
| type |
string |
The type of the version selector. LABEL selects by tag, and VERSION selects by specific version. Valid values:
|
LABEL |
| value |
string |
The value of the selector. For LABEL, it is the tag name (such as latest). For VERSION, it is the specific version number. |
latest |
| subAgents |
array<object> |
The list of sub-agent configurations. |
|
|
array<object> |
|||
| name |
string |
The name of the sub-agent. |
reviewer-agent |
| instruction |
string |
The instruction for the sub-agent. |
Review the code |
| skills |
array<object> |
The list of skills for the sub-agent. |
|
|
object |
|||
| name |
string |
The name of the skill. |
web-search |
| version |
string |
The version of the skill. |
1.0.0 |
Examples
Success response
JSON format
{
"requestId": "1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": true,
"data": {
"contextConfiguration": {
"enabled": true,
"bindings": [
{
"type": "KNOWLEDGE_BASE",
"resourceId": "kb-example"
}
]
},
"effectiveContextConfiguration": {
"enabled": true,
"bindings": [
{
"type": "KNOWLEDGE_BASE",
"resourceId": "kb-example"
}
]
},
"agenticFsMounts": [
{
"server": "ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com",
"path": "workspace/data",
"mountPath": "/mnt/agenticfs/data",
"readOnly": false
}
],
"agentId": "agent-1",
"workspaceId": "ws-1",
"name": "my-agent",
"description": "Agent for code review",
"status": "Running",
"harness": {
"type": "qodercli",
"configuration": {
"connectorServiceAccountKey": "key-xxxx",
"connectorServiceAccountName": "my-connector-key"
},
"version": "202611031754",
"outdatedInstanceCount": 2
},
"latestSpecVersion": 1,
"latestVersionStatus": "succeeded",
"createMode": "Managed",
"deployType": "Managed",
"accessMode": "API_KEY",
"accessScope": "ALL",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"regionId": "cn-hangzhou",
"sandboxPhaseCounts": {
"key": 1
},
"model": {
"modelConnectionId": "mc-1",
"modelName": "qwen-max",
"quota": {
"enabled": true,
"limitType": "token",
"usageLimit": 1000000,
"periodType": "day",
"ruleStatus": "ACTIVE",
"usedAmount": 12345,
"overLimit": false
},
"thinkingLevel": "high"
},
"instruction": "You are a code review assistant",
"promptVariables": [
{
"name": "brand",
"defaultValue": "default",
"description": "desc"
}
],
"template": {
"aiRegistry": {
"name": "code-review-template",
"version": "1.0.0"
}
},
"runtime": {
"compute": {
"computeClass": "STANDARD"
},
"sessionPolicy": {
"type": "DISABLED",
"headerName": "X-Session-Id"
},
"hpa": {
"enabled": false,
"minSandboxCount": 1,
"maxSandboxCount": 3,
"maxConcurrentSessionsPerSandbox": 5,
"sessionTtlSeconds": 3600
}
},
"environment": {
"variables": [
{
"name": "API_KEY",
"value": "sk-xxxx"
}
],
"credentialReferences": [
{
"credentialId": "cred-1"
}
]
},
"network": {
"accessInternet": {
"enabled": false
},
"accessVpc": {
"enabled": true
}
},
"ossMounts": [
{
"bucketName": "bucket-001",
"path": "datasets",
"mountPath": "/mnt/oss/datasets",
"readOnly": false
}
],
"tools": [
{
"name": "code-reviewer",
"type": "MCP"
}
],
"skills": [
{
"name": "code-analysis",
"version": "1.0.0",
"sourceType": "REFERENCE",
"versionSelector": {
"type": "LABEL",
"value": "latest"
},
"fromTemplate": false,
"resolvedVersion": "1.0.0",
"appliedVersion": "1.0.0"
}
],
"configuredSkills": [
{
"name": "web-search",
"version": "1.0.0",
"sourceType": "REFERENCE",
"versionSelector": {
"type": "LABEL",
"value": "latest"
}
}
],
"subAgents": [
{
"name": "reviewer-agent",
"instruction": "Review the code",
"skills": [
{
"name": "web-search",
"version": "1.0.0"
}
]
}
]
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 404 | Resource.NotFound | The specified ManagedAgent does not exist. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.