UpdateExternalAgent

Updated at:
Copy as MD

Updates the model source, instructions, tools, and skills of a managed agent, and processes the configuration asynchronously.

Operation description

Updates the model, instruction, tool, or skill configurations saved on the platform for a managed agent to adjust its capability configurations after integration.

Update rules

Provide at least one updatable field. Omitted top-level fields retain their original configurations. You can set description=null to clear the description. The tools and skills fields are replaced in their entirety upon submission. You must include the items that you want to retain. Pass [] to clear the corresponding explicit list.

Switch model sources

  • To switch to PLATFORM, provide modelSource=PLATFORM and a valid model configuration, including the model connection ID and model name.

  • To switch to RUNTIME, update the Settings to modelSource=RUNTIME and do not commit the platform model. The original platform model configuration is removed when the source is switched.

When a template is used, configurations that belong to the template, such as instructions, are read from the template. A successful update indicates that the request is accepted. Invoke GetExternalAgent to query the configuration version and external accessed state. The clientToken parameter does not provide idempotence guarantees at this time.

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

update

*ExternalAgent

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

None None

Request syntax

PATCH /workspaces/{workspaceId}/external-agents/{agentId} HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example

workspaceId

string

Yes

The workspace ID.

ws-1

agentId

string

Yes

The managed agent ID.

agent-1

Request parameters

Parameter

Type

Required

Description

Example

body

object

No

The request body.

name

string

No

The name of the managed agent.

my-external-agent

description

string

No

The description of the managed agent.

A code review agent that runs in the user environment

modelSource

string

No

The source of the model configuration. PLATFORM indicates that the platform parses and delivers the model configuration. RUNTIME indicates that the external runtime manages the model itself, and the model parameter cannot be passed at the same time. Valid values: PLATFORM (platform model) and RUNTIME (runtime model).

Valid values:

  • PLATFORM :

    Platform model.

  • RUNTIME :

    Runtime model.

PLATFORM

model

object

No

The model configuration. This parameter is available only when modelSource is set to PLATFORM.

modelConnectionId

string

Yes

The model connection ID.

mc-1

modelName

string

Yes

The upstream model name.

qwen-max

quota

object

No

The model token quota configuration. If you do not pass this parameter, no quota is configured.

enabled

boolean

No

Specifies whether to enable the token quota. Default value: true. If you set this parameter to false, the quota is disabled and existing quota rules are deleted.

true

limitType

string

No

The quota limit type. This parameter is required and verified by the backend when the quota is enabled. Fixed value: token.

Valid values:

  • token :

    Limit by token count.

token

usageLimit

integer

No

The maximum number of tokens that can be consumed in a single period. This parameter is required and verified by the backend when the quota is enabled. The value must be greater than 0.

1000000

periodType

string

No

The statistical period of the quota. This parameter is required and verified by the backend when the quota is enabled. Valid values: day (daily) and month (monthly).

Valid values:

  • month :

    Monthly statistics.

  • day :

    Daily statistics.

day

instruction

string

No

The agent instruction, which is used to guide the behavior of the agent.

You are a code review assistant

tools

array<object>

No

The list of tool configurations.

object

No

The list of tool configurations.

name

string

Yes

The tool name.

code-reviewer

type

string

Yes

The tool type. Valid values: MCP (MCP tool).

Valid values:

  • MCP :

    MCP tool.

MCP

skills

array<object>

No

The list of skill configurations.

array<object>

No

The list of skill configurations.

name

string

Yes

The skill name.

code-analysis

version

string

No

The skill version field for compatibility with legacy requests. For new requests, use sourceType and versionSelector. Do not submit this parameter in combination with sourceType.

1.0.0

sourceType

string

No

The skill source type. Valid values: REFERENCE (references AI Registry) and STATIC (statically provided with the package).

Valid values:

  • REFERENCE :

    Reference AI Registry assets.

  • STATIC :

    Statically provided with deployment artifacts.

REFERENCE

versionSelector

object

No

The skill reference version selector, which supports LABEL tags and VERSION specific versions. If omitted, LABEL/latest is used. Selectors are not provided for STATIC sources.

type

string

No

The version selector type. Valid values: LABEL (by tag) and VERSION (by specific version).

Valid values:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

LABEL

value

string

No

The selector value. When the type is LABEL, the value is the tag name, such as latest. When the type is VERSION, the value is the specific version number.

latest

template

object

No

The agent template configuration.

aiRegistry

