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

Prerequisites

• AgentCore is activated, and a Workspace is created.

• Docker is installed and running on your local machine.

• A Container Registry (ACR) Enterprise Edition instance and an image repository are ready, and you have permission to push images.

Image requirements

Note: When "Allow VPC Access" is disabled, images are pulled over the Internet. If an Internet access whitelist is configured for the ACR instance, add the public egress IP address of the target Workspace to the whitelist. You can find this IP address under "Network Configuration" on the Agent creation page. When "Allow VPC Access" is enabled, the platform attempts to pull images over the VPC. Make sure that the network access configuration of ACR allows access from that VPC.

Step 1: Configure the model connection

Note: If you already have a usable model connection, skip this step. Note down the model connection name and the model name for later use in the code.

1. Log on to the AgentCore console and select the target Workspace.

2. In the left-side navigation pane, click Model Connections, and then click Add Model Connection.

3. Select a model vendor, and set the model connection name to content-model, and configure the API endpoint and API Key as required by the vendor.

4. In Model Configuration, select qwen3.8-max, save the connection, and verify that the model is available. For more information about model configuration, see Manage Models.

Step 2: Create the application files

Create a project directory on your local machine and create the following four files. The example uses the model connection content-model and the model qwen3.8-max. If you use other resources, in app.py, replace the corresponding parameters of core.model(...).

import logging

from agentcore import AsyncAgentCore
from agentcore.server import AgentCoreServer

logging.basicConfig(level=logging.INFO)
core = AsyncAgentCore.auto()
model_client = None


async def startup():
    global model_client
    try:
        # Replace with the model connection name and model name in your current Workspace.
        model_client = await core.model("content-model", model="qwen3.8-max")
    except Exception:
        logging.exception("Agent failed to start")
        await core.aclose()
        raise


server = AgentCoreServer(
    startup=startup,
    shutdown=core.aclose,
    readiness=lambda: model_client is not None,
)


@server.invoke
async def invoke(request, context):
    messages = [
        {"role": message.role.value, "content": message.content}
        for message in request.messages
    ]
    response = await model_client.invoke(messages)
    return response["choices"][0]["message"]["content"]

alibabacloud-agentcore-sdk[server]==0.1.1

FROM python:3.11-slim
WORKDIR /app
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 9000
CMD ["uvicorn", "app:server", "--host", "0.0.0.0", "--port", "9000"]

*
!app.py
!requirements.txt
!Dockerfile

Step 3: Build and push the image

On the ACR repository page, obtain and run the logon command. After you log on, run the following commands in the project directory to build and push the image. Replace IMAGE with the actual image address.

IMAGE='YOUR_REGISTRY_ADDRESS/NAMESPACE/REPOSITORY:quickstart-v1'
docker build --platform linux/amd64 -t "$IMAGE" .
docker push "$IMAGE"

Note: The preceding commands specify the target architecture by using --platform linux/amd64. Keep this parameter when you build the image on ARM devices such as Apple Silicon to avoid producing images that support only arm64.

Step 4: Deploy the Agent

1. In the left-side navigation pane of the target Workspace, click Agent. Click Create Agent, and select Custom Code / Image, and then configure the following parameters.

2. Complete the remaining configurations as needed and confirm to create and deploy the Agent. Wait for the application to be ready. This example does not require environment variables.

Note: The default health check path in the console is /ready. In this example, change it to /readyz. Both the service port and the health check port use 9000.

Step 5: Verify the Agent

1. Open the Agent debugging page, select AG-UI, and send the following message.

Hello! Please describe what you can do in one sentence.

2. Check the conversation result. If the Agent returns an answer as expected, the model call and the application deployment are successful.

FAQ

• The image fails to start: Check the image pull permissions, the image architecture, and the startup command.

• The health check fails: Check the 9000 port and the /readyz path. If the log shows "Agent failed to start", check the exception details that follow.

• The model call fails: Check the model connection name and model name in the code, as well as the model configuration in the console and the permissions of the Agent execution role.

References

For detailed usage of models, MCP, Skill, memory, credentials, and framework integration, see the AgentCore Python SDK User Guide and the AgentCore Node.js SDK User Guide.