文档首页/ 智果（AgentArts）智能体平台/ Managed Agents（Beta）/ 最佳实践/ 公网模型与私网环境的智能体调测指南
更新时间：2026-11-09 GMT+08:00
查看PDF
分享

公网模型与私网环境的智能体调测指南

概述

Managed Agents支持在私网环境中运行智能体。当智能体关联的模型位于公网（如华为云MaaS），而运行环境位于私网时，智能体便处于“公网模型+私网环境”的跨网场景，此时因公网与私网之间网络不互通，会导致模型调用失败。需先打通公网与私网之间的网络，智能体才能正常运行。

前提条件

  • 已开通AgentArts服务，并在“管理中心 > 授权管理”完成依赖云服务授权。
  • 智能体需要关联模型，请在创建智能体之前完成添加模型。

步骤一：添加模型

这里以添加华为云MaaS的GLM-5.3模型为例，采用标准OpenAI协议，区域选择“西南-贵阳一”。

如果已有可以使用的模型，则跳过此步骤。

获取MaaS的GLM-5.3模型信息

  1. 进入“西南-贵阳一”MaaS页面，选择“模型推理 > 在线推理”，找到GLM-5.3模型，查看模型类型。
    图1 获取模型信息1
  2. 单击“API调用 > 主推版本”，查看模型信息。
    图2 获取模型信息2
  3. 获取模型API Key。
    在MaaS左侧导航，选择“模型与统计 > API Key管理”，单击“创建API Key”，如图3所示，复制并保存API Key信息。
    图3 创建API Key

添加模型供应商

  1. 登录AgentArts控制台，在左侧导航选择“托管与运行 > 模型”。
  2. 单击“添加模型供应商”，配置模型供应商基本信息，如图4所示。
    图4 配置模型供应商基本信息
    表1 参数说明

    参数

    示例

    说明

    名称

    maas

    模型供应商的名称，名称唯一。

    命名规则：以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-40个字符。系统会默认生成名称，可根据需求自定义修改。

    描述（可选）

    接入华为云MaaS的GLM-5.3模型

    用于说明该模型供应商的内容与用途。

    Base_url

    https://api.modelarts-maas.com/openai/v1

    模型API地址，以https://开头的完整URL，长度为1-2048个字符。
  3. 配置出站身份认证，如图5所示。

    此处的出站身份认证用于配置模型的认证方式。华为云MaaS的GLM-5.3模型支持API Key认证，通过在HTTP请求中携带API Key实现身份识别。

    图5 出站身份认证

    创建出站身份认证方式如下：

    在“添加模型供应商”页面的“权限与访问控制”区域，单击“创建出站身份”，按页面提示填写身份名称、选择API Key类型、填写在MaaS界面获取的API Key。
    图6 创建出站身份
    表2 出站身份认证参数说明

    参数

    示例

    说明

    出站身份认证

    API Key认证

    用于配置模型的认证方式。

    位置

    标头

    API Key的传递位置。

    调用MaaS的模型服务时，MaaS要求将API Key放在HTTP请求头中传递，因此选择“标头”。

    参数名称 (可选)

    Authorization

    在请求中传递API的密钥时使用的具体名称。

    调用MaaS OpenAI兼容接口时，鉴权请求头的名称必须是Authorization。

    前缀 (可选)

    Bearer

    在请求头中传递API Key时，API密钥值之前的前缀部分。

    调用MaaS OpenAI兼容接口时，MaaS使用“Bearer $MaaS_API_Key”形式的鉴权，API Key不能直接填写，须添加Bearer前缀。
  4. 配置出网网络，如图7所示。

    此处的出站身份认证用于配置模型的认证方式。华为云MaaS的GLM-5.3模型支持API Key认证，通过在HTTP请求中携带API Key实现身份识别。

    图7 出网网络配置
    表3 出网网络配置参数说明

    参数

    示例

    说明

    出网网络配置

    公网访问

    用于指定访问MaaS模型时使用的网络路径。

    • 公网访问：能够连接到外部的互联网，访问外部的资源和服务。如无特殊网络要求，建议选择“公网访问”。
    • 私网访问：连接内部的私有网络，访问内部的资源和服务。如需通过VPC内网访问模型，选择“私网访问”。
  5. 高级配置。

    保持默认。

    模型供应商信息配置完成后，即可添加模型服务。

