创建网关

前提条件

• 使用网关前需要先开通AgentArts服务并进行服务授权，请在“授权管理”页面进行云服务开通及授权，详细信息请参考授权管理。
• （可选）管理员可在IAM控制台为创建的IAM子用户授予权限，授权后，子用户即可根据权限使用账号中的云服务资源，相关操作步骤如下。
  1. 创建IAM用户。
  2. 给IAM用户授权。
     • 为子用户授予完整的网关权限，需授予AgentArtsFullAccessPolicy身份策略。
     • 创建自定义身份策略并授予如下权限，授权项功能介绍请参考表1。

       表1 授权项

       操作	授权项	功能介绍
       创建网关	iam:agencies:pass	授予向云服务传递委托的权限。
       	vpc:nativePorts:create	授予原生API创建端口权限。
       	vpc:routeTables:update	授予更新路由表权限。
       	eip:publicIps:associateInstance（涉及公网访问时需要）	授予将弹性公网IP绑定网卡的权限。
       删除网关	vpc:routeTables:update	授予更新路由表权限。
       	vpc:nativePorts:delete	授予原生API删除端口权限。
       	eip:publicIps:disassociateInstance（涉及公网访问时需要）	授予将弹性公网IP解绑网卡的权限。
       创建网关的入站认证功能	csms:secret:getVersion	授予查询指定凭据版本的信息和其明文凭据值的权限。
       	kms:cmk:decryptDataKey	授予解密数据密钥的权限。
       出站网络使用VPC网络	vpcep:endpoints:create	授予指定服务创建VPC终端节点的权限。
       	vpcep:endpoints:delete	授予删除终端节点的权限。

• 创建网关时需要创建委托并授权，请确保传入的委托包含以下身份策略权限：

  表2 授权项

  授权项	功能介绍
  csms:secret:getVersion	授予查询指定凭据版本的信息和其明文凭据值的权限。
  kms:cmk:decryptDataKey	授予解密数据密钥的权限。
  agentIdentity::getResourceApiKey	授予获取与API密钥凭证提供者关联的API密钥的权限。
  agentIdentity::getResourceOauth2Token	授予通过OAuth2两方/三方授权流程获取访问令牌，以访问外部资源的权限。
  agentIdentity::getResourceStsToken	授予从STS凭证提供者获取IAM临时凭证的权限。

约束与限制

一个租户最多可创建10个网关，如需调整配额，请提交工单申请。

创建网关

