# 使用SDK一键部署智能体到运行时 #### 概述 智能体运行时是AgentArts提供的托管运行环境，负责承载智能体的运行、调度与运维。传统部署方式需要开发者手动完成镜像构建、镜像仓库推送、运行时创建等多个环节，流程繁琐且容易出错。AgentArts运行时SDK（agentarts-sdk）提供了一键部署能力，通过命令行工具自动完成镜像构建、推送SWR镜像仓库及部署到运行时的全流程操作，帮助开发者快速将本地智能体发布到云端运行环境。本文将以一个基于LangChain的基础对话智能体为例，介绍从代码编写、本地验证到SDK一键部署、调用的完整流程。 本文操作流程如[图1]所示，主要包含以下步骤： - [步骤一：准备Agent代码]：编写Agent核心逻辑并封装为符合平台规范的HTTP服务。 - [步骤二：本地验证]：启动服务并验证健康检查与对话接口。 - [步骤三：通过SDK一键部署]：使用运行时SDK自动完成镜像构建、推送与部署。 - [步骤四：调用Agent]：通过SDK或HTTP API调用已部署的智能体。 图1操作流程 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002719759906.png "点击放大") #### 前置条件与环境准备 在开始之前，请确认以下准备工作已完成： **账号与服务：** - 已开通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+；本文不逐条展开各发行版安装差异。 ![](https://support.huaweicloud.com/bestpractice-agentarts/public_sys-resources/caution_3.0-zh-cn.png) 需使用ARM64系统制作的Agent镜像，使用X86系统制作的镜像在调用智能体运行时会调用失败。 可以使用华为云ECS服务购买服务器，购买时需要选择鲲鹏架构（ARM64），系统选择Ubuntu。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002711693086.png "点击放大") - 安装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 ``` ![](https://support.huaweicloud.com/bestpractice-agentarts/public_sys-resources/note_3.0-zh-cn.png) 华为云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基础镜像地址"。 ![](https://support.huaweicloud.com/bestpractice-agentarts/public_sys-resources/note_3.0-zh-cn.png) - 执行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包。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002711533152.png "点击放大") - 执行以下命令配置华为云凭证，获取华为云凭证请参考[认证鉴权](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_047.html)。 ``` export HUAWEICLOUD_SDK_AK="your-access-key" export HUAWEICLOUD_SDK_SK="your-secret-key" ``` #### 步骤一：准备Agent代码 1. 创建项目目录。 在终端执行以下命令，创建项目目录并进入： ``` mkdir my-first-agent && cd my-first-agent ``` 2. 配置环境变量。 在项目根目录下创建.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 ``` 3. 执行如下命令安装langchain、langgraph、langchain-openai。 ``` pip install -U langchain langgraph langchain-openai ``` 4. **编写Agent核心逻辑** 。 1. 在项目根目录执行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() ``` 2. 验证Agent逻辑是否正常。 在终端执行以下命令，直接调用agent.py进行快速验证，确认模型调用链路没有问题： ``` python3 -c "from agent import agent; print(agent.chat('你好，请用一句话做个自我介绍。'))" ``` 如果模型调用正常，终端会输出模型的回复内容。 如果此步骤报错，请优先排查以下问题： - .env文件中的MODEL_API_KEY是否已替换为实际值。 - 当前网络环境是否可以访问api.modelarts-maas.com。 5. **封装为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) ``` ![](https://support.huaweicloud.com/bestpractice-agentarts/public_sys-resources/note_3.0-zh-cn.png) - AgentArtsRuntimeApp是AgentArts SDK提供的运行时封装类，负责处理平台与Agent之间的通信协议，以及健康检查接口的注册。 - @app.entrypoint装饰器将handler函数注册为平台的HTTP调用入口，平台每次调用Agent时都会触发此函数。 #### 步骤二：本地验证 在部署到云端之前，先在本地确认服务启动正常、接口响应符合预期。 1. 启动本地服务。 在正式推送镜像之前，先在本地模拟云端HTTP调用环境，验证Agent的接口封装是否正确、通信是否正常，可以大幅降低因接口问题导致云端部署后才发现错误的调试成本。 执行python app.py启动http server，执行以下命令调用验证Agent的HTTP接口是否已经被正确封装且能正常通信。 执行python app.py回显效果如下。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002748182109.png "点击放大") 2. 验证健康检查接口。 打开一个新的终端窗口（保持原窗口运行），执行以下命令，验证 /ping 健康检查接口是否正常： ``` curl http://localhost:8080/ping ``` 返回类似{"status": "Healthy"}内容说明服务已正常启动，平台的健康探查可以通过。 3. 验证对话接口。 在新终端中执行以下命令，验证/invocations对话接口是否正常： ``` curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"message": "你好，请用一句话做个自我介绍。"}' ``` 收到模型回复后，说明Agent逻辑和HTTP封装均工作正常。 两项验证均通过后，返回第一个终端，按Ctrl+C停止本地服务，继续进行后续的部署操作。 #### 步骤三：通过SDK一键部署 SDK方式会自动完成镜像构建、推送SWR、部署运行时的全部操作，适合快速验证场景。 1. 参考[前置条件与环境准备]安装SDK，并配置华为云凭证。 2. 准备依赖文件。 在项目根目录执行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 ``` 3. 初始化部署配置。 执行如下命令配置智能体。 ``` agentarts configure --entrypoint app:app ``` 执行后按照操作指引进行配置。 表1配置参数 | 参数 | 说明 | |:---|:---| | Agent name | 智能体名称。 以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线。 | | Region | 服务部署区域。 cn-southwest-2，仅支持此区域。 | | Dependency file | 依赖文件默认为requirements.txt。 | | SWR Organization | 镜像组织名称（建议自定义的镜像组织名，可以在SWR服务控制台贵阳一region创建）。 | | SWR Repository | 不填写（推荐）。 SWR Repository项直接回车留空，工具会自动生成仓库名称，部署agentarts launch时自动创建镜像仓库，避免仓库不存在报错。 如需手动指定，请填写SWR中**已存在**的镜像仓库名称；若尚未创建仓库，请留空，切勿填写不存在的仓库名。 | ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002718742310.png "点击放大") 4. 部署智能体。 ``` agentarts launch ``` 该命令会自动完成以下步骤： 1. 本地构建Docker镜像。 2. 将Docker镜像推送到华为云SWR镜像仓库。 3. 部署到AgentArts运行时托管环境。 #### 步骤四：调用Agent 部署完成后，您可以通过AgentArts运行时SDK提供的invoke命令直接调用您的智能体。 在命令行中执行 agentarts invoke 命令，SDK会自动使用您已配置的华为云IAM凭证（AK/SK）进行认证，无需额外参数。 ``` agentarts invoke --agent my-first-agent '{"message": "你好，请用一句话做个自我介绍。"}' ``` - --agent：指定运行时名称（即您在控制台或部署时设置的名称）。 - 紧随其后的JSON字符串为请求体（需要与您的Agent代码中定义的一致）。 您也可以通过标准 HTTP API 直接调用运行时。调用时需要根据创建运行时时选择的"入站身份认证"方式，在请求中携带对应的认证信息。 详细的调用步骤和示例代码请参考： - [使用API调用运行时接口（API Key 认证）](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0042.html) - [使用API调用运行时接口（IAM 认证）](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0063.html) #### 清理资源 验证完成后，如不再需要该运行时，请及时清理，避免产生不必要的费用。 登录[AgentArts 控制台](https://console.huaweicloud.com/agentarts)，在"智能体运行时"列表中，找到创建的运行时，进行删除。 #### 下一步 成功部署第一个运行时后，可以进一步探索： - 了解镜像制作的完整规范与高级配置 → [制作Agent镜像](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_079.html) - 了解控制台部署的完整配置项说明 → [通过控制台部署智能体运行时](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_031.html) - 了解SDK的完整命令参考 → [AgentArts运行时SDK](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_035.html) - 为Agent集成平台底座组件，增强记忆、工具调用等能力 → [记忆库](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_014.html)、[网关](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_021.html)、[代码解释器](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_007.html)