:Deploy and use a high-code Agent

Prerequisites

• AgentCore is activated and a workspace is created. For more information, see Manage Workspace.

• A runnable Agent container image is prepared and pushed to Enterprise Container Registry (ACR).

• The startup command, listening port, health check path, and conversation protocol of the application are determined.

• If the application uses platform models, MCP tools, or Skills, the corresponding resources are configured in the target workspace and an execution role with the required permissions is prepared.

Note: This topic describes deploying self-built code to AgentCore managed runtime. It does not describe integrating a locally running Agent into the platform. Self-built HTTP services do not need to be replaced with AgentCoreServer. However, the actual interfaces must match the protocol and path configured in the console.

Step 1: Check the image and application configuration

Before creating, confirm that the image meets the following requirements.

The image repository must be reachable from the Agent runtime environment. The ability to push or pull images locally does not mean the cloud can pull them. For network settings, see "Configure network and logs" below. For image build examples, see Use the Python SDK to quickly create a pro-code Agent.

Step 2: Create a high-code Agent

1. Go to the creation page

1. Log on to the AgentCore console.

2. Select the target region at the top and switch to the target workspace.

3. In the left navigation pane, click Agent, then click Create Agent.

4. In Select creation method, select Custom code / Image.

2. Configure basic information and container image

In the Basic Information area, fill in the following fields.

We recommend using explicit version tags for each release to facilitate deployment verification and troubleshooting.

3. Configure startup and execution role

The execution role is used by the Agent to access cloud resources. It is not the API Key for external calls to the Agent. For role requirements, see Authorization Description on the page.

The state of the selected role determines the authorization options available on the page:

• If the role is displayed as Not created, click Create and authorize with one click. The platform creates the role and attaches the required policies.

• If the role already exists but lacks the required permissions, the page lists the missing permissions. Click One-click authorization to add them, or click Go to the RAM console to authorize to handle the authorization yourself.

• After the authorization is complete, the page displays The authorization is successful and the permission has taken effect. If the authorization is not complete or the permission has not taken effect, try again.

Note: If your browser blocks the authorization pop-up, allow pop-ups and try again. If the current account does not have the required permissions, the page cannot list roles. Contact the Alibaba Cloud account or a permission administrator to grant the permissions.

When using platform models, MCP tools, or Skills, reference the corresponding resources in your code. The high-code creation page does not generate prompts, select models, or register tools for the application like managed Harness does. For integration methods, see the SDK guide for your language.

4. Declare the conversation protocol

In Protocol configuration, click Configure, select the protocols supported by your application, enter the Path, and add Headers as needed. You can declare both protocols simultaneously.

• Path: Enter the actual interface path of the application, starting with /. Do not include the full domain name. For example, if your service uses /v1/chat/completions, change it to that path.

• Header: Enter the fixed request headers required to call the protocol interface. Leave empty if not required. Do not enter the downstream model API Key as the Agent interface authentication information.

After filling, click Save in the dialog.

Note: Declaring a protocol does not automatically generate the corresponding interface for the application, nor does it add tool events. If no protocol is declared, the console debug panel cannot initiate conversations by protocol. If the declaration does not match the actual interface, 404 errors or response parsing failures may occur.

5. Configure runtime resources and health check

In Advanced configuration, adjust the following parameters as needed.

The platform performs health checks based on the configuration. Consecutive check failures affect traffic to the instance and may trigger instance restarts. Therefore, you cannot change only the service port without updating the check port to match.

The following are deployment values for the Python quick start example. They apply only to that example. For other applications, fill in values based on actual implementation.

Note: The default health check path on the creation page is /healthz. Applications using /readyz or other paths must manually update the value. Do not keep the default page value.

6. Configure network and logs

Network configuration

• If the application needs to access public model services or other public endpoints, enable Allow default network interface to access public network.

• If the application needs to access VPC resources in the workspace, enable Allow VPC access. This uses the VPC configuration of the current workspace.

• When VPC access is not enabled, images are pulled over the public network. If ACR has a public access whitelist, add the Current workspace public egress IP shown on the page to the whitelist. After enabling VPC access, the platform attempts to pull images via VPC. Confirm that ACR allows access from the corresponding VPC.

Log configuration

We recommend enabling Enable logs, selecting Log project and Logstore to view runtime logs during deployment or invocation exceptions. The application should also output startup information and error logs for troubleshooting. Avoid printing keys and sensitive business content.

7. Submit

Verify the image version, startup command, service port, protocol path, and health check configuration, then click Create Now in the upper-right corner.

After creation, return to the Agent list and wait for the status to become Running. Hover over the corresponding card and click Details to view saved image version, startup configuration, and protocol declarations in Overview and configuration.

Step 3: Debug in the console

1. Open the Agent details and click Debug.

2. Select the declared protocol from the dropdown and confirm that Debug endpoint is ready.

3. Enter a simple message, such as "Hello, please introduce yourself in one sentence," and click send.

4. Check whether the Agent returns the expected response. Then test requests that require tool invocation or business resource access.

To start a new conversation, click Create session. For troubleshooting, copy the session ID from the page and view the corresponding logs via Runtime logs for the relevant time period.

Note: Whether the execution process and tool calls are displayed depends on the protocol events returned by the application. Selecting AGUI in the console does not automatically add events that the code does not output.

Step 4: Call from your application

1. In the Agent details, click External channel configuration.

2. Click Direct access to view the Endpoint status and invocation address.

3. In Authentication, click Get authentication info and configure the caller with the Header name and API Key shown on the page.

4. Follow the API call instructions and call examples on the page to send requests, using the path and request format consistent with the protocol declaration.

The Endpoint is the access address of the Agent application, not the downstream model provider address. Store the API Key in a trusted server-side configuration. Do not write it into public frontend code or documentation.

For development examples of request bodies and streaming responses, see the AgentCore Python SDK User Guide or Node.js SDK User Guide for "Call Agent services." Self-built servers use their actual protocol implementation.

Update the Agent

1. Push the new image version to ACR.

2. Open the Agent details, click Edit configuration in Overview and configuration. You can also enter from the list card via Edit.

3. Refresh the image version list and select the new version. If the application entry, port, or protocol changes, update the startup command, service port, health check, and protocol configuration accordingly.

4. Click Save and wait for the update to complete. Re-run console debugging and business call verification.

Updates may affect in-flight requests. We recommend performing updates during an appropriate business window. Do not assume the Agent is using the new version based solely on the new image appearing in ACR. Verify in the Agent configuration.

View status and troubleshoot

When contacting technical support, provide the region, workspace ID, Agent ID, failure time, and error message. If available, also provide the session ID or request ID. Do not include API Keys or full sensitive request headers.

Development reference

• Developer Reference

• Use the Python SDK to quickly create a pro-code Agent

• AgentCore Python SDK User Guide

• AgentCore Node.js SDK User Guide