添加模型服务

  1. 单击“添加模型服务”，配置模型信息，如图8所示，配置完成后，单击“确定”。
    图8 配置模型信息
    表4 参数说明

    参数

    示例

    说明

    模型服务名称

    maas

    模型服务名称。

    命名规则：支持中英文、数字及符号 _./-，须以中英文或数字开头结尾，长度2-64个字符。

    系统会默认生成名称，可根据需求自定义修改。

    描述

    接入华为云MaaS模型即服务的GLM-5.3模型

    用于说明该模型服务的内容与用途。长度不大于1000个字符。

    模型名称

    glm-5.3

    模型名称，接口调用请求体中的model字段的取值。

    由英文、数字及符号（连字符、点、下划线、星号、问号和@）组成，支持 * 的前缀通配以及后缀通配，长度为1-256个字符。

    支持精确匹配与通配匹配，精确匹配优先。

    精确匹配：与请求model字段完全一致时匹配。例如，glm-5.3。

    前缀通配：*结尾，匹配所有以glm-开头的模型。例如，glm-*。

    后缀通配：*开头，匹配所有以-turbo结尾的模型。例如，*-turbo。

    同时满足精确和通配匹配时，优先精确匹配。

    通配匹配命中后，网关将客户端请求中的原始model值透传给后端，而非通配符本身。例如配置glm-*，请求glm-5.3-turbo时，后端收到的model为glm-5.3-turbo。

    API接口协议

    标准OpenAI协议

    选择模型API接口协议，支持以下三种：

    • 标准OpenAI协议：兼容OpenAI API标准的协议。适用于大多数主流模型提供商，推荐优先使用。
    • Anthropic协议：兼容Anthropic API标准的协议。
    • 华为云MaaS标准API V1：用于对接MaaS V1版本接口，推荐使用适用范围更广的“标准OpenAI协议”。V1版本协议仅支持对接Qwen3-32B、Qwen3-30B-A3B模型，详见MaaS标准API V1。

    模型类型

    文本对话/图像理解

    模型支持的能力类别，须按模型实际能力选择。

    • 文本对话/图像理解
    • 文本向量化
    • 多模态对话
    • 文本排序
    • 实时语音对话
  2. 单击“创建”。

    模型供应商显示在模型列表中，添加的模型服务显示在模型供应商详情页面的模型服务列表中，即可被选择使用。

步骤二：创建环境

这里以创建私网环境为例。

在Managed Agents页面，选择“环境”页签，单击“创建环境”，配置环境参数。创建后，环境显示在环境列表中。

图9 创建环境
表5 参数说明

参数

示例

说明

基本信息

名称

environment-vpc

环境的展示名称，供用户在列表中快速识别与检索该环境。系统默认生成以environment开头的名称，可以自定义。创建后，不可修改。

由2~40个字符组成，包含小写字母、数字和-，且必须以小写字母开头、以小写字母或数字结尾。

描述（可选）

私网环境

环境的描述信息，帮助用户快速理解该环境。

由0~4096个字符组成。

网络配置

出网网络配置

私网访问

vpc-default(192.168.0.0/16)

subnet-default(192.168.0.0/24)

default(254804d8-fd29-4505-bbe9-a64f6f9278d1)

用于指定沙箱向外发起网络请求时使用的网络路径。

出网网络配置在环境创建后，不可修改。
  • 公网访问：通过互联网出口访问公网上的服务。默认公网访问。
  • 私网访问：打通企业私有VPC内网，只能访问内网资源，流量不经过互联网。配置完成后，建议在智能体中发起测试请求，验证VPC内网连通性。
    说明：

    VPC免费，但NAT网关、EIP会产生按需费用，具体请参考NAT网关按需计费和弹性公网IP按需计费。

    当选择“私网访问”时，需配置如下参数：

    • 选择已配置的VPC，默认显示第一个。如未配置，请单击“新建VPC”，具体请参考创建虚拟私有云和子网。
    • 选择已配置的子网，默认显示第一个。如未配置，请单击“新建子网”，具体请参考创建虚拟私有云和子网。
    • 选择已配置的安全组，默认显示第一个。如未配置，请单击“新建安全组”，具体请参考创建安全组。

