华为云智果AgentArts智能体平台全流程对接与实战指南

在人工智能技术飞速迭代的今天，企业对定制化AI智能体的需求呈爆发式增长，但传统智能体开发面临技术门槛高、工程化周期长、运维成本高、安全合规难保障等痛点。华为云智果AgentArts作为企业级一站式智能体构建与运营平台，打破开发壁垒，支持业务人员与技术人员通过可视化低代码或高代码方式，快速搭建从简单对话助手到复杂多智能体协同的各类AI应用，已在金融、能源、制造、医疗等行业实现规模化落地。本文将从平台核心能力出发，详细讲解从账号开通、智能体创建、API对接、模型接入到运维监控的全流程对接方法，结合实战代码示例，帮助读者全面掌握AgentArts平台的使用技巧。

一、智果AgentArts平台核心能力与架构解析

1.1 平台核心定位

智果AgentArts是华为云推出的一站式企业级智能体开发与运营平台，核心定位是降低AI智能体开发门槛，加速企业AI能力落地。平台覆盖智能体全生命周期管理，包括需求设计、开发构建、测试部署、运营监控、安全运维五大环节，既支持零基础用户通过自然语言描述快速生成智能体，也支持专业开发者基于代码灵活定制复杂智能体逻辑。

1.2 核心能力亮点

• 多范式开发支持：提供低代码可视化拖拽、自然语言生成、高代码开发三种模式，适配不同技术背景用户，开发效率较传统模式提升一倍以上。
• 灵活编排能力：支持单智能体、工作流、多智能体协同三种开发范式，可实现复杂业务流程的自动化编排，满足简单对话到复杂任务处理的全场景需求。
• 丰富资产复用：内置五十余款预置应用模板、插件和提示词模板，涵盖合同审核、文章写作、政务摘要等场景，支持免费体验额度，开箱即用。
• 企业级安全可靠：采用零信任安全架构，支持API Key、IAM权限认证，提供全链路数据加密、访问控制与操作审计，保障智能体运行与数据安全。
• 全链路可观测：集成日志记录、指标监控、调用链追踪能力，支持调试模式与发布模式切换，便于问题排查与性能优化。
• 模型生态兼容：无缝对接华为云MaaS大模型服务，支持多款主流模型，兼容OpenAI协议，可灵活接入第三方模型服务。

1.3 平台基础架构

AgentArts平台采用分层架构设计，从上至下分为用户层、开发层、运行层、资源层：

• 用户层：提供Web控制台、API接口、SDK工具三种访问方式，适配控制台操作、业务系统集成、本地开发等不同场景。
• 开发层：包含智能体管理、组件库、知识库、提示词开发、模型接入五大模块，支撑智能体的设计与开发。
• 运行层：提供高性能智能体运行时托管环境，支持Docker镜像部署，负责智能体的调度、执行、弹性扩缩容。
• 资源层：依托华为云基础设施，包括计算、存储、网络、镜像仓库、大模型服务等，为平台提供底层资源支撑。

二、账号开通与服务接入前置准备

2.1 华为云账号注册与实名认证

使用AgentArts平台前，需先注册华为云账号并完成实名认证，这是开通所有华为云服务的基础。

1. 访问华为云官网，点击注册，输入手机号、验证码，设置登录密码，完成账号注册。
2. 登录华为云控制台，进入账号中心，选择实名认证，企业用户需上传营业执照、法人信息等材料，个人用户可通过身份证加人脸核验完成认证，认证通过后才能开通付费服务与资源。

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

2.2 开通智果AgentArts服务

华为云为AgentArts提供免费基础版额度，新用户可直接开通体验，步骤如下：

1. 登录华为云控制台，在顶部搜索框输入智果AgentArts，进入平台服务页面。
2. 点击立即开通，选择部署区域，当前主流可用区域为西南贵阳一区。
3. 选择服务版本，基础版免费，支持有限次数的智能体调用与开发，企业版提供更高调用额度、专属资源与技术支持，可根据业务需求选择。
4. 勾选服务协议，点击确认开通，等待一到两分钟，服务开通成功后即可进入AgentArts控制台。

