GetManagedAgent

Updated at:
Copy as MD

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:

FieldPurpose
latestSpecVersionThe latest submitted expected configuration version.
latestVersionStatusThe processing status of the expected version.
statusThe overall status of the agent.
sandboxPhaseCountsThe 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

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

agentcore:GetManagedAgent

get

*ManagedAgent

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/managedAgent/{#agentId}

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:

  • Creating :

    Creating.

  • Failed :

    Failed.

  • Running :

    Running.

  • Updating :

    Updating.

  • Deleted :

    Deleted.

  • Deleting :

    Deleting.

Running

harness

object

The agent runtime framework.

type

string

The type of the runtime framework.

Valid values:

  • qwenpaw :

    The qwenpaw runtime framework.

  • qodercli :

    The qodercli runtime framework.

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:

  • waiting_retry :

    Waiting for retry.

  • pending :

    Pending.

  • processing :

    Processing.

  • failed :

    Failed.

  • superseded :

    Superseded.

  • succeeded :

    Succeeded.

succeeded

createMode

string

The creation mode.

Managed

deployType

string

The deployment type.

Managed

accessMode

string

The inbound access mode.

Valid values:

  • API_KEY :

    API key authentication.

  • USER :

    User identity.

API_KEY

accessScope

string

The user access scope.

Valid values:

  • ALL :

    All scopes.

  • SPECIFIED :

    Specified scope.

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 :

    Limit by token count.

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:

  • day: Daily.

  • month: Monthly.

Valid values:

  • month :

    Monthly.

  • day :

    Daily.

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:

  • off
  • low
  • medium
  • high
  • xhigh
  • max

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:

  • HEAVY :

    High-end specifications (4 vCPUs, 8 GiB).

  • INTERACTIVE :

    Interactive specifications (1 vCPU, 2 GiB).

  • STANDARD :

    Standard specifications (2 vCPUs, 4 GiB).

STANDARD

sessionPolicy

object

The session policy configuration.

type

string

The session policy type.

Valid values:

  • DISABLED :

    Disabled.

  • AFFINITY :

    Session affinity.

  • ISOLATED_HEADER_FIELD :

    Isolate sessions by specifying a request header identifier.

  • ISOLATED_COOKIE :

    Isolate sessions by using a cookie identifier.

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 :

    MCP service.

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 :

    References AI Registry assets.

  • STATIC :

    Statically provided with the deployment artifact.

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:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

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 :

    References AI Registry assets.

  • STATIC :

    Statically provided with the deployment artifact.

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:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

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.