文档首页/ 智果（AgentArts）智能体平台/ 最佳实践/ 运行时实践/ 通过控制台托管智能体到运行时

更新时间：2026-09-24 GMT+08:00

通过控制台托管智能体到运行时

概述

AgentArts支持自行制作Agent镜像并推送到SWR镜像仓库后，通过控制台可视化界面创建运行时，可对镜像版本、资源配置、网络与认证等参数进行精细控制，适合已有成熟Agent镜像、需要精细控制配置、习惯可视化操作的场景。

本文以一个基于LangChain的对话Agent为例，引导您手动制作镜像、推送到SWR，并通过AgentArts控制台将本地Agent代码部署到运行时，再完成调用验证。

本文操作流程如图1所示，主要包含以下步骤：

步骤一：准备Agent代码：编写Agent核心逻辑并封装为符合平台规范的HTTP服务。
步骤二：本地验证：启动服务并验证健康检查与对话接口。
步骤三：手动制作镜像并通过控制台部署：构建镜像、推送SWR，并在控制台创建运行时。
步骤四：调用Agent：通过SDK或HTTP API调用已部署的智能体。

图1 操作流程

前置条件与环境准备

在开始之前，请确认以下准备工作已完成：

账号与服务：

已开通AgentArts服务，并在“管理中心 > 授权管理”页面完成依赖云服务授权。

本地环境：

操作系统：推荐使用Linux Ubuntu 22.04 ARM64，服务器可访问公网。
本文命令如无特殊说明，均以Ubuntu为例。为保证镜像构建与云端部署的兼容性，建议使用Ubuntu系统。

因此，为了减少部署失败和额外排查成本，建议直接使用Ubuntu 22.04 ARM64制作AgentArts镜像。

若使用CentOS、EulerOS等非Ubuntu系统，请将下命令中的apt替换为yum或dnf，并自行确认Docker 18.06+、Python 3.10+；本文不逐条展开各发行版安装差异。

需使用ARM64系统制作的Agent镜像，使用X86系统制作的镜像在调用智能体运行时会调用失败。

可以使用华为云ECS服务购买服务器，购买时需要选择鲲鹏架构（ARM64），系统选择Ubuntu。
安装Python：请确保Python 3.10及以上版本已安装。
大多数Linux发行版（如Ubuntu）都预装了Python，您可以先通过python3 --version检查。如未安装，可以使用如下命令安装：
```
sudo apt update
sudo apt install python3
```
非Ubuntu/Debian系统请使用yum或dnf安装Python 3.10+及pip。
安装Docker：请确保Docker 18.06及以上版本已安装。如未安装，可以使用如下命令安装：
```
# 查询 Docker 版本
docker --version

# 安装Docker
sudo apt update
sudo apt install docker.io
```
安装完成后，建议立即配置国内镜像加速器。在后续执行agentarts launch构建镜像时，Docker需要拉取python:3.10-slim基础镜像，默认从docker.io官方仓库下载，可能超时失败。提前配置加速器可避免此问题。

执行以下命令创建Docker配置目录：
```
sudo mkdir -p /etc/docker
```
执行以下命令配置国内镜像源（直接复制并回车执行）：
```
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors":[
    "https://docker.m.daocloud.net",
    "https://dockerproxy.net",
    "https://mirror.baidubce.com"
  ]
}
EOF
```
依次执行以下命令重启Docker服务，使配置生效：
```
sudo systemctl daemon-reload
sudo systemctl restart docker
```
华为云SWR基础版不支持OCI镜像格式，如果您使用的是Docker 27及以上版本，并且需要处理OCI镜像，可以通过设置环境变量来关闭OCI支持。
```
export DOCKER_BUILDKIT=0
# 或者
export BUILDKIT_USE_OCI_MEDIA_TYPES=0
```
执行以下命令安装SDK（建议在Python虚拟环境中安装，以避免与系统包产生冲突）。
```
# 安装依赖包
apt install python3.12-venv

# 创建并激活虚拟环境 (linux) 
python3 -m venv venv
source venv/bin/activate

# 安装sdk
pip install agentarts-sdk
```
若配置镜像加速器，后续在执行agentarts launch命令时，仍无法拉取 python:3.10-slim，可参考本文结尾的“常见问题”中的“直接修改Dockerfile基础镜像地址”。
- 执行pip install agentarts-sdk命令下载缓慢、超时可以更改为使用如下命令
```
pip install agentarts-sdk -i https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com
```
- 如果系统缺少python3-venv包，导致无法创建虚拟环境，请按照命令回显提示安装python3-venv包。