2.3 权限配置与AK/SK获取

为保障安全，建议使用IAM子账号进行日常操作，避免主账号密钥泄露，同时获取访问密钥AK/SK用于本地SDK开发与API调用认证。

1. 在华为云控制台搜索IAM，进入身份与访问管理控制台，点击用户，创建用户，输入用户名，选择编程访问与控制台访问。
2. 为子账号授予AgentArts相关权限，推荐配置完全访问权限以及镜像仓库权限，满足高代码部署需求。
3. 创建用户成功后，下载CSV格式的AK/SK文件，妥善保存，该文件仅支持一次下载，丢失需重新创建用户。
4. 本地开发时，通过环境变量配置AK/SK，Linux与macOS系统执行命令如下：

export HUAWEICLOUD_SDK_AK="your-access-key"
export HUAWEICLOUD_SDK_SK="your-secret-key"

三、低代码快速创建智能体（零基础入门）

低代码模式是AgentArts的核心优势之一，无需编写代码，通过可视化操作或自然语言描述，即可快速创建智能体，适合业务人员快速搭建AI应用原型、落地轻量化业务场景。

3.1 自然语言辅助创建智能体

平台支持通过自然语言描述业务需求，自动生成智能体工作流，整个过程无需手动配置节点，大幅降低使用门槛，具体操作步骤如下：

1. 进入AgentArts控制台，在总览页面点击快速创建，选择AI辅助创建功能。
2. 在输入框中详细描述智能体的业务需求，例如创建电商舆情分级处置智能体，要求自动识别用户评论的情感倾向，负面评论自动生成工单并推送至客服，正面评论自动回复感谢语。
3. 点击生成工作流，平台会自动解析文字需求，生成可视化工作流画布，画布内包含情感识别、条件判断、消息推送、自动回复等全链路节点。
4. 在可视化画布中，可自由拖拽调整节点位置、修改节点配置参数，比如调整情感识别阈值、修改预设回复话术，完成细节优化。

3.2 模板化创建智能体（开箱即用）

针对通用办公、客服、文案处理等标准化场景，可直接使用平台预置模板，跳过从零搭建的流程，快速落地应用：

1. 在AgentArts控制台左侧导航栏点击资产广场，浏览平台内置的各类应用模板，包含合同审核助手、文章写作助手、知识问答助手等常用类型。
2. 选中匹配业务场景的模板，点击创建应用，按照命名规范输入智能体名称，名称要求以小写字母开头，可包含字母、数字、中划线，字符长度控制在二至四十八位之间。
3. 根据模板类型配置对应参数，以知识问答助手为例，需要上传知识库文档，平台支持PDF、Word、TXT等主流格式文件，同时可以自定义回答生成规则、引用规则。
4. 点击确认创建，平台自动完成智能体初始化，创建成功后直接进入编辑页面，用户可进一步调整提示词、对话流程、交互逻辑等配置内容。

3.3 智能体提交与部署

低代码创建完成的智能体仅处于编辑状态，必须提交版本并完成部署后，才能对外提供服务，支持网页访问和API调用，具体部署流程如下：

1. 在智能体编辑页面，确认所有配置无误后，点击提交版本，填写版本号与版本描述，方便后续版本管理与回滚。
2. 勾选部署至实例选项，入站身份认证选择API Key模式，同时勾选日志记录、指标监控、调用链追踪功能，便于后续问题排查与性能分析，其余配置保持系统默认即可。
3. 点击确定按钮，平台自动执行智能体部署流程，部署完成后智能体状态变更为已提交，此时可以获取对外调用的凭证与接口地址。

四、高代码开发智能体（专业定制）

对于存在复杂业务逻辑、需要集成自定义工具、对接第三方服务或者深度定制交互规则的场景，低代码模式无法满足需求，此时可以使用高代码模式开发智能体。平台原生支持LangChain、LangGraph等主流AI开发框架，开发者可以借助AgentArts SDK将本地编写的代码打包部署至平台运行时环境。

