基础示例：创建基础对话智能体-j9九游会登录

场景概述

传统开发agent的方式，是用户在本地使用langchain或langgraph等编写智能体脚本，但当需要将其推向生产环境时，往往会卡在繁琐的工程化步骤上：需要手动编写路由、处理请求、构建docker镜像，并自行寻找服务器部署。

agentarts提供了一条从代码到生产的完整链路。

本示例作为高代码开发的入门第一课，将暂时剥离复杂的外部工具，带您体验agentarts最基础但也最核心的“智能体运行时（runtime）托管能力”。示例中将编写一个纯粹的带有模型的对话智能体，并展示如何通过agentarts sdk将本地脚本转化为标准的http web服务，并托管到云端的agentarts中。

适用场景：

存量代码迁移：学习如何将已有的langchain/langgraph本地资产无缝接入agentarts平台。
熟悉开发链路：跑通“本地代码开发->sdk标准化封装->云端托管部署”的agentarts高码开发流程。
学习调用maas模型：学习如何在智能体中调用华为云maas服务提供的模型接口。

环境准备

操作系统：linux arm64，服务器可访问公网。

需使用arm64系统制作的agent镜像，使用x86系统制作的镜像在调用智能体运行时时会调用失败。

可以使用华为云ecs服务购买服务器，购买时需要选择鲲鹏架构（arm64）。
安装python：请确保python 3.10及以上版本已安装。
大多数linux发行版（如ubuntu）都预装了python，您可以先通过python3 --version检查。如未安装，可以使用如下命令安装：
```
sudo apt update
sudo apt install python3
```
安装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
```
- 执行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"

核心代码实现

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

在本地创建agent.py文件，编辑代码如下。

示例代码中创建了一个对话智能体，并对接华为云maas服务提供的模型。

import os
from typing import list, dict, any, typeddict, annotated
from dotenv import load_dotenv
from langgraph.graph import stategraph, end
from langgraph.graph.message import add_messages
from langchain_core.messages import basemessage, humanmessage, systemmessage
from langchain_openai import chatopenai
# 从 .env 文件加载环境变量
load_dotenv()
# ================================================================================
# 第一部分：状态定义与配置
# ================================================================================
class agentstate(typeddict):
    """
    agent 状态类型定义
    这是 langgraph 运行时的核心数据结构。
    - messages: 使用 add_messages 确保每次对话的新消息会被安全追加，而不是覆盖。
    """
    messages: annotated[list[basemessage], add_messages]
# ================================================================================
# 第二部分：agent 主类与工作流构建
# ================================================================================
class basicagent:
    """
    基础对话智能体类
    封装了 llm 的初始化、langgraph 工作流的构建与执行。
    """
    def __init__(self):
        # 强校验：没有 api key 直接报错阻断，避免产生难以排查的网络错误
        api_key = os.getenv("model_api_key")
        if not api_key:
            raise valueerror("[错误] 未找到 model_api_key！请在 .env 文件中进行配置。")
        # 实例化大模型客户端 (对接华为云maas服务提供的模型)
        self._llm = chatopenai(
            model=os.getenv("model_name", "deepseek-v3.2"),
            base_url=os.getenv("model_url", "https://api.modelarts-maas.com/openai/v1"),
            api_key=api_key,
            temperature=0.7,
        )
        self.graph = self._build_graph()
        self.system_prompt = "你是一个乐于助人的 ai 助手，请简明扼要地回答问题。"
    def _build_graph(self):
        """
        创建 agent 工作流图
        使用 langgraph 的 stategraph 构建极简工作流：
        1. 添加 agent 节点（调用 llm 生成回复）
        2. 设置起点为 agent 节点
        3. 设置终点（执行完 agent 节点后直接结束，无工具循环）
        returns:
            编译后的 langgraph 图
        """
        def model_node(state: agentstate) -> agentstate:
            response = self._llm.invoke(state["messages"])
            return {"messages": [response]}
        workflow = stategraph(agentstate)
        workflow.add_node("agent", model_node)
        workflow.set_entry_point("agent")
        workflow.add_edge("agent", end) 
        return workflow.compile()
    def run(self, user_input: str) -> str:
        """
        执行 agent 处理用户输入
        """
        messages = [
            systemmessage(content=self.system_prompt), 
            humanmessage(content=user_input)
        ]
        result = self.graph.invoke({"messages": messages})
        return result["messages"][-1].content

创建.env环境变量配置文件。
```
# 必填：您的华为云 maas api 密钥
model_api_key=xxxxxxxxxxxxxxxxxxxx
# 选填：如果您想使用其他模型，取消下方注释并修改
# model_name=deepseek-v3.2
# model_url=https://api.modelarts-maas.com/openai/v1
```
获取模型api key的方法请参考获取华为云maas服务模型api key。

agent.py文件的示例中，使用华为云maas服务提供的deepseek-v3.2模型，如果使用其他模型注意model_name的值，需填写为模型接口中model参数的值，可以参考如下方式获取。注意需要选择openai兼容接口。

图1 获取openai兼容接口的model值

创建main.py文件，用于本地运行智能体，并进行测试。

from agent import basicagent
def main():
    print("正在初始化 agent...")
    try:
        agent = basicagent()
    except exception as e:
        print(e)
        return
    print("=" * 50)
    response = agent.run("你好，请用一句话做个自我介绍。")
    print(f"agent 回复: \n{response}")
    print("=" * 50)
if __name__ == "__main__":
    main()

将agent.py、.env、main.py上传至服务器中。
如果您使用mobaxterm、xshell这类客户端软件，可以直接在软件界面上拖拽上传。
执行python main.py命令对智能体进行本地测试。
由于在main.py文件中已经设置好了问题“你好，请用一句话做个自我介绍。”，智能体本地运行时会调用大模型进行回复。有正常的回复即表示本地测试成功。

sdk封装，agentarts平台通过标准http协议与智能体通信，您需要用agentarts sdk将agent逻辑包一层，将其暴露为符合平台规范的/invocations接口，平台才能正确调度和管理您的智能体。

创建app.py文件，并上传至服务器中。该文件会将本地的agent逻辑封装为符合agentarts平台规范的web服务。

import os
from typing import dict, any
from agentarts.sdk import agentartsruntimeapp, requestcontext
from agent import basicagent
# 实例化平台运行时应用
app = agentartsruntimeapp()
try:
    my_agent = basicagent()
except exception as e:
    print(f"agent 初始化失败: {e}")
    my_agent = none
# ================================================================================
# agentarts 平台标准化接入 (核心)
# ================================================================================
@app.entrypoint
async def handler(payload: dict[str, any], context: requestcontext = none) -> dict[str, any]:
    """
    agentarts 平台标准 http 暴露入口
    args:
        payload: 请求载荷，包含用户输入 (如 payload.get("message"))
        context: 请求上下文，包含 session_id 等平台注入信息
    """
    if not my_agent:
        return {"response": "服务未正确初始化，请检查环境变量。", "status": "error"}
    query = payload.get("message", "")
    try:
        response = my_agent.run(query)
        return {"response": response, "status": "success"}
    except exception as e:
        return {"response": f"执行出错: {str(e)}", "status": "error"}
if __name__ == "__main__":
    # 平台托管时，必须读取 agent_run_port 环境变量以匹配容器端口契约
    run_port = int(os.getenv("agent_run_port", 8080))
    app.run(port=run_port)

接口验证，在正式推送镜像之前，先在本地模拟云端http调用环境，验证agent的接口封装是否正确、通信是否正常，可以大幅降低因接口问题导致云端部署后才发现错误的调试成本。
执行python app.py启动http server，执行以下命令调用验证agent的http接口是否已经被正确封装且能正常通信。

执行python app.py回显效果如下。
打开一个新的终端窗口（保持原窗口运行），使用curl命令进行测试。测试完成后，可以使用ctrl c停止运行的进程。
```
curl --location --request post 'http://localhost:8080/invocations' \
--header 'content-type: application/json' \
--data-raw '{"message": "你好，请用一句话做个自我介绍。"}'
```

部署智能体运行时。

按上述步骤验证完成后，接下来将智能体打包并托管到agentarts云端运行时。平台将自动完成镜像构建、推送与部署，您只需准备好依赖清单和配置文件即可。

首先准备依赖文件requirements.txt，内容如下：

# ================================================================================
# 指定国内 pypi 镜像源
# ================================================================================
--index-url https://repo.huaweicloud.com/repository/pypi/simple
--trusted-host repo.huaweicloud.com
# ================================================================================
# agentarts langgraph agent demo - 依赖清单
# ================================================================================
#
# 本项目基于 agentarts 平台，使用 langgraph 框架构建 ai agent
# 依赖分为两部分：基础框架依赖   平台 sdk 依赖
#
# 安装方式:
#   pip install -r requirements.txt
#
# ================================================================================
# ================================================================================
# 第一部分：langgraph & langchain 核心框架
# ================================================================================
# langgraph: ai agent 工作流编排框架
# - 状态图定义与执行
# - checkpoint 持久化机制
# - 条件边与节点路由
langgraph>=0.2.0
# langchain: llm 应用开发工具链
# - 消息类型定义 (humanmessage, aimessage, systemmessage)
# - 工具系统 (@tool 装饰器)
# - llm 客户端封装
langchain>=0.3.0
langchain-core>=0.3.0
langchain-community>=0.3.0
# ================================================================================
# 第二部分：llm provider 支持
# ================================================================================
# openai 兼容接口
openai>=1.0.0
langchain-openai>=0.1.0
# anthropic (claude) 支持
anthropic>=0.18.0
langchain-anthropic>=0.1.0
# ================================================================================
# 第三部分：http & 网络
# ================================================================================
requests>=2.31.0
httpx>=0.27.0
# ================================================================================
# 第四部分：工具与配置
# ================================================================================
# 环境变量管理
python-dotenv>=1.0.0
# 异步支持
aiofiles>=23.0.0
# json/yaml 支持
pyyaml>=6.0
# ================================================================================
# 第五部分：agentarts 平台 sdk（核心依赖） 
# ================================================================================
agentarts-sdk

执行如下命令配置智能体。
```
agentarts configure --entrypoint app:app
```
执行后按照操作指引进行配置。

配置智能体名称（以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线）、服务部署区域（使用cn-southwest-2，仅支持此区域）、requirements.txt依赖文件、swr organization镜像组织名称（如果使用自定义的镜像组织名，需要在swr服务控制台贵阳一region创建）
执行命令部署智能体。
```
agentarts launch
```
该命令会自动完成以下步骤：
1. 本地构建docker镜像。
2. 将docker镜像推送到华为云swr镜像仓库。
3. 部署到agentarts运行时托管环境。

调用云端agent进行会话。

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

点击放大

常见问题

执行agentarts launch命令时出现ak/sk认证报错
执行以下命令配置华为云凭证，获取华为云凭证请参考认证鉴权。
```
export huaweicloud_sdk_ak="your-access-key"
export huaweicloud_sdk_sk="your-secret-key"
```
执行agentarts launch命令出现运行时runtime名称错误
智能体的名称需要以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。

请重新执行agentarts configure --entrypoint app:app命令进行配置。
执行命令，出现swr.4040010,error_msg:repository does not exists,error: organization 'xxx' not found报错。
问题现象及原因

swr服务镜像组织不存在，出现该报错的原因通常是在执行agentarts configure --entrypoint app:app命令时，手动指定了一个swr镜像组织名称，但是未在swr控制台创建同名组织导致。

j9九游会登录的解决方案

登录（贵阳一区域），在“组织管理”中手动创建一个与agentarts configure --entrypoint app:app命令中同名的镜像组织。
执行agentarts launch命令，在执行requirements.txt步骤中出现read timed out ... files.pythonhosted.org报错。
问题现象及原因

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

j9九游会登录的解决方案
执行以下命令让其在安装依赖时使用华为云官方的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命令，出现failed to resolve reference "docker.io/library/python:3.10-slim"类型报错。
问题现象及原因

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

j9九游会登录的解决方案

配置docker国内镜像加速器

执行以下命令在系统配置目录下创建一个名为docker的文件夹。
```
sudo mkdir -p /etc/docker
```
执行以下命令（直接复制下面这段代码并回车执行），更换docker镜像源，从国内镜像站寻找python:3.10-slim。
```
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
```
docker配置完成后，再次执行agentarts launch命令进行agent部署。
执行agentarts launch命令，在执行requirements.txt步骤中出现read timed out ... files.pythonhosted.org报错。
问题现象及原因

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

j9九游会登录的解决方案

执行以下命令让其在安装依赖时使用华为云官方的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控制台“总览”页面右上角处可切换至新版）。