执行以下命令配置华为云凭证，获取华为云凭证请参考认证鉴权。

export HUAWEICLOUD_SDK_AK="your-access-key"
export HUAWEICLOUD_SDK_SK="your-secret-key"

步骤一：准备Agent代码

创建项目目录。

在终端执行以下命令，创建项目目录并进入：
```
mkdir my-first-agent && cd my-first-agent
```

配置环境变量。

在项目根目录下创建.env文件，用于存放模型调用所需的配置信息。

执行vi .env命令创建.env文件，写入以下内容，并将model_api_key替换为您实际的模型API Key。

# .env

# 必填，您的华为云 MaaS API 密钥
MODEL_API_KEY=model_api_key

# 模型名称
MODEL_NAME=deepseek-v4-flash

# 模型服务地址
MODEL_URL=https://api.modelarts-maas.com/openai/v1

# Agent 服务监听端口（可选，默认 8080）
AGENT_RUN_PORT=8080

执行如下命令安装langchain、langgraph、langchain-openai。
```
pip install -U langchain langgraph langchain-openai
```

编写Agent核心逻辑。

在项目根目录执行vi agent.py命令，写入以下内容并保存。

# agent.py

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

# 加载 .env 文件中的环境变量
load_dotenv()


class MyAgent:
    """基础对话智能体"""

    def __init__(self):
        # 初始化大模型客户端
        self.llm = ChatOpenAI(
            model=os.getenv("MODEL_NAME", "deepseek-v4-flash"),
            openai_api_key=os.getenv("MODEL_API_KEY"),
            openai_api_base=os.getenv(
                "MODEL_URL", "https://api.modelarts-maas.com/openai/v1"
            ),
        )
        self.system_prompt = (
            "你是一个友好、专业的 AI 助手，请用简洁清晰的语言回答用户的问题。"
        )

    def chat(self, message: str) -> str:
        """接收用户消息，调用大模型，返回回复内容"""
        messages = [
            SystemMessage(content=self.system_prompt),
            HumanMessage(content=message),
        ]
        response = self.llm.invoke(messages)
        return response.content


# 创建 Agent 单例，供 app.py 引用
agent = MyAgent()

验证Agent逻辑是否正常。
在终端执行以下命令，直接调用agent.py进行快速验证，确认模型调用链路没有问题：
```
python3 -c "from agent import agent; print(agent.chat('你好，请用一句话做个自我介绍。'))"
```
如果模型调用正常，终端会输出模型的回复内容。

如果此步骤报错，请优先排查以下问题：
- .env文件中的MODEL_API_KEY是否已替换为实际值。
- 当前网络环境是否可以访问api.modelarts-maas.com。

封装为HTTP服务。

AgentArts运行时通过标准HTTP接口与您的Agent通信。本步骤使用AgentArts运行时SDK将Agent逻辑封装为符合平台规范的HTTP服务。

在项目根目录执行vi app.py命令，写入以下内容并保存。

# app.py

import os
from typing import Dict, Any
from dotenv import load_dotenv
from agentarts.sdk import AgentArtsRuntimeApp, RequestContext
from agent import agent

load_dotenv()

app = AgentArtsRuntimeApp()


@app.entrypoint
async def handler(payload: Dict[str, Any], context: RequestContext = None) -> Dict[str, Any]:
    """
    AgentArts 平台标准 HTTP 暴露入口。
    - payload：用户传入的完整请求体（dict 格式）
    - context：请求上下文，包含 session_id 等平台注入信息
    """
    message = payload.get("message", "")
    if not message:
        return {"response": "请求体中缺少 message 字段", "status": "error"}

    try:
        reply = agent.chat(message)
        return {"response": reply, "status": "success"}
    except Exception as e:
        return {"response": f"执行出错: {str(e)}", "status": "error"}


if __name__ == "__main__":
    port = int(os.getenv("AGENT_RUN_PORT", 8080))
    app.run(host="0.0.0.0", port=port)

AgentArtsRuntimeApp是AgentArts SDK提供的运行时封装类，负责处理平台与Agent之间的通信协议，以及健康检查接口的注册。
@app.entrypoint装饰器将handler函数注册为平台的HTTP调用入口，平台每次调用Agent时都会触发此函数。

