通过运行时SDK部署

本文以预置Agent模板为例，介绍如何在本地使用AgentArts SDK的Toolkit工具将本地代码部署到云上AgentArts智能体运行时。

背景介绍

AgentArts SDK包含一套命令行工具，用于简化Agent应用的全生命周期管理，包括初始化、配置、构建、部署和运维。当前Toolkit已预置以下Agent示例模板供您选择，您也可以使用自研代码：

basic：基础智能体模板，具有最小化的设置。适用于从一个非常简单的起点开始，然后根据需求逐步添加功能的开发者。它提供一个基本的框架，可以帮助开发者快速启动项目，而不需要从零开始构建所有内容。
langgraph：基于LangGraph的智能体，适用于需要处理复杂状态和逻辑的应用场景。
langchain：基于LangChain的智能体，适合需要将多个语言处理工具和服务集成到一个应用中的场景。
google-adk：Google ADK智能体模板，适用于利用Google提供的技术和工具来开发智能体应用的开发者。

前提条件

操作系统：推荐使用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镜像格式推送到SWR时会报错，可以通过设置以下环境变量来关闭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"

通过SDK部署智能体运行时

创建agent。

执行以下命令初始化一个LangGraph项目，支持基本的问答能力。

agentarts init -n my-agent -t langgraph

my_agent/
├── agent.py              # Agent implementation
├── requirements.txt      # Python dependencies
├── Dockerfile            
└── .agentarts_config.yaml # Project configuration

（可选）配置agent。使用交互式配置向导设置部署参数。
```
agentarts config
```
配置向导会引导完成以下配置，按Enter键表示使用默认配置：
1. Agent名称（显示已有Agent列表）
2. 入口函数（格式：module:function）
3. 华为云区域（默认cn-southwest-2）
4. 依赖文件（自动检测requirements.txt）
5. SWR组织名称
6. SWR仓库名称

修改.agentarts_config.yaml中环境变量配置。

environment_variables:
  - key: OPENAI_API_KEY
    value: 您申请的大模型apikey
  - key: OPENAI_MODEL_NAME
    value: 您申请的大模型名称
  - key: OPENAI_BASE_URL
    value: 您申请的大模型访问地址

部署agent。

执行以下命令，将应用在本地构建镜像并部署至AgentArts智能体运行时。
```
agentarts launch
```
首次部署耗时较长，大约需要3-5min，请耐心等待。

当回显部署完成时，则表示创建成功。

图1 部署完成

部署完成后登录AgentArts控制台，查看已部署的智能体运行时及详细信息。

图2 查看已部署的智能体运行时
查看智能体启动状态以及调试agent。

执行以下命令，对agent进行调试。
```
agentarts invoke '{"message":"你好"}'
```
调用成功结果如下：

常见问题

执行pip install agentarts-sdk命令，出现HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out报错。
请重新执行pip install agentarts-sdk命令进行安装。
执行agentarts launch命令，出现failed to resolve reference "docker.io/library/python:3.10-slim"类型报错。
问题现象及原因

尝试连接Docker官方镜像仓库（docker.io）下载python:3.10-slim基础环境时，网络连接超时（网络连接被阻断或者限速）。

解决方案一：配置Docker国内镜像加速器（推荐）

执行以下命令在系统配置目录下创建一个名为docker的文件夹。
```
sudo mkdir -p /etc/docker
```
执行以下命令（直接复制下面这段代码并回车执行），更换Docker镜像源，从国内镜像站寻找python:3.10-slim。
```
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors":[
    "替换为国内可用的Docker镜像源地址"
  ]
}
EOF
```
依次执行下面两条命令，重启Docker服务：
```
sudo systemctl daemon-reload
sudo systemctl restart docker
```
Docker配置完成后，再次执行agentarts launch命令进行Agent部署。