存储配置

会话存储

勾选

/data/managedagents

会话级别的持久化存储，用于保存会话上下文、中间结果、用户偏好等。存储资源由后台服务统一托管，每个会话拥有独立存储空间。配置后不可取消，仅支持1个。

挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含“..”，最大长度为4000字符。

SFS Turbo

-

当“出网网络配置”选择“私网访问”时，支持此参数。

高性能分布式共享文件存储服务，支持多云主机、容器同时挂载访问，提供低时延、弹性扩容的持久化文件存储能力。最多添加5个SFS Turbo类型的存储，且SFS Turbo仅在私网访问下支持配置。

单击“添加”，详细参数配置请参考表5。

OBS

-

当“出网网络配置”选择“私网访问”时，支持此参数。

用于保存会话过程中产生的文件等，存储资源为用户的OBS桶。最多只能选择5个不同的OBS桶，最多添加10个OBS类型的存储，且OBS仅在私网访问下支持配置。

单击“添加”，详细参数配置请参考表5。

步骤三：创建智能体

在Managed Agents页面，选择“智能体 > 创建智能体 > 自定义创建”，配置智能体参数。创建后，智能体显示在智能体列表中，并生成一个版本。

图10 创建智能体
图11 配置智能体
表6 参数说明

参数

示例

说明

基本信息

名称

agent-vpc

智能体的展示名称，供用户在列表中快速识别与检索该智能体。系统默认生成以agent开头的名称，可以自定义。创建后，不可修改。

由2~40个字符组成，包含小写字母、数字和中划线，且必须以小写字母开头、以小写字母或数字结尾。

描述（可选）

公网模型+私网环境

智能体的描述信息，帮助用户快速理解该智能体的作用。

由0~4096个字符组成。

模型及提示词

模型

maas/glm-5.3

智能体使用的模型。默认展示第一个模型。如未配置，请单击“模型管理”，具体请参考模型。不同模型的推理费用不同，请根据业务需求选择合适的模型。

提示词（可选）

-

定义智能体的角色、行为规则和约束边界。由0~32,768个字符组成。如何写好提示词，请参考提示词。

环境

环境

environment-vpc

智能体的运行环境。环境是可复用的沙箱/容器模板，定义智能体会话实际执行任务的底层运行载体，回答“智能体在哪里执行任务”。创建环境请参考配置智能体运行环境。

默认展示第一个环境。

工具与Skill

内置工具（可选）

-

Managed Agents提供了bash、read_file、write_file、edit_file、glob、list_files、grep内置工具，当用户在会话中执行bash命令或文件操作时，为智能体选择内置工具。详细介绍请参考内置工具。

Skill（可选）

-

最多支持选择50个Skill。

需要特定领域能力（如翻译、摘要）时，进行配置。详细介绍请参考Skill。

权限与访问控制

委托

DefaultAgentArtsRuntimeAgency
注意：

委托权限决定了智能体可访问的外部资源范围。请遵循最小权限原则，仅授予必要的权限，避免因权限过大导致数据泄露或越权操作。

授予的代理权限或代理功能，允许代表智能体与外部系统进行通信和交互。

为了保证智能体运行时正常运行，所选委托需要具备相关权限。委托创建完成后可对委托进行授权，操作详情请参考创建委托并授权。

系统默认值为DefaultAgentArtsRuntimeAgency。

说明：

使用OBS桶挂载功能时，需为运行时委托配置相应的OBS权限。根据文件系统的访问模式，所需的最小权限如下：

  • 文件系统只读操作：obs:bucket:headBucket、obs:bucket:listBucket、obs:object:getObject。
  • 文件系统读写操作：obs:bucket:headBucket、obs:bucket:listBucket、obs:object:getObject、obs:object:putObject、obs:object:deleteObject。

以上为最小权限要求。如需配置其他权限，请提交工单咨询OBS权限相关事宜。

