CreateExternalAgent

Updated at:
Copy as MD

Creates an agent that runs in an external environment, saves the configurations for the platform model, instructions, tools, and skills, and asynchronously processes the onboarding configuration.

Operation description

Registers an agent hosted in a user runtime environment, which corresponds to the "Managed Agent" in the console. After registration, you can continue to obtain onboarding information and complete the connection.

Configure a managed agent

Provide name and select the configuration based on the model source:

modelSourceModel configuration
PLATFORMUses a platform model. Provide model.modelConnectionId and model.modelName.
RUNTIMEThe model is managed by an external runtime environment. Do not submit model.

If modelSource is omitted but model is provided, it is processed as PLATFORM. If both are omitted, the agent cannot be created.

Configure instructions, MCP tools, and skills by using instruction, tools, and skills. You can also reference an agent template by using template.aiRegistry. The external process is deployed by the caller. This operation does not create a platform runtime instance.

Onboarding sequence

Step 1: After creation, save the agentId and call GetExternalAgent to query the configuration processing result.

Step 2: After the latest configuration takes effect, call GetExternalAgentBootstrapOptions to obtain the available onboarding networks.

Step 3: Select an available network and call CreateExternalAgentBootstrapToken to obtain the onboarding token and CMS configuration. The external process completes the onboarding.

clientToken is a reserved query parameter and does not provide idempotency 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:CreateExternalAgent

create

*ExternalAgent

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

None None

Request syntax

POST /workspaces/{workspaceId}/external-agents HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example

workspaceId

string

Yes

The workspace ID.

ws-1

Request parameters

Parameter

Type

Required

Description

Example

body

object

No

The request body.

name

string

Yes

The name of the managed agent.

my-external-agent

description

string

No

The description of the managed agent.

Code review agent running 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. Available only when modelSource is 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 not passed, no quota is configured.

enabled

boolean

No

Specifies whether to enable the token quota. Defaults to true if not specified. Passing false disables and deletes existing quota rules.

true

limitType

string

No

The quota limit type. Required and validated 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 allowed to be consumed in a single period. Required and validated by the backend when the quota is enabled, and must be greater than 0.

1000000

periodType

string

No

The quota statistical period. Required and validated 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, 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. Use sourceType and versionSelector for new requests. Do not submit it in combination with sourceType.

1.0.0

sourceType

string

No

The skill source type. REFERENCE references the AI Registry. STATIC is statically provided with the deployment package.

Valid values:

  • REFERENCE :

    Reference AI Registry assets.

  • STATIC :

    Statically provided with deployment artifacts.

REFERENCE

versionSelector

object

No

The skill reference version selector. Supports LABEL tags and VERSION specific versions. Defaults to LABEL/latest if omitted. Selectors are not provided for STATIC sources.

type

string

No

The version selector type. LABEL selects by tag. VERSION selects by specific version.

Valid values:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

LABEL

value

string

No

The selector value. For LABEL, it is the tag name (such as latest). For VERSION, it 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 the AI Registry.

code-review-template

version

string

Yes

The version of the template in the AI Registry.

1.0.0

environment

object

No

Optional. Credentials can be bound to both PLATFORM and RUNTIME model sources. When passing the object, you must explicitly provide a non-null credentialReferences list. Common environment variables are not supported.

credentialReferences

array<object>

No

This list must be explicitly provided and cannot be null when the environment object is passed. The list is replaced as a whole. If environment is not passed during an update, the original binding is retained. If an empty list is passed or environment is null, the binding is cleared. Only the credential ID is passed, not the actual secret key.

object

No

credentialId

string

No

Required when a credential reference item is passed. Validated by the backend.

cred-example

clientToken

string

No

The reserved query parameter. The backend does not provide idempotency guarantees for deduplication or restoring the original acceptance result based on this identifier at this time.

client-token-1

For the specific meanings and value requirements of the request parameters, see the following parameter description.

Response elements

Element

Type

Description

Example

object

The successful response for creating 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. 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.

data

object

The information about the created managed agent.

agentId

string

The ID of the managed agent.

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.

Code review agent running in the user environment

status

string

The status of the managed agent. Valid values:

  • Creating: The agent is being created.

  • Running: The agent is running.

  • Failed: The agent failed.

  • Updating: The agent is being updated.

  • Deleting: The agent is being deleted.

  • Deleted: The agent is 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 (Pending), processing (Processing), waiting_retry (Waiting for retry), succeeded (Succeeded), failed (Failed), and superseded (Superseded by a new version).

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. Available only when modelSource is 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 the quota usage status for the current cycle. This parameter is empty if no quota is configured.

enabled

boolean

Indicates whether the quota is enabled. This parameter 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 cycle.

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 parameter is read-only and returned by the backend.

ACTIVE

usedAmount

integer

The number of tokens consumed in the current cycle. This parameter is read-only and returned by the backend.

12345

overLimit

boolean

Indicates whether the quota is exceeded in the current cycle. This parameter is read-only and returned by the backend.

false

instruction

string

The agent instruction, 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 compatible 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. REFERENCE references the AI Registry. STATIC is statically provided with the deployment package.

Valid values:

  • REFERENCE :

    Reference AI Registry assets.

  • STATIC :

    Statically provided with deployment artifacts.

REFERENCE

versionSelector

object

The skill reference version selector. Supports LABEL tags and VERSION specific versions. Defaults to LABEL/latest if omitted. Selectors are not provided for STATIC sources.

type

string

The version selector type. LABEL selects by tag. VERSION selects by specific version.

Valid values:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

LABEL

value

string

The selector value. For LABEL, it is the tag name (such as latest). For VERSION, it is the specific version number.

latest

fromTemplate

boolean

Specifies whether the skill is from a fixed template. This field is read-only. Template items cannot be removed.

false

resolvedVersion

string

The current target version. This field is read-only.

1.0.0

appliedVersion

string

The effective runtime version. 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. REFERENCE references the AI Registry. STATIC is statically provided with the deployment package.

Valid values:

  • REFERENCE :

    Reference AI Registry assets.

  • STATIC :

    Statically provided with deployment artifacts.

REFERENCE

versionSelector

object

The skill reference version selector. Supports LABEL tags and VERSION specific versions. Defaults to LABEL/latest if omitted. Selectors are not provided for STATIC sources.

type

string

The version selector type. LABEL selects by tag. VERSION selects by specific version.

Valid values:

  • VERSION :

    Select by specific version.

  • LABEL :

    Select version by tag.

LABEL

value

string

The selector value. For LABEL, it is the tag name (such as latest). For VERSION, it 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 the AI Registry.

code-review-template

version

string

The version of the template in the 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 latest heartbeat is within 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 last heartbeat reported by the managed agent, in RFC 3339 format.

2026-01-01T00:00:00Z

lastActiveAt

string

The last active time of the managed agent, 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>

This list must be explicitly provided and cannot be null when the environment object is passed. The list is replaced as a whole. If environment is not passed during an update, the original binding is retained. If an empty list is passed or environment is null, the binding is cleared. Only the credential ID is passed, not the actual secret key.

object

credentialId

string

Required when a credential reference item is passed. Validated by the backend.

cred-example

For the meanings of the fields in a successful response, see the following response parameter description.

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.