# 公网模型与私网环境的智能体调测指南 #### 概述 Managed Agents支持在私网环境中运行智能体。当智能体关联的模型位于公网（如华为云MaaS），而运行环境位于私网时，智能体便处于"公网模型+私网环境"的跨网场景，此时因公网与私网之间网络不互通，会导致模型调用失败。需先打通公网与私网之间的网络，智能体才能正常运行。 #### 前提条件 - 已开通AgentArts服务，并在"管理中心 \> 授权管理"完成依赖云服务授权。 - 智能体需要关联模型，请在创建智能体之前完成添加模型。 #### 步骤一：添加模型 这里以添加华为云MaaS的GLM-5.3模型为例，采用标准OpenAI协议，区域选择"西南-贵阳一"。 如果已有可以使用的模型，则跳过此步骤。 #### 获取MaaS的GLM-5.3模型信息 1. 进入"西南-贵阳一"[MaaS页面](https://console.huaweicloud.com/modelarts/#/model-studio/homepage)，选择"模型推理 \> 在线推理"，找到GLM-5.3模型，查看模型类型。 图1获取模型信息1 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002754843984.png "点击放大") 2. 单击"API调用 \> 主推版本"，查看模型信息。 图2获取模型信息2 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002784242863.png "点击放大") 3. 获取模型API Key。 在MaaS左侧导航，选择"模型与统计 \> API Key管理"，单击"创建API Key"，如[图3]所示，复制并保存API Key信息。 图3创建API Key ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002754684092.png "点击放大") #### 添加模型供应商 1. 登录[AgentArts控制台](https://console.huaweicloud.com/agentarts)，在左侧导航选择"托管与运行 \> 模型"。 2. 单击"添加模型供应商"，配置模型供应商基本信息，如[图4]所示。 图4配置模型供应商基本信息 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002772766765.png "点击放大") 表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出站身份认证 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002809059797.png) 创建出站身份认证方式如下： 在"添加模型供应商"页面的"权限与访问控制"区域，单击"创建出站身份"，按页面提示填写身份名称、选择API Key类型、填写在MaaS界面获取的API Key。 图6创建出站身份 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002809061373.png "点击放大") 表2出站身份认证参数说明 | 参数 | 示例 | 说明 | |:---|:---|:---| | 出站身份认证 | **API Key认证** | 用于配置模型的认证方式。 | | 位置 | **标头** | API Key的传递位置。 调用MaaS的模型服务时，MaaS要求将API Key放在HTTP请求头中传递，因此选择"标头"。 | | 参数名称 (可选) | **Authorization** | 在请求中传递API的密钥时使用的具体名称。 调用MaaS OpenAI兼容接口时，鉴权请求头的名称必须是Authorization。 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002754843986.png "点击放大") | | 前缀 (可选) | **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出网网络配置 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002809059837.png) 表3出网网络配置参数说明 | 参数 | 示例 | 说明 | |:---|:---|:---| | 出网网络配置 | **公网访问** | 用于指定访问MaaS模型时使用的网络路径。 - 公网访问：能够连接到外部的互联网，访问外部的资源和服务。如无特殊网络要求，建议选择"公网访问"。 - 私网访问：连接内部的私有网络，访问内部的资源和服务。如需通过VPC内网访问模型，选择"私网访问"。 | 5. 高级配置。 保持默认。 模型供应商信息配置完成后，即可[添加模型服务]。 #### 添加模型服务 1. 单击"添加模型服务"，配置模型信息，如[图8]所示，配置完成后，单击"确定"。 图8配置模型信息 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002743247526.png "点击放大") 表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](https://support.huaweicloud.com/model-call-maas/model-call-020.html)。 | | 模型类型 | **文本对话/图像理解** | 模型支持的能力类别，须按模型实际能力选择。 - 文本对话/图像理解 - 文本向量化 - 多模态对话 - 文本排序 - 实时语音对话 | 2. 单击"创建"。 模型供应商显示在模型列表中，添加的模型服务显示在模型供应商详情页面的模型服务列表中，即可被选择使用。 #### 步骤二：创建环境 这里以创建私网环境为例。 在[Managed Agents](https://console.huaweicloud.com/agentarts/#/home/managed-agents/agent)页面，选择"环境"页签，单击"创建环境"，配置环境参数。创建后，环境显示在环境列表中。 图9创建环境 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002764860880.png "点击放大") 表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网关按需计费](https://support.huaweicloud.com/price-natgateway/nat_billing_0005.html)和[弹性公网IP按需计费](https://support.huaweicloud.com/price-eip/eip_billing_0007.html)。 当选择"私网访问"时，需配置如下参数： - 选择已配置的VPC，默认显示第一个。如未配置，请单击"新建VPC"，具体请参考[创建虚拟私有云和子网](https://support.huaweicloud.com/usermanual-vpc/zh-cn_topic_0013935842.html)。 - 选择已配置的子网，默认显示第一个。如未配置，请单击"新建子网"，具体请参考[创建虚拟私有云和子网](https://support.huaweicloud.com/usermanual-vpc/zh-cn_topic_0013935842.html)。 - 选择已配置的安全组，默认显示第一个。如未配置，请单击"新建安全组"，具体请参考[创建安全组](https://support.huaweicloud.com/usermanual-vpc/zh-cn_topic_0013748715.html)。 | | 存储配置 | 会话存储 | **勾选** **/data/managedagents** | 会话级别的持久化存储，用于保存会话上下文、中间结果、用户偏好等。存储资源由后台服务统一托管，每个会话拥有独立存储空间。配置后不可取消，仅支持1个。 挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含".."，最大长度为4000字符。 | | 存储配置 | SFS Turbo | **-** | 当"出网网络配置"选择"私网访问"时，支持此参数。 高性能分布式共享文件存储服务，支持多云主机、容器同时挂载访问，提供低时延、弹性扩容的持久化文件存储能力。最多添加5个SFS Turbo类型的存储，且SFS Turbo仅在私网访问下支持配置。 单击"添加"，详细参数配置请参考[表5](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0013.html#agentarts_13_0013__table1711433116404)。 | | 存储配置 | OBS | **-** | 当"出网网络配置"选择"私网访问"时，支持此参数。 用于保存会话过程中产生的文件等，存储资源为用户的OBS桶。最多只能选择5个不同的OBS桶，最多添加10个OBS类型的存储，且OBS仅在私网访问下支持配置。 单击"添加"，详细参数配置请参考[表5](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0013.html#agentarts_13_0013__table1711433116404)。 | #### 步骤三：创建智能体 在[Managed Agents](https://console.huaweicloud.com/agentarts/#/home/managed-agents/agent)页面，选择"智能体 \> 创建智能体 \> 自定义创建"，配置智能体参数。创建后，智能体显示在智能体列表中，并生成一个版本。 图10创建智能体 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002764970554.png "点击放大") 图11配置智能体 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002794394313.png "点击放大") 表6参数说明 | 参数 || 示例 | 说明 | |:---|---|:---|:---| | 基本信息 | 名称 | **agent-vpc** | 智能体的展示名称，供用户在列表中快速识别与检索该智能体。系统默认生成以agent开头的名称，可以自定义。创建后，不可修改。 由2\~40个字符组成，包含小写字母、数字和中划线，且必须以小写字母开头、以小写字母或数字结尾。 | | 基本信息 | 描述（可选） | **公网模型+私网环境** | 智能体的描述信息，帮助用户快速理解该智能体的作用。 由0\~4096个字符组成。 | | 模型及提示词 | 模型 | **maas/glm-5.3** | 智能体使用的模型。默认展示第一个模型。如未配置，请单击"模型管理"，具体请参考[模型](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0005.html)。不同模型的推理费用不同，请根据业务需求选择合适的模型。 | | 模型及提示词 | 提示词（可选） | **-** | 定义智能体的角色、行为规则和约束边界。由0\~32,768个字符组成。如何写好提示词，请参考[提示词](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0006.html)。 | | 环境 | 环境 | **environment-vpc** | 智能体的运行环境。环境是可复用的沙箱/容器模板，定义智能体会话实际执行任务的底层运行载体，回答"智能体在哪里执行任务"。创建环境请参考[配置智能体运行环境](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0012.html)。 默认展示第一个环境。 | | 工具与Skill | 内置工具（可选） | **-** | Managed Agents提供了bash、read_file、write_file、edit_file、glob、list_files、grep内置工具，当用户在会话中执行bash命令或文件操作时，为智能体选择内置工具。详细介绍请参考[内置工具](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0007.html)。 | | 工具与Skill | Skill（可选） | **-** | 最多支持选择50个Skill。 需要特定领域能力（如翻译、摘要）时，进行配置。详细介绍请参考[Skill](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0011.html)。 | | 权限与访问控制 | 委托 | **DefaultAgentArtsRuntimeAgency** | 注意： 委托权限决定了智能体可访问的外部资源范围。请遵循最小权限原则，仅授予必要的权限，避免因权限过大导致数据泄露或越权操作。 授予的代理权限或代理功能，允许代表智能体与外部系统进行通信和交互。 为了保证智能体运行时正常运行，所选委托需要具备相关权限。委托创建完成后可对委托进行授权，操作详情请参考[创建委托并授权](https://support.huaweicloud.com/usermanual-iam/iam_06_0002.html)。 系统默认值为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。 以上为最小权限要求。如需配置其他权限，请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)咨询OBS权限相关事宜。 | | 权限与访问控制 | 入网配置 | **defaultgw** | 警告： 入网配置创建后不可修改。请根据您的网络环境谨慎选择公网访问或VPC内网访问，配置后如需更改需重新创建智能体。 通过互联网或者VPC内网访问智能体运行时。更多信息请参考[网络配置](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_068.html)。 系统默认值为defaultgw。 公网访问适合需要从外部互联网调用的场景。VPC内网访问适合与VPC内其他云服务内网互通的场景，安全性更高。 | | 权限与访问控制 | 入站身份认证 | **API Key认证** **APIKey-1106369606** | 配置入站身份认证方式。在智能体接收到请求时，对请求进行身份验证和授权，确保请求来自可信的来源，并且具有访问特定资源的权限。 创建后，不可修改。 支持以下认证方式： - IAM认证：使用登录管理控制台时使用的IAM用户名进行认证。默认为IAM认证。 - OAuth 2.0认证：将OAuth 2.0配置为入站身份认证。选择"OAuth 2.0认证"后，相关参数配置请参考[表5](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0004.html#agentarts_13_0004__table1322435218288)。 - API Key认证：通过接口的访问密钥进行身份验证和授权。系统会自动生成API Key的名称，可根据需求自定义修改。 身份认证凭证在凭据管理服务（DEW）中托管，凭据托管按需计费，费用说明请参考[DEW计费说明](https://support.huaweicloud.com/price-dew/dew_03_0005.html)。 选择认证方式可以参考[表6](https://support.huaweicloud.com/managedagents-agentarts/agentarts_13_0004.html#agentarts_13_0004__table177641246174411)。 | | 可观测配置 | 日志记录 | **开启** | - 未开启，运行时过程产生的日志无法上报至云日志服务（LTS）。 - 开启后，运行时过程产生的日志会上报至云日志服务（LTS），日志管理费用按需收取，有关计费相关内容请参考[LTS计费说明](https://support.huaweicloud.com/price-lts/lts_001_04.html)。默认已开启。 开启后，调用智能体后，可在智能体详情"日志"页签中查看每次调用的输入输出、执行时长、工具调用记录等信息，用于调试智能体行为、排查异常和性能优化。 | | 高级配置 | 空闲会话超时 | **15** | 智能体在一段时间内无用户交互时，自动结束当前会话并释放运行资源，避免持续计费和资源占用。超时后会话终止，用户再次调用时需重新发起。 取值范围1\~10,080分钟，默认值15分钟。 时间越长，会话保持在线越久，资源占用和费用越高，但中断后可无缝续接；时间越短，费用更低，但短暂离开后再回来需重新发起会话。建议按实际使用频率权衡设置。不确定时，建议先用默认15分钟，后续按实际体验调整。 | | 高级配置 | 最大存活时间 | **24** | 会话从创建起可存续的最大时长，无论期间是否有交互，到时间后强制结束会话。用于防止会话长期占用资源，控制成本和生命周期风险。 取值范围1\~168小时，默认值24小时。 时间太短，长任务未执行完成即被强制中断，导致结果丢失需重新执行；时间太长，资源占用和费用持续累积。建议按任务最长耗时设置，留有余量即可。 | #### 步骤四：打通"公网模型+私网环境"的跨网场景 这里以通过NAT网关为例，介绍如何打通网络。 1. 进入虚拟私有云VPC控制台。 图12进入虚拟私有云VPC ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002794409271.png "点击放大") 2. 在左侧导航，选择"网络连接 \> NAT网关 \> 公网NAT网关"，单击"购买公网NAT网关"。 图13购买公网NAT网关 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002765130472.png "点击放大") 3. 配置NAT网关信息，单击"立即购买"，单击"提交"。 **虚拟私有云、子网与环境中的VPC、子网一致。** ![](https://support.huaweicloud.com/managedagents-agentarts/public_sys-resources/caution_3.0-zh-cn.png) NAT网关按需计费，具体收费规则请参考[NAT网关按需计费](https://support.huaweicloud.com/price-natgateway/nat_billing_0005.html)。 图14配置NAT网关 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002765100270.png "点击放大") 4. 在弹窗中，单击"添加规则"，添加SNAT规则。 图15添加规则 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002764941374.png) 5. 在"SNAT规则"页面，单击"添加SNAT规则"。 ![](https://support.huaweicloud.com/managedagents-agentarts/public_sys-resources/caution_3.0-zh-cn.png) IP按需计费，具体收费规则请参考[弹性公网IP按需计费](https://support.huaweicloud.com/price-eip/eip_billing_0007.html)。 安全组中不能将此IP禁用。 通过此IP连通公网和私网。 图16添加SNAT规则1 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002764958352.png "点击放大") 图17添加SNAT规则2 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002794472571.png "点击放大") #### 步骤五：调用智能体 **当前版本中，调试（Playground）主要用于快速体验。** 1. 在[Managed Agents](https://console.huaweicloud.com/agentarts/#/home/managed-agents/agent)页面，选择"智能体 \> Playground"。 2. 在下拉框中选择已创建的智能体，单击"开始测试"。 3. 在输入框中输入需要发送的信息（例如，你好），单击![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002806189305.png)。 4. 正常响应，即调试成功。 图18调试成功 ![](https://support.huaweicloud.com/managedagents-agentarts/zh-cn_image_0000002780225948.png "点击放大")