解决方案二：直接修改Dockerfile基础镜像地址
1. 在项目根目录下找到Dockerfile（由agentarts launch自动生成或已存在）。
2. 编辑Dockerfile，将FROM python:3.10-slim替换为国内镜像地址，例如：
```
sed -i 's|FROM python:3.10-slim|FROM docker.m.daocloud.io/library/python:3.10-slim|g' Dockerfile
```
  或手动修改为：
```
FROM docker.m.daocloud.io/library/python:3.10-slim
```
  保存后重新执行agentarts launch命令。
执行agentarts launch命令，在执行requirements.txt步骤中出现Read timed out ... files.pythonhosted.org报错。
问题现象及原因

Docker镜像在构建过程中，尝试从官方PyPI服务器下载在requirements.txt里写的那些Python包，由于网络环境原因造成超时。

解决方案

执行以下命令让其在安装依赖时使用华为云官方的Python镜像加速器。
```
sed -i 's|pip install --no-cache-dir -r requirements.txt|pip install --no-cache-dir -r requirements.txt -i https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com|g' Dockerfile
```
配置完成后，再次执行agentarts launch命令进行Agent部署。
执行agentarts launch命令，出现Organization 'agentarts-org1' already exists、Failed to create/get organization 'agentarts-org1'报错。
SWR服务镜像名称已被占用，请重新更换名称，即更换.agentarts_config.yaml文件中swr_config配置中organization参数的值、artifact_source参数中的值（在yaml文件中，该值共有2处需要替换）。

可依次执行以下命令进行替换，也可以直接手动执行nano .agentarts_config.yaml命令进入到yaml文件中进行修改。
```
# 将.agentarts_config.yaml文件中原有的 agentarts-org1 组织名替换为一个不容易重名的名字，比如 org_agent_6731
sed -i 's/organization: agentarts-org1/organization: org_agent_6731/g' .agentarts_config.yaml

# 修正 artifact_source 里的 URL 中的组织名，这里以 org_agent_6731 为例
sed -i 's|url: swr.cn-southwest-2.myhuaweicloud.com/agentarts-org1/agent_my-agent:latest|url: swr.cn-southwest-2.myhuaweicloud.com/org_agent_6731/agent_my-agent:latest|g' .agentarts_config.yaml
```
执行agentarts launch命令，出现SVCSCTG.SWR.4030017、403 Insufficient permissions报错。
如果使用IAM账户执行agentarts launch命令产生该报错，表示IAM用户没有SWR服务中创建组织或管理资源的权限。请联系主账号授予SWRFullAccessPolicy权限（在IAM新版控制台中授权，IAM控制台“总览”页面右上角处可切换至新版）。
执行agentarts launch命令弹窗要求修改配置repository及swr。
需手动编辑 .agentarts_config.yaml文件中的配置。
1. 使用编辑器打开 .agentarts_config.yaml 文件。
2. 修改 swr_config 部分，在 .agentarts_config.yaml 文件中，找到 swr_config 部分。修改以下字段：
  - organization: 组织名称
  - repository: 仓库名称
  - organization_auto_create: 是否自动创建组织
  - repository_auto_create: 是否自动创建仓库
执行agentarts launch命令，出现ReadTimeoutError: Read timed out报错。
需修改Dockerfile中的pip install命令，添加国内镜像源和超时时间。
1. 执行以下命令，打开Dockerfile：
```
vi Dockerfile
```
2. 在文件中找到如下行：
```
RUN pip install --no-cache-dir -r requirements.txt
```
3. 将该行替换为以下内容（添加镜像源和超时时间）：
```
RUN pip install --no-cache-dir -i https://repo.huaweicloud.com/repository/pypi/simple --timeout 100 -r requirements.txt
```
4. 按Esc键进入命令模式，输入:wq并按Enter键保存退出。

通过运行时SDK部署

背景介绍

前提条件

通过SDK部署智能体运行时

常见问题

更多操作

相关文档

您对此文档页面的整体评价？