入网配置

defaultgw
警告：

入网配置创建后不可修改。请根据您的网络环境谨慎选择公网访问或VPC内网访问，配置后如需更改需重新创建智能体。

通过互联网或者VPC内网访问智能体运行时。更多信息请参考网络配置。

系统默认值为defaultgw。

公网访问适合需要从外部互联网调用的场景。VPC内网访问适合与VPC内其他云服务内网互通的场景，安全性更高。

入站身份认证

API Key认证

APIKey-1106369606

配置入站身份认证方式。在智能体接收到请求时，对请求进行身份验证和授权，确保请求来自可信的来源，并且具有访问特定资源的权限。

创建后，不可修改。

支持以下认证方式：

  • IAM认证：使用登录管理控制台时使用的IAM用户名进行认证。默认为IAM认证。
  • OAuth 2.0认证：将OAuth 2.0配置为入站身份认证。选择“OAuth 2.0认证”后，相关参数配置请参考表5。
  • API Key认证：通过接口的访问密钥进行身份验证和授权。系统会自动生成API Key的名称，可根据需求自定义修改。

    身份认证凭证在凭据管理服务（DEW）中托管，凭据托管按需计费，费用说明请参考DEW计费说明。

选择认证方式可以参考表6。

可观测配置

日志记录

开启
  • 未开启，运行时过程产生的日志无法上报至云日志服务（LTS）。
  • 开启后，运行时过程产生的日志会上报至云日志服务（LTS），日志管理费用按需收取，有关计费相关内容请参考LTS计费说明。默认已开启。

开启后，调用智能体后，可在智能体详情“日志”页签中查看每次调用的输入输出、执行时长、工具调用记录等信息，用于调试智能体行为、排查异常和性能优化。

高级配置

空闲会话超时

15

智能体在一段时间内无用户交互时，自动结束当前会话并释放运行资源，避免持续计费和资源占用。超时后会话终止，用户再次调用时需重新发起。

取值范围1~10,080分钟，默认值15分钟。

时间越长，会话保持在线越久，资源占用和费用越高，但中断后可无缝续接；时间越短，费用更低，但短暂离开后再回来需重新发起会话。建议按实际使用频率权衡设置。不确定时，建议先用默认15分钟，后续按实际体验调整。

最大存活时间

24

会话从创建起可存续的最大时长，无论期间是否有交互，到时间后强制结束会话。用于防止会话长期占用资源，控制成本和生命周期风险。

取值范围1~168小时，默认值24小时。

时间太短，长任务未执行完成即被强制中断，导致结果丢失需重新执行；时间太长，资源占用和费用持续累积。建议按任务最长耗时设置，留有余量即可。

步骤四：打通“公网模型+私网环境”的跨网场景

这里以通过NAT网关为例，介绍如何打通网络。

  1. 进入虚拟私有云VPC控制台。
    图12 进入虚拟私有云VPC
  2. 在左侧导航，选择“网络连接 > NAT网关 > 公网NAT网关”，单击“购买公网NAT网关”。
    图13 购买公网NAT网关
  3. 配置NAT网关信息，单击“立即购买”，单击“提交”。

    虚拟私有云、子网与环境中的VPC、子网一致。

    NAT网关按需计费，具体收费规则请参考NAT网关按需计费。

    图14 配置NAT网关
  4. 在弹窗中，单击“添加规则”，添加SNAT规则。
    图15 添加规则
  5. 在“SNAT规则”页面，单击“添加SNAT规则”。

    IP按需计费，具体收费规则请参考弹性公网IP按需计费。

    安全组中不能将此IP禁用。

    通过此IP连通公网和私网。

    图16 添加SNAT规则1
    图17 添加SNAT规则2

步骤五：调用智能体

当前版本中，调试（Playground）主要用于快速体验。

  1. 在Managed Agents页面，选择“智能体 > Playground”。
  2. 在下拉框中选择已创建的智能体，单击“开始测试”。
  3. 在输入框中输入需要发送的信息（例如，你好），单击。
  4. 正常响应，即调试成功。
    图18 调试成功
父主题： 最佳实践

相关文档