object

No

The AI Registry template configuration.

name

string

Yes

The name of the template in AI Registry.

code-review-template

version

string

Yes

The version of the template in AI Registry.

1.0.0

environment

object

No

The credential binding configuration. If you do not pass this parameter, the original binding is retained. If you pass an object, you must explicitly provide a non-null credentialReferences list, and the list is replaced in its entirety. If the list is empty or environment is null, the binding is cleared. Empty objects and objects that contain only common environment variables are invalid.

credentialReferences

array<object>

No

The list of credential references. You must explicitly provide this list when passing the environment object, and it cannot be null. The list is replaced in its entirety. If you do not pass environment during an update, the original binding is retained. If you pass an empty list or set environment to null, the binding is cleared. Pass only the credential ID, not the actual key.

object

No

credentialId

string

No

The credential ID. This parameter is required when passing a credential reference item and is verified by the backend.

cred-example

clientToken

string

No

The reserved query parameter. The backend does not currently provide idempotence guarantees for deduplication or recovery of original acceptance results based on this identifier.

client-token-1

For the specific meanings and valid values of the request parameters, see the metric description below.

Response elements

Element

Type

Description

Example

object

The successful response for updating a managed agent.

requestId

string

The request ID.

1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx

message

string

The request processing result message.

success

httpStatusCode

integer

The HTTP status code. The value is 200 for a successful request.

200

code

string

The business status code. The value is SUCCESS for a successful request.

SUCCESS

success

boolean

Indicates whether the request is successful.

data

object

The details of the updated managed agent.

agentId

string

The managed agent ID.

agent-1

workspaceId

string

The workspace ID.

ws-1

regionId

string

The region ID.

cn-hangzhou

name

string

The name of the managed agent.

my-external-agent

description

string

The description of the managed agent.

A code review agent that runs in the user environment

status

string

The status of the managed agent. Valid values: Creating, Running, Failed, Updating, Deleting, and Deleted.

Valid values:

  • Creating :

    Creating.

  • Failed :

    Failed.

  • Running :

    Running.

  • Updating :

    Updating.

  • Deleted :

    Deleted.

  • Deleting :

    Deleting.

Running

latestSpecVersion

integer

The latest specification version number.

1

latestVersionStatus

string

The processing status of the latest specification version. Valid values: pending, processing, waiting_retry, succeeded, failed, and superseded.

Valid values:

  • waiting_retry :

    Waiting for retry.

  • pending :

    Pending.

  • processing :

    Processing.

  • failed :

    Failed.

  • superseded :

    Superseded by a new version.

  • succeeded :

    Succeeded.

pending

createMode

string

The creation mode.

CUSTOM

runtime

string

The runtime type reported by the managed agent.

qwenpaw

deployType

string

The deployment type.

SELF_HOSTED

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

modelSource

string

The source of the model configuration. PLATFORM indicates that the platform parses and delivers the model configuration. RUNTIME indicates that the external runtime manages the model itself, and the model parameter cannot be passed at the same time. Valid values: PLATFORM (platform model) and RUNTIME (runtime model).

Valid values:

  • PLATFORM :

    Platform model.

  • RUNTIME :

    Runtime model.

PLATFORM

model

object

The model configuration. This parameter is available only when modelSource is set to PLATFORM.

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. A value of day indicates daily, and a value of month indicates monthly.

Valid values:

  • month :

    Monthly statistics.

  • day :

    Daily statistics.

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

instruction

string

The agent instruction, which is used to guide the behavior of the agent.

You are a code review assistant

tools

array<object>

The list of tool configurations.

object

The list of tool configurations.

name

string

The tool name.

code-reviewer

type

string

The tool type. Valid values: MCP (MCP tool).

Valid values:

  • MCP :

    MCP tool.

MCP

skills

array<object>

The list of skill configurations.

array<object>

The list of skill configurations.

name

string

The skill name.

code-analysis

version

string

The current target version for compatibility with legacy clients. New clients use resolvedVersion and determine the effective runtime version based on appliedVersion.

1.0.0

sourceType

string

The skill source type. Valid values: REFERENCE (references AI Registry) and STATIC (statically provided with the package).

Valid values:

  • REFERENCE :

    Reference AI Registry assets.

  • STATIC :

    Statically provided with deployment artifacts.

REFERENCE

versionSelector

object

The skill reference version selector, which supports LABEL tags and VERSION specific versions. If omitted, LABEL/latest is used. Selectors are not provided for STATIC sources.

