Use execution roles for high-code agents

Updated at:
Copy as MD

A high-code agent requires an execution role to access cloud resources. This topic describes how to configure an execution role in AgentCore and verify that the agent can access the destination resources.

Background information

An execution role is a RAM role associated with a high-code agent. The role defines the cloud resource operations that the agent can perform at runtime. Workload identities help you avoid writing long-term AccessKey pairs to code or images.

An execution role includes the following configurations:

  • Trust policy: Limits the workload identities that can use the role. The workload identity condition determines which agent runtime environments can use the role. The service principal for a high-code agent is workload.agentidentity.aliyuncs.com.

  • Access policy: Limits the operations that can be performed and the resources that can be accessed by using the role.

    At runtime, the high-code agent uses the execution role to send business requests to the destination cloud resources.

Inbound authentication for external applications that call the agent and API keys for third-party models must be configured separately.

Prerequisites

  • AgentCore is activated, and a Workspace is created.

  • The cloud services, resources, and operations that the agent must access are identified.

  • You have the permissions required to configure the agent. Creating and authorizing the execution role and modifying its trust policy require RAM administrator permissions.

  • The agent runtime environment can access the destination service over the required network.

Configure an execution role

Step 1: Go to the execution role configuration

  1. Log on to the AgentCore console, and select a region and a Workspace.

  2. Create a high-code agent or go to the configuration page of an existing high-code agent.

  3. Find the Execution role configuration item.

    For instructions on how to create a high-code agent, see High-code Agent deployment and use guide.

Step 2: Create or select a role

For a first-time configuration, use quick authorization to create the default role. If your account already has a role that you can reuse, use the existing role.

Create a role (first-time configuration)

  1. In the Execution role section, click Create and authorize to go to the RAM authorization page.

  2. Confirm the role name, service principal, and access policy, and complete the authorization.

  3. Return to AgentCore, refresh the role list and policy information, and select the created role.

Important

The workload identity scope in the current quick authorization request is *. Before using the role in production, check the policy that is generated in RAM and narrow the scope to the applicable workload identities as needed.

The default role name is AliyunAgentCoreDefaultRole. Whether you create a role by using quick authorization or select an existing role, make sure that both of the following system policies are attached to the execution role:

  • AliyunAgentIdentityDataGetCredentialAccess

  • AliyunAgentCoreFullAccess

If either policy is missing after quick authorization, add it as described in Step 3. Attaching these two policies does not grant the agent permissions to access all cloud services. To access OSS or other cloud resources, you must still grant the corresponding permissions.

Use an existing role

  1. In the RAM console, choose Identities > Roles and open the destination role.

  2. On the Trust Policy tab, check the trusted service (workload.agentidentity.aliyuncs.com), actions, and workload identity condition against the configuration below. To make changes, click Edit Trust Policy, complete the configuration, and save it.

  3. Return to AgentCore, refresh the page, and select the role.

    To adjust the service principal or workload identity scope, see Modify the trust policy of a RAM role. Before the modification, check whether the role is used by other workloads to avoid overwriting required trust configurations. If multiple agents share the role, modifying the trust policy, removing permissions, or deleting the role may affect all users of the role.

Trust policy configuration

Check the following trust policy for both new and existing roles:

{
  "Statement": [
    {
      "Action": [
        "sts:AssumeRole",
        "sts:SetContext"
      ],
      "Condition": {
        "StringLike": {
          "sts:RequestContext/agentidentity:WorkloadIdentityArn": "*"
        }
      },
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "workload.agentidentity.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}

This policy sets the trusted service to workload.agentidentity.aliyuncs.com and includes both sts:AssumeRole and sts:SetContext. The * in the condition does not limit the workload identity ARN to a specific value. To limit the role to a specific identity, use the actual workload identity ARN and verify that the agent runs as expected. Before using the role in production, verify the policy in RAM and narrow the workload identity condition as needed.

The preceding JSON configuration is part of the role's Trust Policy, whereas the two system policies in Step 3 are added in the role's Permissions section. Both must be configured.

Step 3: Configure required policies and business permissions

  1. Open the role in the RAM console and go to its permission configuration.

  2. Click Grant permissions, and search for and add the system policies AliyunAgentIdentityDataGetCredentialAccess and AliyunAgentCoreFullAccess. You do not need to add a policy that is already attached.

  3. If the agent also needs to access cloud resources such as OSS, add the system policies or custom policies required by your business.

  4. Check the authorization details, complete the authorization, and make sure that the permission list of the role contains both of the preceding required policies.

  5. Return to AgentCore, refresh the policy information, and check the validation result.

    For example, if the agent needs only to read a specified business file, limit the permissions to the required read operations and destination resource. Do not grant write or delete permissions on unrelated resources. For instructions, see Manage permissions on a RAM role.

Step 4: Save and verify the configuration

  1. Wait for role validation to complete, and resolve validation issues such as a nonexistent role, a trust mismatch, or incomplete authorization.

  2. Save the agent configuration, and wait for the deployment or update to complete. If you use versions and endpoints, make sure that test requests reach the version that contains the current configuration.

  3. Send a request from the agent runtime environment to access an actual destination resource, such as an authorized test file.

  4. Check the business response and logs to confirm that access is successful.

Usage notes

When you configure and use an execution role for a high-code agent, note the following items:

  • Follow the principle of least privilege. Grant only the operations and resource scope required by the business. Use separate roles for development, testing, and production environments. Quick authorization is not a least-privilege solution customized for your business.

  • Check the trust scope. Before using the role in production, check the trust policy that quick authorization generates in RAM and narrow the scope to the applicable workload identities as needed.

  • Distinguish operator permissions from execution role permissions. The current logon identity requires the corresponding RAM permissions to query roles and policies in the console. Granting query permissions to the execution role does not resolve an issue in which the logon identity cannot read a role.

  • Verify permissions by sending actual requests. A selectable role, successful policy validation, or a saved configuration does not guarantee access to the destination resource. If a custom policy cannot pass page validation, check the policy and error message instead of broadening permissions only to clear the validation message.

  • Obtain credentials correctly. A role ARN is only an identity and cannot be directly used to sign API requests. Configuring only a role ARN does not allow any client to automatically obtain the identity. A self-managed application must use an SDK or credential provider that matches its runtime environment.

  • Protect runtime credentials. Do not expose secrets in code, prompts, logs, or frontend responses. If the application manages temporary credentials, use a method that supports credential refresh.

  • Evaluate the impact of changes. Test role changes before scheduling a production change.

FAQ

SymptomTroubleshooting
A role exists in RAM but is not displayed in the drop-down listCheck the service principal and workload identity conditions of the role and the query permissions of the current logon identity. Then, refresh the list.
A message indicates that a role or policy cannot be readCheck the RAM query permissions of the current logon identity and the API error information.
An unauthorized message remains after authorizationWait for the authorization status to update, refresh the page, check the role ARN, and make sure that both AliyunAgentIdentityDataGetCredentialAccess and AliyunAgentCoreFullAccess are attached.
Agent conversations work, but access to cloud resources is deniedCheck the identity that is actually used by the program and the permissions of the role on the destination operation and resource. Rule out an override by old credentials. For example, the program may prioritize an old long-term AccessKey pair and therefore still send requests by using the old identity.
A request times out or cannot establish a connectionCheck the service address, region, DNS, VPC, and public network access conditions. Role authorization does not automatically enable network connectivity.

During troubleshooting, you can record the role ARN, failure time, error code, and RequestId. Do not record AccessKey secret, SecurityToken, or other sensitive information.