1. 登录AgentArts智能体平台。
2. 在左侧导航栏选择“托管与运行 > 网关”，进入网关界面。
3. 单击右上角“创建网关”。
4. 在“创建网关”的页面中，输入网关的配置信息，参数说明请参考表3。

   表3 参数说明

   参数		说明
   基本信息	名称	网关的名称，同一账号下网关名称不可重复。 命名规则： 以小写字母开头，小写字母或数字结尾。 支持小写字母、数字和中划线。 长度为 2-40 个字符。 系统会默认生成网关的名称，可根据需求自定义修改。
   	描述	用于对网关内容和用途的简要说明。 规则：长度不大于1000个字符。
   	MCP 版本	支持配置MCP协议版本，可以选择一个或多个支持的MCP协议版本（如2025-03-26、2025-06-18、2025-11-25）。 关于协议版本的介绍、配置及相关约束等可参考MCP协议版本介绍。
   权限与身份认证	委托	授予的代理权限或代理功能，允许代表智能体与外部系统进行通信和交互。 可使用系统默认创建的AgentArtsGatewayAgency委托。 如需手动创建，请单击“创建委托”并参考如下配置创建。 委托名称：自定义。 信任主体类型：选择“云服务”。 云服务：搜索service.WorkloadSandboxMetadata。 其余参数使用默认值。 图1 创建委托 委托创建完成后可对委托进行授权，操作具体详情请参考创建委托并授权。
   	入网配置	选择入站网关，通过互联网或者VPC内网访问网关服务。如下拉框无选项，请单击“创建网络配置”创建新的网络配置。 选择后修改网关时入网配置无法修改。 说明： 入网配置关联VPC内网时，则不支持调测以及语义检索功能。
   	入站身份认证	配置网关的身份认证方式。入站身份认证是指网关在接收和处理来自智能体或SDK的请求时，对请求进行身份验证，确保只有经过验证的请求才能进入网关，提高系统的安全性和可靠性。 支持以下认证方式： IAM认证：使用登录管理控制台时使用的IAM用户名进行认证。 OAuth 2.0认证：将OAuth 2.0配置为入站身份认证。选择“OAuth 2.0认证”后，相关参数配置请参考表4。 API Key认证：通过接口的访问密钥进行身份验证和授权。系统会自动生成API Key的名称，可根据需求自定义修改。 身份认证凭证在凭据管理服务（DEW）托管，托管按需计费，费用说明请参考DEW 计费说明。
   可观测配置	日志记录	未开启，网关使用过程产生的日志无法上报至云日志服务。 开启后，网关使用过程产生的日志会上报云日志服务（LTS），日志管理费用按需收取，有关计费相关内容请参考LTS计费详情。
   关联Target	创建Target	单击“创建Target”按钮完成Target创建后，网关将与新创建的Target关联。 创建Target详情请参考创建Target。 同一个网关中可以同时挂载MCP和推理两种Target，请求各自走独立路径，互不干扰。
   工具检索	语义检索	语义检索是一种基于自然语言处理的技术，用于从大量文本数据中提取和检索相关信息。在网关中启用语义检索功能后，调用网关时会优先通过检索筛选匹配工具，工具数量较多时建议开启。 “语义检索”仅针对MCP协议的Target。 开启后，将为您自动创建服务关联委托如图2，委托中的授权项包含以下action： agentIdentity::getAuthorizerConfiguration： 授予查询工作负载身份授权配置的权限。 图2 服务关联委托 Top N：用于设置返回的匹配结果数量，从所有工具中选择匹配度排名前N条返回。可以输入1到100之间的整数，表示系统在匹配时返回的前N个最相关的工具或结果。默认值为10，您可以根据需要增加或减少这个数值。数值越大返回越多，但可能包含相关度较低的内容。 相似阈值：用于设置匹配结果的相似度阈值。可以输入0到0.9之间的数值（精确到小数点后一位），表示系统在匹配时返回的结果与查询内容的相似度必须达到或超过这个阈值。默认值为0.7，您可以根据需要调整这个数值。数值越接近1，表示匹配结果的相似度要求越高。值越高结果越精准，但可能返回更少甚至为空。建议配合Top N数值一起调整。 关于语义检索的tools/call的调用示例请参考检索网关工具。
   高级配置	私网访问	连接内部的私有网络，访问内部的资源和服务。 选择已配置的VPC，如未配置，请单击“新建VPC”，具体请参考创建虚拟私有云和子网。 选择已配置的子网，如未配置，请单击“新建子网”，具体请参考创建虚拟私有云和子网。 选择已配置的安全组，如未配置，请单击“新建安全组”，具体请参考创建安全组。 配置后可单击刷新。
   	公网访问	能够连接到外部的互联网，访问外部的资源和服务。
   	会话保持	开启后，通过同一个mcp-session-id调用网关时，网关将与后端目标（Target）保持会话，用于后续多轮交互。 “会话保持”仅针对MCP协议的Target。 如果Target的名称、配置信息以及出站身份认证信息发生变更（除描述外），则网关和该Target的会话将会重建。
   	标签 (可选)	由“标签键”和“标签值”组成，用于标识和分类云资源。 您可以在TMS中创建预定义标签，用于使用同一标签标识多种云资源，创建后可在标签输入框下拉选择同一标签，具体操作请参考创建预定义标签，创建后单击刷新。 单击“添加标签”，选择在TMS中创建的预定义标签，或自定义输入标签键和标签值。 可添加一个或多个标签，最多添加20个标签。

   表4 OAuth 2.0认证参数配置说明

   参数	说明
   Discovery URL	OAuth发现服务器（OAuth discovery server）只支持公网权威的认证服务器，即服务端证书必须能够校验通过。 需输入身份提供商（例如Okta、Cognito等）提供的Discovery URL，该URL通常可在该提供商的文档中找到。输入以https:// 开头，/.well-known/openid-configuration结尾的有效 URL。
   JWT授权配置
   允许的受众	用于认证为OAuth 2.0指定的受众是否在Agent Identity运行中指定的受众匹配或为其子集。 支持添加100个受众。
   允许的客户端	用于认证为OAuth 2.0指定的客户端标识符是否被允许访问Agent Identity。 支持添加100个客户端。
   允许的范围	仅当令牌包含此处配置的至少一个必须范围时才允许访问自定义声明。 支持添加100个范围。
   自定义声明	仅当令牌中的特定声明与预定义字符串值相匹配时才允许访问。 支持添加100个自定义声明。

5. 单击“确定”。即可在网关列表中展示已创建的网关，单击网关名称，查看网关详情。

MCP协议版本介绍

MCP（模型上下文协议）是智能体连接外部工具与数据的通用开放标准。为保障协议兼容性，AgentArts在创建网关时支持配置一个或多个MCP协议版本。网关创建后，调用接口时网关会校验请求中携带的协议版本是否在已配置的支持列表中。