4.1 环境准备

高代码开发需要提前搭建本地开发环境，平台对运行架构有明确要求，推荐使用Linux ARM64系统，X86架构系统制作的镜像会出现部署失败问题，具体环境依赖与安装步骤如下：

1. 安装Python环境，要求版本为3.10及以上，Ubuntu系统安装命令如下：

# Ubuntu系统安装Python
sudo apt update
sudo apt install python3 python3-venv

2. 安装Docker环境，版本要求18.06及以上，用于代码打包构建镜像，同时配置国内镜像加速器解决拉取镜像超时问题：

# 安装Docker
sudo apt install docker.io
# 配置国内镜像加速器
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors":[
"https://docker.m.daocloud.net",
"https://dockerproxy.net",
"https://mirror.baidubce.com"
]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

3. 创建虚拟环境并安装AgentArts SDK以及相关AI框架依赖，使用华为云镜像源提升下载速度：

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate
# 安装AgentArts SDK
pip install agentarts-sdk -i https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com
# 安装LangChain与LangGraph框架
pip install -U langchain langgraph langchain-openai

4.2 核心代码开发（对话智能体示例）

下面以LangGraph框架为基础，开发一款基础对话智能体，对接华为云MaaS大模型，完整代码分为环境配置文件、智能体逻辑文件、平台服务入口文件以及依赖声明文件四部分。

1. 创建.env环境配置文件，统一管理模型接口地址、密钥等敏感信息：

# .env文件内容
MODEL_API_KEY=your-maas-api-key
MODEL_NAME=deepseek-v3.2
MODEL_URL=https://api.modelarts-maas.com/openai/v1

2. 创建agent.py文件，实现智能体核心对话逻辑与工作流编排：

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
# 加载环境变量
load_dotenv()
# 定义智能体状态结构
class AgentState(TypedDict):
    messages: Annotated[List[BaseMessage], add_messages]
# 基础对话智能体类
class BasicAgent:
    def __init__(self):
        api_key=os.getenv("MODEL_API_KEY")
        if not api_key:
            raise ValueError("未配置MODEL_API_KEY")
        # 初始化大模型客户端
        self._llm=ChatOpenAI(
            model=os.getenv("MODEL_NAME"),
            base_url=os.getenv("MODEL_URL"),
            api_key=api_key,
            temperature=0.7
        )
        self.graph=self._build_graph()
        self.system_prompt="你是乐于助人的AI助手，简明扼要回答问题"
    # 构建工作流图
    def _build_graph(self):
        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:
        messages=[
            SystemMessage(content=self.system_prompt),
            HumanMessage(content=user_input)
        ]
        result=self.graph.invoke({"messages": messages})
        return result["messages"][-1].content

3. 创建app.py文件，封装为AgentArts平台标准Web服务，作为对外调用入口：

import os
from typing import Dict, Any
from agentarts.sdk import AgentArtsRuntimeApp, RequestContext
from agent import BasicAgent
# 初始化平台应用实例
app=AgentArtsRuntimeApp()
my_agent=None
try:
    my_agent=BasicAgent()
except Exception as e:
    print(f"智能体初始化失败: {e}")
# 注册平台请求入口函数
@app.entrypoint
async def handler(payload: Dict[str, Any], context: RequestContext=None) -> Dict[str, Any]:
    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__":
    run_port=int(os.getenv("AGENT_RUN_PORT", 8080))
    app.run(port=run_port)

4. 创建requirements.txt文件，声明项目所有依赖包与版本，用于云端环境还原：

langgraph>=0.2.0
langchain>=0.3.0
langchain-openai>=0.1.0
requests>=2.31.0
python-dotenv>=1.0.0
agentarts-sdk

4.3 本地测试与云端部署

代码编写完成后，先在本地完成接口测试，验证逻辑是否正常，再执行云端部署操作，确保线上服务稳定运行。

