A high-code Agent hosts your self-developed application in AgentCore. This guide walks through two deployment paths — container image and code package — and covers how to call the deployed Agent from a business application and how to view its runtime status and troubleshoot issues.
Choose one deployment path and complete its preparation, creation, configuration, and verification steps in order:
| Deployment method | What you need to prepare | Key limits | Reading path |
| Container image | An application image pushed to Container Registry Enterprise Edition (ACR) | The image must be Linux x86_64 (linux/amd64). The Agent runtime must be able to pull the image from the ACR repository. Update by selecting a new image version in Edit configuration. | Part 1: Deploy by using a container image |
| Code package (Recommended for a first deployment) | A ZIP file that contains the application and its dependencies, or a console sample | Supports Python 3.12, Node.js 22, and Java 17, subject to the Runtime list for the region and Workspace. Compressed package: no more than 500 MB (500,000,000 bytes). Extracted package: no more than 2 GiB. No ACR image is required. Update by re-uploading or revalidating the package. | Part 2: Deploy by using a code package |
Both deployment paths share the create-page settings in Common configuration. After deployment, call the Agent from a business application (Part 3: Call the Agent from a business application) or view runtime status and troubleshoot issues (Part 4: View runtime status and troubleshoot issues). For application development and SDK integration, see Development reference.
Prerequisites
Both deployment paths
AgentCore is activated and a Workspace is created. For details, see Manage a Workspace.
An Agent execution role is prepared. If the application uses platform models, MCP, Skills, or other resources, configure those resources in the target Workspace and grant the required access permissions.
The application provides a runnable HTTP service whose actual endpoints match the protocol and path declared in the console. For an initial code-package deployment, you can use a platform sample.
(Optional) To collect application logs, a Log project and Logstore in Simple Log Service (SLS).
(Optional) If the application needs to access resources over a private network, a Virtual Private Cloud (VPC) configured for the Workspace, with the target resources in place.
Container image path (Part 1)
An application image pushed to an ACR Enterprise Edition instance. Pull access depends on the network path you use. For details, see Network and logs.
Code-package path (Part 2)
A ZIP file that contains the application and its actual runtime dependencies, or a plan to use a console sample. Compressed package: no more than 500 MB (500,000,000 bytes). Extracted package: no more than 2 GiB. Supported runtimes: Python 3.12, Node.js 22, and Java 17, subject to the Runtime list for the current region and Workspace.
(OSS source only) An Object Storage Service (OSS) bucket in the current account and region that contains the ZIP package. You complete the bucket authorization on the creation page.
Common configuration
Both deployment paths use the same creation-page settings for the startup method and execution role, the conversation protocol, runtime resources and health checks, and network and logs. The procedures in Part 1 and Part 2 point to this section at the configuration step. Path-specific guidance is labeled accordingly.
Startup method and execution role
Configure the following settings on the creation page:
| Configuration item | Instructions |
| Startup command | Enter the executable command that starts the application. For an image deployment, the command path and entry file must match the image contents. For a code-package deployment, the command is relative to the code-package root directory, such as node main.js. |
| Service port | Enter the port on which the application listens. The value must match the port bound by the application. For example, enter 9000 when the startup command binds port 9000. |
| Execution role | Select a role that has access to the resources required by the application. Use View policies to verify the permissions. |
| Environment variables | Add names and values as required by the application. You can use form mode or JSON mode. |
The execution role enables the application to access cloud resources. When you use a model, MCP, or Skill, integrate it in the application code. For integration methods, see the applicable SDK guide.
Handle execution-role authorization in Resource Access Management (RAM) according to the status shown on the page:
| Page status | Action |
| Not created | Click Create and authorize with one click. |
| The role exists but lacks permissions | Use One-click authorization for the missing permissions listed on the page, or click Go to the RAM console to authorize. |
| Authorization is incomplete or not yet effective | Complete authorization, check the status again, and retry if needed. |
| Authorization successful. Permissions have taken effect. | Continue with the remaining configuration. |
If the authorization window is blocked, allow pop-up windows and try again.
Conversation protocol
Under Protocol configuration, click Configure, select a protocol implemented by the application, enter the Path, and add a Header if needed. You can select both protocols. Save the configuration after completing it.
| Protocol | Purpose | Prefilled path |
| Chat Completions | Receives requests in the OpenAI Chat Completions format. | /openai/v1/chat/completions |
| AGUI | Receives AG-UI requests and returns streaming events. | /ag-ui/agent |
The console displays the AG-UI protocol as AGUI.
The path must start with /, must match the actual application route, and must not include a domain name. For example, if the application uses /v1/chat/completions, replace the prefilled path with that path.
Use Header for fixed request headers required by the Agent protocol endpoint. Leave it empty when none are required. Do not enter a downstream model API key here.
The protocol declaration determines which protocols are available for console debugging and how requests are routed to the application. Selecting a protocol does not create an endpoint or tool events automatically. AGUI execution progress and tool events depend on the protocol events emitted by the application. External systems call the Agent by using the invocation URL and authentication information on the Endpoint page, as described in Part 3: Call the Agent from a business application. Omitting a protocol, or declaring a protocol that does not match the actual route or response format, can affect console debugging.
Runtime resources and health check
Under Advanced configuration, configure the settings required by the application:
| Configuration item | Description |
| Specification | Select the required CPU and memory. |
| Instance count | Set the number of running instances. |
| Max sessions per instance | Set the value according to the application's concurrent-processing capacity. |
| Session TTL (seconds) | Set the lifetime of a platform session. This is not a model-generation timeout. |
| Session isolation method | Select Not enabled, Session affinity, or Header isolation as needed, and complete the corresponding configuration. |
| Health check | Enter the actual values for Health Check Path, Health Check Port, Health Check Interval, timeout, Healthy Threshold, and Unhealthy Threshold. |
A failed health check can cause an instance to stop receiving traffic or restart. After you change the application port, also verify the health check port.
Network and logs
| Configuration item | Instructions |
| Allow default network interface to access public network | Enable this option when the application needs to access a public model, tool, or other service. |
| Allow VPC access | Enable this option when the application needs to access resources in the Workspace VPC. |
| Enable logs | Enable this option and select an SLS Log project and Logstore to view collected application logs. |
Container image path — Check ACR network access control for the image-pull path. If VPC access is not enabled, the Agent pulls the image over the public network: enable anonymous public pulls for the ACR Enterprise Edition instance and use a public repository as required by the creation page, and add the Workspace public egress IP displayed on the page to the ACR public access whitelist when required. If VPC access is enabled, confirm that the repository allows access from the corresponding VPC.
Code-package path — A code-package deployment does not require you to configure a private ACR repository. External services required by business code must still meet the applicable network requirements. The Hello World code-package sample does not need to connect to a real model.
The application should output the startup and error logs needed for troubleshooting. Do not log secrets or sensitive content.
Part 1: Deploy by using a container image
This workflow starts with image preparation and covers Agent creation, debugging, and later image updates.
Prepare a container image
Verify that the image and its repository meet the following requirements:
| Check item | Requirement |
| Architecture | Must be Linux x86_64, also written as linux/amd64. |
| Shell | Provides executable /bin/bash and /bin/sh. |
| Runtime artifacts | Contains the application, its dependencies, and the files required to start it. |
| Image repository | Uses an ACR Enterprise Edition instance. Pull access follows the creation-page requirements for the network path you select. For details, see Network and logs. |
| Network | The Agent runtime can access the image repository. Configure access control for the selected public-network or VPC path. |
Do not include secrets or business data in a public image.
For an image build example, see Create a high-code Agent by using the Python SDK.
The application must listen on 0.0.0.0 and implement a health check and the required conversation endpoints. Before you create the Agent, confirm the actual startup command, service port, health check path, and protocol path.
Create an Agent and select an image
Log on to the AgentCore console, and select the target region and Workspace.
Open the Agent list, click Create Agent, and select Custom code / Image.
Enter an Agent name and an optional description.
Under Select code source, select Container image.
Select Container image instance, Image repository, and Image version in sequence:
| Field | Instructions |
| Container image instance | Select the prepared ACR Enterprise Edition instance. Refresh the list after you create an instance. |
| Image repository | Select the repository that contains the application image. |
| Image version | Select the tag to deploy. Use the digest, image size, and most recent push time to verify the selection. |
Use an explicit version tag for each release so that you can verify the deployed content.
Configure the create page
Configure the startup method and execution role, the conversation protocol, runtime resources and health checks, and network and logs. These settings are common to both deployment paths. For details, see Common configuration, and check the ACR pull-access guidance for the container image path in Network and logs.
Create a high-code Agent by using the Python SDK uses the following example values. Configure other applications according to their actual implementation:
| Configuration item | Example value |
| Startup command | uvicorn app:server --host 0.0.0.0 --port 9000 |
| Service port | 9000 |
| Health check path / port | /readyz / 9000 |
| Protocol / path | AGUI / /ag-ui/agent |
Submit the creation request and verify the Agent
Verify the image version, startup command, service port, execution role, protocol, and health check, then click Create Now.
Return to the Agent list to view the status of the Agent. Open the details page, and verify the saved image and runtime settings under Overview and configuration.
Wait for the instance and debug endpoint to become ready. Don't continue to the next step until you can open Debug and select a declared protocol.
Send a simple message and confirm that the Agent responds. Then verify calls to models, tools, or business resources.
To start a new conversation, click Create session.
If an error occurs, record the session ID and failure time, open Runtime logs, and troubleshoot the issue as described in Part 4: View runtime status and troubleshoot issues.
Update the image
Build the new image and push it to ACR.
In Overview and configuration on the Agent details page, open Edit configuration.
Refresh the image-version list, select the new version, and update the entry point, port, protocol, and health check if they changed.
Save the configuration, wait for the update to complete, and verify console debugging and business calls again.
Pushing an image does not replace the Agent configuration. Verify the version selected on the details page.
If the new version misbehaves, roll back by opening Edit configuration again and selecting the previous image version.
An update can affect requests in progress. Perform it during an appropriate business window.
Part 2: Deploy by using a code package
This workflow uses a platform runtime and does not require a container image. You can upload a local ZIP file, import a ZIP file from OSS, or use a console sample.
Prepare a code package
Code packages support Python 3.12, Node.js 22, and Java 17. The available options are determined by the Runtime list for the current region and Workspace. Before you package the application, confirm that its runtime appears in that list. A code-package deployment does not require you to prepare an ACR image.
Format and runtime requirements
| Check item | Requirement |
| File format | A non-empty ZIP file. |
| Compressed package size | No more than 500 MB (500,000,000 bytes). |
| Extracted size | No more than 2 GiB. |
| Application dependencies | Package the application code with its actual runtime dependencies or build artifacts. The platform does not automatically install dependencies or build the project. |
| Runtime compatibility | Compatible with the selected language version and the Linux x86_64 environment. |
| Entry location | A file path in the startup command is relative to the root directory after the code package is extracted. |
| Archive paths | Use relative paths in the package. Do not include absolute paths, .. in paths, or links outside the package. |
| HTTP service | Listens on 0.0.0.0, and uses the same port as the Service port value in the console. |
| Health check and protocol | Implements the corresponding endpoints, and uses paths that match the console configuration. |
Prepare dependencies locally or in CI. For an application that uses native extensions, binary dependencies, or Java Native Interface (JNI), verify operating-system, CPU-architecture, and language-version compatibility. Do not package incompatible dependencies built for macOS, Windows, or ARM environments. A dependency descriptor such as requirements.txt, package.json, or pom.xml does not replace actual runtime dependencies.
Package structure and startup commands
| Runtime | Example package structure | Startup command |
| Python 3.12 | The root directory contains main.py, and dependencies are under python/. | python main.py |
| Node.js 22 | The root directory contains main.js, package.json, and node_modules/. | node main.js |
| Java 17 | The root directory contains an executable app.jar. Make external dependencies available to the application through its Class-Path configuration. | java -jar app.jar |
Enter the project directory and package the runtime files in that directory:
cd my-agent
zip -r ../package.zip .This command places the entry file at the ZIP root. If the actual package structure is my-agent/main.py, enter python my-agent/main.py as the startup command. The platform does not automatically remove an outer directory.
To run multiple startup commands, put the logic in start.sh in the code package and enter sh start.sh as the startup command.
Create an Agent and select a runtime
Log on to the AgentCore console, and select the target region and Workspace.
Open the Agent list, click Create Agent, and select Custom code / Image.
Enter an Agent name and an optional description.
Under Select code source, select Upload code package to deploy from a code package. You select the specific source — local upload, OSS, or a sample — in the next step.
Under Runtime, select the language environment that matches the application. If the list does not load, click Retry.
Provide a code package
| Source option | Scenario | Method |
| Upload code package | The ZIP file is on your local computer. | Select or drag the ZIP file from your local computer. |
| Use OSS code package | The ZIP file is already stored in OSS, for example, as a CI build output. | Select a bucket, enter an object path, and validate the package. |
| Create from sample code | (Recommended for a first deployment) You want to deploy a runnable sample without preparing your own code. | Use the sample code for the selected runtime. |
Upload code package appears at two levels on the creation page: as the code source under Select code source, and as the local-upload option under the code-package source options.
Method 1: Upload a local code package
Under the code-package source options, select Upload code package.
Click Click to upload, or drag the ZIP file to the upload area. The upload starts automatically. Wait for Code package uploaded successfully! to appear.
(Optional) To replace the file, click Re-upload or select another file, and wait for the new upload to finish.
Continue with the startup settings and the remaining deployment configuration.
A file name in the upload area does not mean that the upload is complete. If an upload fails, check the file format, size, and network connection, and then retry.
Method 2: Use an OSS code package
Under the code-package source options, select Use OSS code package.
Under Bucket name, select a bucket in the current account and region. You can search for a bucket name or refresh the list.
If the page shows that bucket authorization is required, click Go to authorize, complete the authorization as prompted, return to the page, and refresh the authorization status. This authorization enables the platform to read the deployment file. It is separate from the execution role, which enables the application to access cloud resources.
In OSS directory, enter the complete object path of the ZIP file, including the file name.
Click Validate code package. When Code package is ready to submit and save appears, complete the remaining deployment configuration.
Use the following values as an example:
| Field | Example value | Description |
| Bucket name | my-agent-code-bucket | The bucket that contains the code package. |
| OSS directory | releases/v1/package.zip | The complete object path in the bucket, including the ZIP file name. |
For OSS directory, enter the object path. Do not enter only releases/v1/, and do not enter a complete URL that includes the bucket name.
You do not need to make the bucket publicly readable to import a code package. Bucket authorization and code-package validation are separate steps. After authorization, click Validate code package for the specific file. The authorization page lists object read, write, and delete permissions. Verify the authorization scope displayed on that page.
You do not need to configure Mount OSS for an OSS code-package source. Configure a data mount separately only when the application needs to mount business data.
How AgentCore handles an OSS code-package source:
Validation scope — Validation checks whether the file exists, meets the size requirements, and can be read. It does not start the application. Validate again after you change the bucket or object path.
Source file availability — Keep the source file readable until you save the configuration. Do not overwrite or delete it during this period.
Saved copy — After you save the configuration, the platform keeps its own copy of the code package. Overwriting the OSS object does not update the deployed Agent, and changing other settings while retaining the current code package does not reread the latest file from OSS. To deploy new content, use Update code package, as described in Update a code package.
Download — Downloading the code package returns the copy saved in the current configuration, not the current OSS object. For details, see Download the current code package.
Method 3: Create from sample code
Select the required Runtime.
Select Create from sample code. The page selects the corresponding sample package and fills in its startup command.
Verify the service port, health check, and conversation protocol settings.
Configure or leave empty the model environment variables, depending on whether the sample must call a real model.
Complete the remaining deployment configuration and submit the creation request.
The available samples are as follows:
| Runtime | Sample name | Startup command |
| Python 3.12 | Python 3.12 Sample | python main.py |
| Node.js 22 | Node.js 22 Sample | node main.js |
| Java 17 | Java 17 Sample | java -jar app.jar |
All three samples use the same service and protocol settings:
| Configuration item | Value |
| Service port | 8080 |
| Health check path | /healthz |
| Health check port | 8080 |
| Conversation protocol | AGUI |
| Protocol path | /ag-ui/agent |
Sample mode adds the AGUI protocol. If you previously configured an AGUI path or request header, verify that it applies to the selected sample.
After selecting a runtime, you can click Download sample code package and follow the dialog box to download the corresponding code. The sample package includes the dependencies required to run it and can be deployed directly. Package the application again after you modify a sample.
The sample supports the following case-sensitive, uppercase environment variables:
| Environment variable | Meaning |
AGENTCORE_MODEL_CONNECTION | The model connection name in the current Workspace. |
AGENTCORE_MODEL_NAME | The model name to call. |
The page adds these two environment-variable names and retains existing values with the same names. Runtime behavior varies with the variable configuration:
| Configuration | Runtime behavior |
| Both variables are omitted or empty | AGUI returns a message that the two variables are missing, and outputs Hello World. |
| Only one variable is configured | Returns an error message that the other variable is missing. |
| Both variables are configured | Calls a real model through the SDK. |
(Recommended) For an initial experience, leave both variables empty. Before calling a real model, configure the Workspace model connection and ensure that the execution-role permissions and network meet the access requirements. If model resolution or invocation fails, the sample returns an error message.
The sample provides tools, MCP, and Skill integration as comments. Add the implementation required by the business scenario and package the application again.
Configure the create page
After you upload a code package, validate an OSS package, or select a sample, configure the startup method and execution role, the conversation protocol, runtime resources and health checks, and network and logs. These settings are common to both deployment paths. For details, see Common configuration, including the code-package guidance in Network and logs. For code-package deployment, also note the following:
A code-package deployment does not require an OSS mount path or an extraction command.
For your own application, change the page defaults to match its actual listening port and health check path instead of retaining them.
Submit the creation request and verify the Agent
Verify the runtime, code package, startup command, service port, execution role, protocol, and health check, then click Create Now.
Return to the Agent list to view the status of the Agent. Under Overview and configuration on the details page, verify the saved code package and runtime settings.
Wait for the instance and debug endpoint to become ready. Open Debug and select a protocol declared by the application.
When you use a code-package sample from this guide, select AGUI and send a simple message. When both model environment variables are empty, expect a message about the missing variables and the Hello World output. When both are configured, expect a response from the real model.
After the basic call succeeds, verify tools and other business-resource access. To start a new conversation, click Create session.
If an error occurs, record the session ID and failure time, open Runtime logs, and troubleshoot the issue as described in Part 4: View runtime status and troubleshoot issues.
A successful upload or validation completes only that step. The platform saves the code package, extracts it at startup, and runs the entry command. Verify that the application can start and be called successfully before you consider the deployment complete.
Update a code package
Open the Agent details page, and select Edit configuration under Overview and configuration.
Select an update method as needed:
Update content Method Only the startup command, environment variables, or other settings change Retain the current code package and modify the required settings. Application code changes Click Update code package, select a local upload, OSS code package, or sample source, and complete the required upload or validation. Cancel the current code-package replacement Click Cancel update to restore the runtime and startup command for the original package, and then verify other edited settings. Verify the runtime, startup command, service port, health check, and protocol, then click Save.
Wait for the update to complete, and verify console debugging and business calls again.
Cancel update cancels a replacement that has not been submitted yet. To roll back an update that has already taken effect, click Update code package, reselect and validate the previous code-package source, and save the configuration.
Overwriting a file at an existing OSS path does not automatically update the deployed Agent. For example, after you overwrite releases/package.zip, deploy the new content by selecting Update code package in the Agent, selecting and validating the source again, and saving the configuration.
An update can affect requests in progress. Perform it during an appropriate business window.
Download the current code package
Open Overview and configuration on the Agent details page.
Under Code configuration, view the Runtime and Code package.
Click the code-package file name to download it.
You can download a saved code package that was uploaded locally, imported from OSS, or created from a sample by using this entry.
The downloaded content is the code package saved in the current configuration. It does not include files or modifications generated while the application was running. To retain runtime-generated data, use the application's own persistent storage or configure a separate data mount. Runtime files are not written back to the code package automatically.
Download links expire. If a link expires or a download fails, return to the page and click the code-package file name again to obtain a new link.
Part 3: Call the Agent from a business application
This call method applies to both image-based and code-package Agents that have completed deployment. External systems call the Agent through the Endpoint, which is the Agent entry address, by using the authentication information on the Endpoint page. The application uses its own integration method for model-service addresses and credentials.
In Agent details, open External channel configuration, and select Direct access.
Confirm that the Endpoint is available, and obtain the invocation URL.
Under Authentication, click Get authentication info and configure the required header and API key as prompted. Store the API key in trusted server-side configuration.
Use API call instructions and its examples to construct a request with the protocol path declared by the application.
Send the request, and verify the regular or streaming response.
For request formats, see the SDK guides in Next steps.
Part 4: View runtime status and troubleshoot issues
Runtime status entries
| Entry | Purpose |
| Overview and configuration | View the image version or code-package runtime, startup command, port, environment variables, and protocol. |
| Instances and sessions | View instances and sessions, and record IDs associated with an error. |
| Observability > Basic monitoring | View runtime data for the period in which the error occurred. |
| Observability > Runtime logs | Query collected application logs. |
Common issues
The following issues can occur in both image-based and code-package deployments:
| Symptom | What to check |
| An instance is not ready or restarts | Check the entry point and dependencies, resource specification, listening address, service port, and health check port. For image deployment, also check the architecture and shells. |
| No protocol is available on the debug page | Edit the configuration, declare the protocols implemented by the application, and save. |
| A request returns 404 or a response parsing error | Verify the actual route, protocol path, and response format. |
| Authentication fails | Check the endpoint authentication information (Part 3: Call the Agent from a business application) or the application execution-role permissions, according to the failure location. |
| A simple conversation succeeds but resource calls fail | Check the resource name, Workspace, permissions, and network. |
| No runtime logs are available | Check the log switch, Log project, and Logstore. Confirm that the application outputs logs and that the query time is correct. |
Image deployment issues
| Symptom | What to check |
| An image cannot be selected or pulled | Verify the ACR instance, repository, image version, and access control. Follow the page guidance. |
Code-package issues
| Symptom | What to check |
| A local file cannot be selected or the upload is rejected | Check that the file is a non-empty ZIP and does not exceed 500 MB (500,000,000 bytes). |
| A module or dependency is missing at startup | Package the actual runtime dependencies or build artifacts with the application. The platform does not automatically install dependencies. |
| The application runs locally but reports a binary-loading error after deployment | Verify that dependencies match Linux x86_64 and the selected language version. |
| The required OSS bucket is unavailable | Verify the account, region, and access permissions. Search for or refresh the bucket list. |
| The page cannot be submitted after entering OSS directory | Ensure that the path includes the ZIP file name, complete bucket authorization, and click Validate code package. |
| OSS validation succeeds but the application fails to start | Check whether the ZIP is damaged, the extracted size exceeds the limit, the entry file exists, and dependencies are complete. Then view runtime logs. |
| The startup process cannot find the entry file | Check whether the ZIP contains an extra outer directory, and make the startup command match the actual package path. |
| Secure extraction fails | Check archive paths and extracted size. Remove absolute paths, traversal paths, and links outside the package, then package the application again. |
| A sample reports missing model variables and returns Hello World | This is expected when both model variables are empty. Configure both variables to call a real model. |
| A sample reports that only one model variable is missing | Provide the variable named in the message. To experience Hello World only, leave both model variables empty. |
| The Agent continues to run old code after an OSS file is updated | In the Agent, select Update code package, validate the source again, and save. |
| The page has no separate Download code package button | Under Overview and configuration > Code configuration, click the code-package file name to download it. |
When requesting troubleshooting assistance, provide the region, Workspace ID, Agent ID, failure time, and error information. Include the related request ID or session ID when available. Do not provide API keys or complete request headers that contain credentials.
Next steps
For an overview of application development and SDK integration, see Development reference.
For an image build example, see Create a high-code Agent by using the Python SDK.
For Python development, see AgentCore Python SDK user guide.
For Node.js development, see AgentCore Node.js SDK user guide.