type

string

The version selector type. Valid values: LABEL (by tag) and VERSION (by specific version).

Valid values:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

LABEL

value

string

The selector value. When the type is LABEL, the value is the tag name, such as latest. When the type is VERSION, the value is the specific version number.

latest

fromTemplate

boolean

Indicates whether the skill 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 applied 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. For new requests, use sourceType and versionSelector.

1.0.0

sourceType

string

The skill source type. Valid values: REFERENCE (references AI Registry) and STATIC (statically provided with the package).

Valid values:

  • REFERENCE :

    Reference AI Registry assets.

  • STATIC :

    Statically provided with deployment artifacts.

REFERENCE

versionSelector

object

The skill reference version selector, which supports LABEL tags and VERSION specific versions. If omitted, LABEL/latest is used. Selectors are not provided for STATIC sources.

type

string

The version selector type. Valid values: LABEL (by tag) and VERSION (by specific version).

Valid values:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

LABEL

value

string

The selector value. When the type is LABEL, the value is the tag name, such as latest. When the type is VERSION, the value is the specific version number.

latest

template

object

The agent template configuration.

aiRegistry

object

The AI Registry template configuration.

name

string

The name of the template in AI Registry.

code-review-template

version

string

The version of the template in AI Registry.

1.0.0

externalAgentStatus

object

The runtime status information reported by the managed agent.

heartbeatStatus

string

The heartbeat status. ONLINE indicates that the most recent heartbeat did not exceed the configured timeout threshold. STALE indicates that the heartbeat has timed out. UNKNOWN indicates that the heartbeat is missing or the format is invalid. Valid values:

  • ONLINE: Online.

  • STALE: Heartbeat expired.

  • UNKNOWN: Unknown.

Valid values:

  • STALE :

    Heartbeat expired.

  • UNKNOWN :

    Unknown.

  • ONLINE :

    Online.

ONLINE

lastHeartbeat

string

The time of the most recent heartbeat from the managed agent, in RFC 3339 format.

2026-01-01T00:00:00Z

lastActiveAt

string

The time when the managed agent was last active, in RFC 3339 format.

2026-01-01T00:00:00Z

localIP

string

The local IP address reported by the managed agent.

10.0.0.42

runtime

string

The runtime type reported by the managed agent.

qwenpaw

environment

object

The credential binding configuration.

credentialReferences

array<object>

The list of credential references. You must explicitly provide this list when passing the environment object, and it cannot be null. The list is replaced in its entirety. If you do not pass environment during an update, the original binding is retained. If you pass an empty list or set environment to null, the binding is cleared. Pass only the credential ID, not the actual key.

object

credentialId

string

The credential ID. This parameter is required when passing a credential reference item and is verified by the backend.

cred-example

For the meanings of the fields in a successful response, see the metric description of the response parameters below.

Examples

Success response

JSON format

{
  "requestId": "1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message": "success",
  "httpStatusCode": 200,
  "code": "SUCCESS",
  "success": false,
  "data": {
    "agentId": "agent-1",
    "workspaceId": "ws-1",
    "regionId": "cn-hangzhou",
    "name": "my-external-agent",
    "description": "Code review agent running in the user environment",
    "status": "Running",
    "latestSpecVersion": 1,
    "latestVersionStatus": "pending",
    "createMode": "CUSTOM",
    "runtime": "qwenpaw",
    "deployType": "SELF_HOSTED",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z",
    "modelSource": "PLATFORM",
    "model": {
      "modelConnectionId": "mc-1",
      "modelName": "qwen-max",
      "quota": {
        "enabled": true,
        "limitType": "token",
        "usageLimit": 1000000,
        "periodType": "day",
        "ruleStatus": "ACTIVE",
        "usedAmount": 12345,
        "overLimit": false
      }
    },
    "instruction": "You are a code review assistant",
    "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"
        }
      }
    ],
    "template": {
      "aiRegistry": {
        "name": "code-review-template",
        "version": "1.0.0"
      }
    },
    "externalAgentStatus": {
      "heartbeatStatus": "ONLINE",
      "lastHeartbeat": "2026-01-01T00:00:00Z",
      "lastActiveAt": "2026-01-01T00:00:00Z",
      "localIP": "10.0.0.42",
      "runtime": "qwenpaw"
    },
    "environment": {
      "credentialReferences": [
        {
          "credentialId": "cred-example"
        }
      ]
    }
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.