1. 启动本地服务并使用curl命令测试接口可用性：

# 启动本地Web服务
python app.py
# 新开终端窗口测试接口
curl -X POST 'http://localhost:8080/invocations' \
-H 'Content-Type: application/json' \
-d '{"message": "你好，介绍一下智果AgentArts"}'

2. 本地测试通过后，执行平台部署命令，完成镜像构建、镜像推送、服务部署全流程：

# 配置智能体入口文件
agentarts configure --entrypoint app:app
# 一键部署至华为云AgentArts平台
agentarts launch
# 平台内调用测试
agentarts invoke '{"message": "你好，介绍一下智果AgentArts"}'

五、智能体API对接与调用（业务系统集成）

智能体部署完成后，最核心的使用场景就是和企业现有业务系统做集成，平台提供标准RESTful API接口，支持Python、cURL、Java等多种开发语言调用，整体流程分为获取认证凭证、组装请求参数、发送请求、解析响应四个步骤。

5.1 获取API认证凭证

平台对外接口均开启身份校验，必须使用API Key完成认证，具体获取与格式化步骤如下：

1. 登录AgentArts控制台，进入开发中心下的智能体管理页面，选中目标智能体，复制对应的智能体ID。
2. 切换至部署运行板块，打开智能体运行时列表，通过智能体ID检索目标实例，点击ID进入详情页面。
3. 在访问与权限控制区域找到URN地址，点击进入详情页，复制页面中的API Key。
4. 接口认证采用Bearer认证模式，在API Key前方拼接Bearer加空格，组合为完整的Authorization请求头内容。

5.2 API接口信息与参数说明

• 请求地址：https://{endpoint}/agent/{runtime_name}/invocations，endpoint与runtime_name均可在智能体详情页面查询。
• 请求方法：统一使用POST请求。
• 请求头：Authorization、Content-Type为必选参数，会话ID用于区分不同用户对话，调试模式参数可按需配置。

参数	是否必选	说明
Authorization	是	Bearer 拼接API Key，用于身份认证
Content-Type	是	固定为application/json
x-hw-agentarts-session-id	是	自定义会话ID，字符串格式，长度不超过64字符
X-Invoke-Mode	否	可选debug调试模式、published发布模式，默认发布模式

• 请求体：标准JSON格式，核心字段为query，用于传递用户提问内容。

{"query": "用户提问内容"}

5.3 多语言调用示例

5.3.1 Python调用示例

import requests
import json
# 接口请求地址
url="https://cn-southwest-2.myhuaweicloud.com/agent/your-runtime-name/invocations"
# 组装请求头
headers={
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json",
    "x-hw-agentarts-session-id": "session-123456"
}
# 组装请求体
payload=json.dumps({"query": "什么是智果AgentArts？"})
# 发送POST请求
response=requests.post(url, headers=headers, data=payload)
# 打印接口返回结果
print("响应结果：", response.json())

5.3.2 cURL调用示例（Linux/macOS）

curl -X POST "https://cn-southwest-2.myhuaweicloud.com/agent/your-runtime-name/invocations" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-H "x-hw-agentarts-session-id: session-123456" \
-d '{"query": "什么是智果AgentArts？"}'

六、模型接入与集成（自定义模型/第三方模型）

AgentArts不局限于平台内置模型，支持三类模型接入方式，分别是华为云原生MaaS大模型、兼容OpenAI协议的第三方模型、企业本地部署的自定义模型，能够满足不同业务对模型能力、数据安全、部署方式的多样化需求。

6.1 接入华为云MaaS模型

1. 登录华为云控制台，搜索ModelArts MaaS进入大模型服务页面，开通对应模型服务，完成实名认证与额度充值后获取模型专属API Key。
2. 回到AgentArts控制台，进入模型管理模块，选择接入模型，类型勾选华为云MaaS。
3. 依次填写模型名称、API Key、模型接口地址，选择模型分类，包含对话、内容生成、向量嵌入等类型。
4. 点击测试连接，系统校验连通性，连接成功后保存配置，该模型即可在所有智能体项目中被调用。

