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

概述

智能体运行时是AgentArts提供的托管运行环境，负责承载智能体的运行、调度与运维。传统部署方式需要开发者手动完成镜像构建、镜像仓库推送、运行时创建等多个环节，流程繁琐且容易出错。AgentArts运行时SDK（agentarts-sdk）提供了一键部署能力，通过命令行工具自动完成镜像构建、推送SWR镜像仓库及部署到运行时的全流程操作，帮助开发者快速将本地智能体发布到云端运行环境。本文将以一个基于LangChain的基础对话智能体为例，介绍从代码编写、本地验证到SDK一键部署、调用的完整流程。

前置条件与环境准备

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

账号与服务：

• 已开通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代码

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)

   

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

步骤二：本地验证

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

1. 启动本地服务。

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

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

   执行python app.py回显效果如下。

   

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中已存在的镜像仓库名称；若尚未创建仓库，请留空，切勿填写不存在的仓库名。

   

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 认证）
• 使用API调用运行时接口（IAM 认证）

清理资源

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

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

下一步

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

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