InstallWorkspacePlugin

Updated at:
Copy as MD

Enables a component for a workspace, which corresponds to the operation of enabling the collaboration component in the console. After the component is enabled, you can query its status and current configurations.

Operation description

Enables the collaboration component for a workspace and configures initial settings such as the network.

Use pluginName=collaboration to specify the collaboration component. The enabling process is executed asynchronously. After submission, use GetWorkspacePlugin to check the component status and processing result.

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

update

*Workspace

acs:agentcore:{#regionId}:{#accountId}:workspace/{#WorkspaceId}

None None

Request syntax

PUT /workspaces/{workspaceId}/plugins/{pluginName} HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example

workspaceId

string

Yes

The workspace ID.

ws-123456

pluginName

string

Yes

The workspace component identifier. The value collaboration corresponds to the collaboration component in the console. For other component identifiers, retain the original values from the API parameter enumeration.

Valid values:

  • collaboration :

    Collaboration component.

collaboration

Request parameters

Parameter

Type

Required

Description

Example

body

object

No

The request body for installing the component.

config

object

No

The component-specific configuration. The configuration structure is determined by the pluginName parameter. Currently, the collaboration component supports the network configuration.

network

object

No

The network configuration used by the collaboration component. If not specified, the server uses the existing network configuration of the workspace.

internet

object

No

Specifies whether the collaboration component is allowed to access the public network. This configuration only controls the public network access capability and does not expose the component service to the public network.

enabled

boolean

No

If set to true and no VPC is specified, PUB_NET is used. If set to true and a VPC is specified, PRIVATE_PUBNET is used. If only a VPC is specified, PRIVATE_NET is used. You must configure at least one of Internet access and VPC.

true

vpc

object

No

The user VPC and the list of vSwitches used to deploy the collaboration component. The zones corresponding to the vSwitches are queried by the server, so you do not need to specify the zones.

enabled

boolean

No

Explicitly specifies whether the collaboration component uses the VPC network. If set to false, vpcId and vSwitchIds are ignored. If set to true, you must provide both vpcId and at least two vSwitchIds.

true

vpcId

string

Yes

The user VPC ID.

vpc-bp1234567890

vSwitchIds

array

Yes

The list of vSwitch IDs. The collaboration component requires that the vSwitches cover at least two different zones, and all vSwitches must belong to the VPC specified by vpcId.

string

No

The vSwitch ID.

vsw-bp1234567890

clientToken

string

No

The client idempotency token.

workspace-plugin-install-20260810-001

Response elements

Element

Type

Description

Example

object

The workspace component installation response.

requestId

string

The request ID.

request-123456

message

string

The response message. An error description is returned if the request fails.

success

httpStatusCode

integer

The HTTP status code.

200

code

string

The business status code.

SUCCESS

success

boolean

Indicates whether the request is successful.

true

data

object

The details of the component installation operation.

workspaceId

string

The workspace ID.

ws-123456

pluginName

string

The component name.

Valid values:

  • collaboration :

    Collaboration component.

collaboration

enabled

boolean

Indicates whether the component is enabled.

false

status

string

The component status. Valid values: DISABLED, ENABLING, ENABLED, ENABLE_FAILED, DISABLING, and DISABLE_FAILED.

Valid values:

  • DISABLED :

    Not installed.

  • ENABLE_FAILED :

    Installation failed.

  • ENABLING :

    Installing.

  • ENABLED :

    Enabled.

  • DISABLING :

    Uninstalling.

  • DISABLE_FAILED :

    Uninstallation failed.

ENABLING

Examples

Success response

JSON format

{
  "requestId": "request-123456",
  "message": "success",
  "httpStatusCode": 200,
  "code": "SUCCESS",
  "success": true,
  "data": {
    "workspaceId": "ws-123456",
    "pluginName": "collaboration",
    "enabled": false,
    "status": "ENABLING"
  }
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter The specified request parameter is invalid.
404 Resource.NotFound The specified AgentCore workspace does not exist.
409 Operation.Conflict The workspace or plugin is not in a state that permits this operation.
409 Idempotency.Conflict The client token has already been used for another workspace plugin operation.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.