使用 Python SDK 快速建立高代碼 Agent - AgentCore

準備工作

已開通 AgentCore 服務，並建立 Workspace。
已在本地安裝並啟動 Docker。
已準備企業版Container Registry ACR 執行個體和鏡像倉庫，並具備鏡像推送許可權。

鏡像要求

檢查項	要求
鏡像架構	必須支援 `linux/amd64`（x86_64）。不要使用僅支援 `arm64` 的鏡像。
Shell 環境	必須同時提供 `/bin/bash` 和 `/bin/sh`，且兩者均可執行。
鏡像倉庫	當前僅支援企業版 ACR。執行個體需開啟公開匿名拉取，鏡像倉庫需設為公開。不要將密鑰或業務資料打入公開鏡像。
網路可達	鏡像倉庫必須從 Agent 運行環境網路可達，並允許平台拉取鏡像。本地能夠推送鏡像，不代表雲端能夠拉取。

說明：未開啟「允許訪問 VPC」時，通過公網拉取鏡像。如 ACR 執行個體配置了公網訪問白名單，請將目標 Workspace 的公網出口 IP 加入白名單；該 IP 可在 Agent 建立頁的「網路設定」中查看。開啟「允許訪問 VPC」後，平台會嘗試通過 VPC 拉取鏡像，需確保 ACR 的網路訪問配置允許該 VPC 訪問。

步驟 1：配置模型串連

說明：已有可用模型串連時，可跳過本步驟。記錄模型串連名稱及其中的模型名稱，後續在代碼中引用。

登入AgentCore控制台，選擇目標 Workspace。
在左側導覽列單擊模型串連，單擊添加模型串連。
選擇模型供應商，模型串連名稱填寫 content-model，按供應商要求配置 API 端點和 API Key。
在模型配置中選擇 qwen3.8-max，儲存串連並驗證模型可用性。模型配置的詳細操作，請參見管理模型。

步驟 2：建立應用檔案

在本地建立專案目錄，並建立以下四個檔案。樣本使用模型串連 content-model 和模型 qwen3.8-max；使用其他資源時，替換 app.py 中 core.model(...) 的對應參數。

app.py：應用入口

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:
        # 改為當前 Workspace 中的模型串連名稱和模型名稱。
        model_client = await core.model("content-model", model="qwen3.8-max")
    except Exception:
        logging.exception("Agent 啟動失敗")
        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"]

應用通過 core.model() 擷取模型用戶端，調用模型後返回回答。AgentCoreServer 提供 AG-UI 和 OpenAI Chat Completions 服務介面。

說明：本樣本返回模型產生的完整回答，不示範逐字輸出或工具調用。應用轉寄請求中已有的對話訊息，不額外儲存聊天歷史。

requirements.txt：依賴聲明

alibabacloud-agentcore-sdk[server]==0.1.1

Dockerfile：鏡像構建配置

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"]

說明：本樣本使用的 python:3.11-slim 已提供 /bin/bash 和 /bin/sh，無需額外安裝。更換基礎鏡像時，請確保滿足前述鏡像要求。

.dockerignore：構建檔案範圍

*
!app.py
!requirements.txt
!Dockerfile

步驟 3：構建並推送鏡像

在 ACR 鏡像倉庫頁面擷取並執行登入命令。登入成功後，在專案目錄執行以下命令，構建並推送鏡像。將 IMAGE 替換為實際的鏡像地址。

IMAGE='你的Registry地址/命名空間/倉庫名:quickstart-v1'
docker build --platform linux/amd64 -t "$IMAGE" .
docker push "$IMAGE"

說明：上述命令已通過 --platform linux/amd64 指定目標架構。在 Apple Silicon 等 ARM 裝置上構建時也需保留此參數，避免產生僅支援 arm64 的鏡像。

步驟 4：部署 Agent

在目標 Workspace 左側導覽列，單擊 Agent。單擊建立 Agent，選擇自訂代碼 / 鏡像，配置以下參數。

參數	說明
Agent 名稱	樣本：`my-first-agent`
容器鏡像	選擇已推送鏡像所在的 ACR 倉庫及 `quickstart-v1` 版本
啟動命令	`uvicorn app:server --host 0.0.0.0 --port 9000`
服務連接埠	`9000`。與應用監聽連接埠保持一致。
執行角色	選擇已授權該 Agent 訪問所需資源的角色
協議配置	啟用 AG-UI，路徑為 `/ag-ui/agent`
進階配置 → 健全狀態檢查	路徑設定為 `/readyz`，連接埠設定為 `9000`

按需完成其餘配置，確認後建立並部署 Agent，等待應用就緒。本樣本無需配置環境變數。

說明：控制台健全狀態檢查預設路徑為 /ready，本樣本需修改為 /readyz。服務連接埠和健全狀態檢查連接埠均使用 9000。

步驟 5：驗證 Agent

開啟 Agent 調試頁面，選擇 AG-UI，發送以下訊息。

你好，請用一句話介紹你能做什麼。

查看對話結果。Agent 正常返回回答，表示模型調用和應用部署成功。

常見問題

鏡像無法啟動：核對鏡像拉取許可權、鏡像架構和啟動命令。
健全狀態檢查失敗：核對 9000 連接埠和 /readyz 路徑；如日誌顯示「Agent 啟動失敗」，繼續查看後面的異常原因。
模型調用失敗：核對代碼中的模型串連名、模型名，以及控制台的模型配置和 Agent 執行角色許可權。

瞭解更多

模型、MCP、Skill、記憶、憑證及框架組成的詳細用法，請參見 AgentCore Python SDK 使用指南與 AgentCore Node.js SDK 使用指南。