步骤二：本地验证

在部署到云端之前，先在本地确认服务启动正常、接口响应符合预期。

启动本地服务。

在正式推送镜像之前，先在本地模拟云端HTTP调用环境，验证Agent的接口封装是否正确、通信是否正常，可以大幅降低因接口问题导致云端部署后才发现错误的调试成本。

执行python app.py启动http server，执行以下命令调用验证Agent的HTTP接口是否已经被正确封装且能正常通信。

执行python app.py回显效果如下。
验证健康检查接口。

打开一个新的终端窗口（保持原窗口运行），执行以下命令，验证 /ping 健康检查接口是否正常：
```
curl http://localhost:8080/ping
```
返回类似{"status": "Healthy"}内容说明服务已正常启动，平台的健康探查可以通过。
验证对话接口。

在新终端中执行以下命令，验证/invocations对话接口是否正常：
```
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"message": "你好，请用一句话做个自我介绍。"}'
```
收到模型回复后，说明Agent逻辑和HTTP封装均工作正常。

两项验证均通过后，返回第一个终端，按Ctrl+C停止本地服务，继续进行后续的部署操作。

步骤三：手动制作镜像并通过控制台部署

准备依赖文件。

按上述步骤验证完成后，接下来将智能体打包并部署到AgentArts云端运行时。在构建镜像之前，需要先准备依赖清单文件，镜像构建时将根据此文件在容器内安装所有依赖。

在项目根目录执行vi requirements.txt命令，写入以下内容并保存。

# ================================================================================
# 指定国内 PyPI 镜像源，加速镜像构建时的依赖下载
# ================================================================================
--index-url https://repo.huaweicloud.com/repository/pypi/simple
--trusted-host repo.huaweicloud.com

# ================================================================================
# 核心依赖
# ================================================================================

# LangChain：LLM 应用开发工具链
langchain>=0.3.0
langchain-core>=0.3.0
langchain-openai>=0.2.0

# 环境变量加载
python-dotenv>=1.0.0

# AgentArts SDK：运行时封装与 HTTP 服务标准化
agentarts-sdk

制作Agent镜像。

创建.dockerignore文件，防止敏感文件被打包进镜像。

在项目根目录执行vi .dockerignore命令，写入以下内容并保存。

# 虚拟环境（镜像内会重新安装依赖）
venv/

# 环境变量文件（含 API Key，禁止打包进镜像）
.env

# Python 缓存
__pycache__/
*.pyc
*.pyo

# Git 相关
.git/
.gitignore

# 部署配置文件
.agentarts_config.yaml

在项目根目录执行vi Dockerfile命令，写入以下内容并保存。

# 必须使用 ARM64 架构的基础镜像
FROM python:3.10-slim

WORKDIR /app

# 优先复制依赖声明，利用 Docker 层缓存
COPY requirements.txt .

# 安装依赖（镜像源已在 requirements.txt 中指定）
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

EXPOSE 8080

ENTRYPOINT ["python", "app.py"]

执行以下命令构建镜像。
```
docker build -t my-first-agent:latest .
```

在本地运行容器，确认镜像可以正常启动。

docker run --rm -p 8080:8080 --env-file .env my-first-agent:latest

打开一个新的终端（保持原窗口运行），依次执行下面的命令，确认容器内的服务接口响应正常。

curl http://localhost:8080/ping

curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"message": "你好，请用一句话做个自我介绍。"}'

推送镜像到华为云SWR服务。

SWR是华为云的容器镜像服务。AgentArts控制台创建运行时时，会从SWR拉取镜像。本步骤将已构建的本地镜像推送到SWR。
1. 登录SWR控制台，切换到与AgentArts相同的区域（贵阳一）。
  图2 SWR控制台
2. 创建SWR组织。SWR组织相当于镜像的命名空间，同一账号下组织名全局唯一。
  输入自定义组织名称，本文示例使用my-org-demo，下方命令中涉及该组织名称时，请替换为您实际使用的值。
3. 获取SWR临时登录指令。
  在SWR“总览”页面，单击页面右上角“登录指令”，在弹出的对话框中复制“通用型登录指令”。
4. 在本地终端执行登录指令。
  将复制的完整登录指令粘贴到终端执行。
```
# 以下为示例格式，请粘贴您实际获取到的完整指令
sudo docker login -u cn-southwest-2@{xxx} -p {xxx} swr.cn-southwest-2.myhuaweicloud.com
```
  终端输出Login Succeeded即表示登录成功。