6.2 接入第三方OpenAI协议模型

市面上多数主流大模型均兼容OpenAI调用协议，接入方式统一，以GLM模型为例，操作步骤如下：

1. 在对应模型平台注册账号，完成认证并获取API Key与标准接口地址。
2. 在AgentArts模型管理页面，选择自定义OpenAI模型分类。
3. 填写供应商名称、模型名称、接口地址、API Key等核心参数。
4. 执行连接测试，测试通过后保存配置，完成第三方模型接入。

七、安全配置与运维监控

7.1 安全配置最佳实践

• API Key安全管理：定期轮换API Key，禁止将密钥硬编码在业务代码中，统一使用环境变量或华为云密钥管理服务存储敏感密钥。
• 权限最小化配置：日常操作全部使用IAM子账号，根据岗位职能分配对应权限，杜绝主账号直接对外使用。
• 访问来源控制：配置IP白名单，仅允许企业内网、指定公网IP调用接口，拦截陌生访问请求，降低被攻击风险。
• 数据安全处理：业务中的手机号、身份证、客户信息等敏感数据必须做脱敏处理，知识库文件开启加密存储，防止核心数据泄露。

7.2 运维监控与问题排查

1. 日志查看：进入智能体详情页面，打开日志板块，可按时间、关键词筛选调用日志、代码执行日志，快速定位报错内容。
2. 指标监控：平台实时统计接口调用次数、平均响应时间、错误率、服务器资源使用率，可自定义告警阈值，出现异常后及时提醒运维人员。
3. 调用链追踪：开启调用链功能后，可查看一次请求的全链路执行节点、各节点耗时，精准定位性能瓶颈与异常节点。

八、常见问题与解决方案

1. 高代码部署时AK/SK认证失败：检查本地环境变量是否正确填写，核对IAM子账号是否已分配镜像仓库与AgentArts权限，重新配置密钥后重试。
2. API调用返回401认证错误：检查Authorization格式，确认Bearer后方存在空格，核对API Key是否过期、状态是否正常，重新获取密钥后测试。
3. 智能体部署超时：排查Docker镜像构建日志，检查网络连通性，更换国内镜像源，清理本地无用镜像文件后重新部署。
4. 模型调用失败：确认模型API Key有效、服务额度充足、接口地址与模型名称匹配，在模型管理页面重新测试连接。

九、总结

华为云智果AgentArts智能体平台采用低代码加高代码的双开发模式，兼顾易用性与灵活性，从账号开通、智能体搭建、接口集成到线上运维，形成了完整的AI智能体落地链路。对于传统业务人员，可以借助模板和自然语言快速搭建应用原型；对于专业开发团队，可以基于代码深度定制复杂智能体逻辑。结合华为云成熟的大模型生态、底层云资源与企业级安全能力，该平台能够有效降低AI落地成本，帮助各行各业快速完成智能化转型。

问答环节

1. 智果AgentArts平台是否提供免费使用额度？
答：平台基础版支持免费使用，包含有限的智能体开发次数与接口调用额度，新用户可直接开通体验。

2. AgentArts目前支持哪些部署区域？
答：当前官方主推西南贵阳一区，后续会逐步开放更多可用区域。

3. 高代码开发部署是否对服务器架构有要求？
答：有要求，高代码打包镜像仅支持Linux ARM64架构，X86架构系统制作的镜像会部署失败。

4. 智能体接口调用采用哪种认证方式？
答：主流使用API Key搭配Bearer认证，同时也支持华为云IAM权限认证两种方式。

5. AgentArts能否接入外部第三方大模型？
答：可以，平台支持接入所有兼容OpenAI调用协议的第三方大模型，也支持企业自研自定义模型。

6. 智能体调用异常时该如何排查问题？
答：优先查看平台调用日志、监控指标与调用链信息，依次核对认证密钥、账号权限、模型连通性、网络状态，逐步定位故障原因。