示例：部署第一个Agent到运行时

概述

将本地Agent代码投入生产，通常意味着一系列繁琐的工程化工作：手动编写路由、处理请求协议、构建Docker镜像，再自行寻找服务器完成部署。

AgentArts提供了一条从本地代码到云端服务的完整链路。本文将引导您将一个本地Agent代码托管到AgentArts运行时。

完成本文后，您将掌握：

• 如何将本地Agent代码封装为符合AgentArts平台规范的HTTP服务。
• 如何将封装好的服务制作成镜像并部署到AgentArts运行时。
• 如何调用已部署的Agent。

AgentArts提供两种部署方式，您可以根据实际情况选择：

两种方式部署完成后，调用方式完全一致。本文前两步（准备代码、本地验证）为两种方法共用，无需重复操作。

图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代码

1. 创建项目目录。

   在终端执行以下命令，创建项目目录并进入：

   mkdir my-first-agent && cd my-first-agent

2. 配置环境变量。

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

   执行touch .env命令创建.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. 执行touch agent.py命令，在项目根目录创建agent.py文件。
   2. 执行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()

   3. 验证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服务。

   执行touch app.py命令，在项目根目录创建app.py文件。

   执行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.invocation_handler装饰器将handle_invocation函数注册为/invocations接口的处理逻辑，平台每次调用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停止本地服务，继续进行后续的部署操作。

步骤三（方法A）：手动制作镜像 + 通过控制台部署

若您选择方法 B（SDK一键部署），请跳转至步骤三（方法B）：通过SDK一键部署。

1. 准备依赖文件。

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

   在项目根目录创建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

2. 制作Agent镜像。
   1. 执行touch .dockerignore命令，创建.dockerignore文件，防止敏感文件被打包进镜像。
      执行vi .dockerignore命令，在文件中写入以下内容：

      # 虚拟环境（镜像内会重新安装依赖）
      venv/
      
      # 环境变量文件（含 API Key，禁止打包进镜像）
      .env
      
      # Python 缓存
      __pycache__/
      *.pyc
      *.pyo
      
      # Git 相关
      .git/
      .gitignore
      
      # 部署配置文件
      .agentarts_config.yaml

   2. 执行touch Dockerfile命令，在项目根目录创建Dockerfile，执行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"]

   3. 执行以下命令构建镜像。

      docker build -t my-first-agent:latest .

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

      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": "你好，请用一句话做个自我介绍。"}'

3. 推送镜像到华为云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控制台，在“我的镜像”页面可查看已上传的镜像。

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

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

   表2 参数说明

   参数	配置说明
   名称	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。
   标签	如需通过标签对云资源进行统一管理，可在此添加，快速验证阶段可跳过。

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

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

步骤三（方法B）：通过SDK一键部署

SDK方式会自动完成镜像构建、推送SWR、部署运行时的全部操作，适合快速验证场景。

1. 参考前置条件与环境准备安装SDK，并配置华为云凭证。
2. 准备依赖文件。

   在项目根目录创建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

   执行后按照操作指引进行配置。

   表3 配置参数

   参数	说明
   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集成平台底座组件，增强记忆、工具调用等能力 → 记忆库、网关、代码解释器