5. 给本地镜像打上SWR仓库标签。
```
# 请将my-org-demo替换为您实际的组织名称
sudo docker tag my-first-agent:latest swr.cn-southwest-2.myhuaweicloud.com/my-org-demo/my-first-agent:latest
```
6. 推送镜像到SWR。
```
# 请将my-org-demo替换为您实际的组织名称
sudo docker push swr.cn-southwest-2.myhuaweicloud.com/my-org-demo/my-first-agent:latest
```
  推送完成后，回到SWR控制台，在“我的镜像”页面可查看已上传的镜像。

通过AgentArts控制台创建运行时。

登录AgentArts 控制台，在左侧导航栏单击“智能体运行时”，单击右上角“托管智能体”，参考下表完成配置。

表1 参数说明
参数	配置说明
名称	Agent名称，例如my-first-agent。
描述	Agent的描述。
镜像	选择已推送到SWR的镜像。
权限与访问控制	委托：使用系统默认创建的DefaultAgentArtsRuntimeAgency委托。入网配置：使用系统默认网关。入栈协议：选择HTTP协议。入站身份认证：选择IAM认证。
可观测配置	开启。
生命周期配置	用于控制会话的自动终止策略，使用默认配置。
出网网络配置	选择公网访问。
存储配置	可选，用于挂载持久化存储。其中会话存储由平台统一托管；SFS Turbo和OBS仅在“私网访问”模式下支持配置。快速验证阶段无需配置。
启动命令	本示例已在Dockerfile中通过ENTRYPOINT ["python", "app.py"]指定了启动命令，此处无需填写，保持默认即可。
监听端口	监听端口默认为8080，与app.py中的app.run(host="0.0.0.0", port=8080) 保持一致，无需修改。
路由配置	选择前缀配置。这是一个容易忽略但非常关键的配置。AgentArts平台收到调用请求后，会先将路径中的 /runtimes/<运行时名称>/invocations/ 前缀剥离，再将剩余路径转发到镜像内部的实际接口。若选择“严格匹配”，请求将无法与镜像内的接口路径匹配，调用时会返回404。
文件上传下载	保持默认“未开启”。若您的 Agent 需要处理文件，开启后运行时将额外提供文件上传/下载的API接口，快速验证阶段无需开启。
环境变量	需要添加环境变量。逐一填入以下变量：变量名MODEL_API_KEY，值填写您MaaS中获取的模型API Key。变量名MODEL_NAME，值填写deepseek-v4-flash。变量名MODEL_URL，值填写https://api.modelarts-maas.com/openai/v1。
标签	如需通过标签对云资源进行统一管理，可在此添加，快速验证阶段可跳过。

单击“立即托管”，等待运行时就绪。

页面跳转至托管智能体列表，创建的运行时状态显示为“正常”，表示部署成功。

步骤四：调用Agent

部署完成后，您可以通过AgentArts运行时SDK提供的invoke命令直接调用您的智能体。

在命令行中执行 agentarts invoke 命令，SDK会自动使用您已配置的华为云IAM凭证（AK/SK）进行认证，无需额外参数。

agentarts invoke --agent my-first-agent '{"message": "你好，请用一句话做个自我介绍。"}'

--agent：指定运行时名称（即您在控制台或部署时设置的名称）。
紧随其后的JSON字符串为请求体（需要与您的Agent代码中定义的一致）。

您也可以通过标准 HTTP API 直接调用运行时。调用时需要根据创建运行时时选择的“入站身份认证”方式，在请求中携带对应的认证信息。

详细的调用步骤和示例代码请参考：

清理资源

验证完成后，如不再需要该运行时，请及时清理，避免产生不必要的费用。

登录AgentArts 控制台，在“智能体运行时”列表中，找到创建的运行时，进行删除。

下一步

成功部署第一个运行时后，可以进一步探索：

了解镜像制作的完整规范与高级配置 → 制作Agent镜像
了解控制台部署的完整配置项说明 → 通过控制台部署智能体运行时
了解SDK的完整命令参考 → AgentArts运行时SDK
为Agent集成平台底座组件，增强记忆、工具调用等能力 → 记忆库、网关、代码解释器

父主题： 运行时实践

上一篇：使用SDK一键部署智能体到运行时

下一篇：构建全能出行助手（集成模型/记忆/代码解释器/网关/高德mcp）