Gateway SDK

场景介绍

Gateway SDK提供管理网关及相关操作的命令行工具，支持网关和网关目标的创建、查询、更新、删除等功能。

前提条件

• 已开通AgentArts。

• 登录控制台获取AK/SK，详情请参考认证鉴权。

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

• 已安装Python，且版本不低于3.10。查看Python版本的命令示例：

  python --version

网关管理

• 创建网关

  def create_gateway(
      self,
      name: Optional[str] = None,
      description: Optional[str] = None,
      protocol_type: Optional[str] = "mcp",
      authorizer_type: Optional[str] = "iam",
      agency_name: Optional[str] = None,
      protocol_configuration: dict[str, Any] | None = None,
      authorizer_configuration: Optional[CoreGatewayAuthorizerConfiguration] = None,
      log_delivery_configuration: Optional[CoreGatewayLogDeliveryConfigurationRequestBody] = None,
      outbound_network_configuration: Optional[CoreGatewayOutboundNetworkConfiguration] = None,
      tags: list[dict[str, str]] | None = None
  ) -> RequestResult

  表1 创建网关参数说明

  参数	类型	是否必选	默认值	说明
  name	Optional[str]	否	gateway-{8个随机字符后缀}	网关名称
  description	Optional[str]	否	-	网关的详细描述
  protocol_type	Optional[str]	否	mcp	网关协议类型
  authorizer_type	Optional[str]	否	iam	授权器类型，可选值：custom_jwt、iam、api_key
  agency_name	Optional[str]	否	AgentArtsCoreGateway	网关委托身份的委托名称
  protocol_configuration	Optional[CoreGatewayProtocolConfiguration]	否	-	网关协议的自定义设置
  authorizer_configuration	Optional[CoreGatewayAuthorizerConfiguration]	否	-	授权器配置
  log_delivery_configuration	Optional[CoreGatewayLogDeliveryConfigurationRequestBody]	否	-	日志投递配置
  outbound_network_configuration	Optional[CoreGatewayOutboundNetworkConfiguration]	否	-	出站网络配置
  tags	Optional[CoreGatewayTag]	否	-	资源标签列表

  授权器配置要求：

  • 当authorizer_type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置。
  • 当authorizer_type = 'api_key' 时，必须提供key_auth配置。
• 查询网关信息

  def get_mcp_gateway(self, gateway_id: str) -> ShowCoreGatewayResponse

  表2 查询网关参数说明

  参数	类型	是否必选	说明
  gateway_id	str	是	要查询的Gateway的唯一标识符

• 更新指定的网关信息

  def update_gateway(
      self,
      gateway_id: str,
      description: Optional[str] = None,
      protocol_configuration: Optional[CoreGatewayProtocolConfiguration] = None,
      log_delivery_configuration: Optional[CoreGatewayLogDeliveryConfigurationRequestBody] = None,
  ) -> RequestResult

  表3 更新网关参数说明

  参数	类型	是否必选	说明
  gateway_id	str	是	要更新的Gateway的唯一标识符
  description	Optional[str]	否	网关的详细描述
  protocol_configuration	Optional[CoreGatewayProtocolConfiguration]	否	网关协议的自定义设置
  log_delivery_configuration	Optional[CoreGatewayLogDeliveryConfigurationRequestBody]	否	日志投递配置

  

  更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。

• 删除指定的网关信息

  def delete_gateway(self, gateway_id: str) -> DeleteCoreGatewayResponse

  表4 更新网关参数说明

  参数	类型	是否必选	说明
  gateway_id	str	是	要删除的Gateway的唯一标识符

• 获取网关列表

  def list_gateways(
      self,
      name: Optional[str] = None,
      status: Optional[str] = None,
      gateway_id: Optional[str] = None,
      tag_key_exists: list[str] | None = None,
      tag_key_matches: list[str] | None = None,
      tag_value_matches: list[str] | None = None,
      tag_match_policy: str | None = None,
      limit: Optional[int] = None,
      offset: Optional[int] = None) -> ListCoreGatewaysResponse

  表5 获取网关实例列表参数说明

  参数	类型	是否必选	默认值	说明
  name	Optional[str]	否	-	按名称过滤网关，支持模糊匹配
  status	Optional[str]	否	-	按状态过滤网关
  gateway_id	Optional[str]	否	-	按网关ID过滤，支持多个ID（最多20个），用逗号分隔
  tag-key-exists	list[str]	否	-	按标签键存在过滤（逗号分隔）
  tag-key-matches	list[str]	否	-	按标签键值对过滤-键（逗号分隔）
  tag-value-matches	list[str]	否	-	按标签键值对过滤-值（逗号分隔）
  tag-match-policy	list[str]	否	-	标签匹配模式（ALL/ANY）
  limit	Optional[int]	否	50	返回结果的最大数量
  offset	Optional[int]	否	0	返回结果的偏移量

• 在指定的网关下创建新的Target实例

  def create_gateway_target(
      self,
      gateway_id: str,
      name: Optional[str] = None,
      description: Optional[str] = None,
      target_configuration: Optional[CoreGatewayTargetConfiguration] = None,
      credential_provider_configuration: Optional[CoreGatewayCredentialProviderConfiguration] = None) -> CreateCoreGatewayTargetResponse

  表6 创建Target参数说明

  参数	类型	是否必选	默认值	说明
  gateway_id	str	是	-	目标Gateway的唯一标识符
  name	Optional[str]	否	target-{8个随机字符后缀}	Target服务名称
  description	Optional[str]	否	-	Target服务描述
  target_configuration	Optional[CoreGatewayTargetConfiguration]	是	-	Target服务配置，mcp_server内容必须提供
  credential_provider_configuration	Optional[CoreGatewayCredentialProviderConfiguration]	否	-	凭证提供者配置

  凭证提供者配置要求：

  • 如果不提供，credential_provider_type默认为none，表示无认证。
  • 当credential_provider_type='oauth' 时，必须提供oauth_credential_provider。
  • 当credential_provider_type='api_key' 时，必须提供api_key_credential_provider。
• 查询指定Gateway下的特定Target实例的详细信息

  def get_gateway_target(self, gateway_id: str, target_id: str) -> ShowCoreGatewayTargetResponse

  表7 查询 Target信息参数说明

  参数	类型	是否必选	说明
  gateway_id	str	是	Target所属Gateway的唯一标识符
  target_id	str	是	要查询的Target的唯一标识符

• 更新指定网关下的特定Target实例

  def update_gateway_target(
      self,
      gateway_id: str,
      target_id: str,
      name: Optional[str] = None,
      description: Optional[str] = None,
      target_configuration: Optional[CoreGatewayTargetConfiguration] = None,
      credential_provider_configuration: Optional[CoreGatewayCredentialProviderConfiguration] = None) -> UpdateCoreGatewayTargetResponse

  表8 更新Target参数信息

  参数	类型	是否必选	说明
  gateway_id	str	是	Target所属Gateway的唯一标识符
  target_id	str	是	要更新的Target的唯一标识符
  name	Optional[str]	否	Target服务名称
  description	Optional[str]	否	Target服务描述
  target_configuration	Optional[CoreGatewayTargetConfiguration]	否	Target服务配置
  credential_provider_configuration	Optional[CoreGatewayCredentialProviderConfiguration]	否	凭证提供者配置

• 删除指定网关下的特定Target实例

  def delete_mcp_gateway_target(self, gateway_id: str, target_id: str) -> DeleteCoreGatewayTargetResponse

  表9 删除Target参数说明

  参数	类型	是否必选	说明
  gateway_id	str	是	Target所属Gateway的唯一标识符
  target_id	str	是	要删除的Target的唯一标识符

• 查询指定网关下的所有Target列表

  def list_mcp_gateway_targets(
      self,
      gateway_id: str,
      limit: Optional[int] = None,
      offset: Optional[int] = None) -> ListCoreGatewayTargetsResponse

  表10 查询指定网关下的Target列表参数说明

  参数	类型	是否必选	默认值	说明
  gateway_id	str	是	-	要查询Targets的Gateway的唯一标识符
  limit	Optional[int]	否	50	每页返回的最大结果数量
  offset	Optional[int]	否	0	返回结果的偏移量

参数说明

• 请求参数

  表11 CoreGatewayProtocolConfiguration

  参数	类型	说明
  mcp	CoreGatewayMcpProtocolConfiguration	网关协议的自定义设置

  表12 CoreGatewayMcpProtocolConfiguration

  参数	类型	说明
  search_configuration	CoreGatewaySearchConfiguration	搜索操作配置
  session_configuration	CoreGatewaySessionConfiguration	会话管理配置
  supported_versions	Array	MCP网关支持的协议版本列表，支持选择的MCP版本：2025-03-26、2025-06-18、2025-11-25。默认值：[2025-03-26]

  表13 CoreGatewaySearchConfiguration

  参数	类型	说明
  search_type	CoreGatewaySearchConfiguration	搜索类型，该字段用于指定网关如何处理搜索操作。
  top_n	integer	当search_type为semantic时，该字段可选。用于指定语义检索场景返回的工具数量。
  score_threshold	string	当search_type为semantic时，该字段可选。语义检索场景，只有工具的相似得分不低于该值时才会返回。

  表14 CoreGatewaySessionConfiguration

  参数	类型	说明
  enabled	bool	是否开启会话管理，默认关闭。

  表15 CoreGatewayAuthorizerConfiguration

  参数	类型	说明
  custom_jwt_authorizer	CoreGatewayCustomJWTAuthorizerConfiguration	搜索类型，该字段用于指定网关如何处理搜索操作。
  key_auth	CoreGatewayKeyAuthAuthorizerConfiguration	当search_type为semantic时，该字段可选。用于指定语义检索场景返回的工具数量

  表16 CoreGatewayCustomJWTAuthorizerConfiguration

  参数	类型	说明
  discovery_url	String	JWT 发现 URL。
  allowed_audience	Array	允许的 JWT 受众（aud）列表，用于验证令牌的预期接收者。
  allowed_clients	Array	允许的客户端 ID 列表，用于限制哪些客户端可以访问。
  allowed_scopes	Array	允许的 JWT 作用域（scope）列表，用于控制访问权限
  custom_claims	Array	自定义声明验证规则列表，用于验证 JWT 中的自定义声明。

  表17 CoreGatewayKeyAuthAuthorizerConfiguration

  参数	类型	说明
  api_keys	Array	API 密钥列表。

  表18 CoreGatewayLogDeliveryConfigurationRequestBody

  参数	类型	说明
  enabled	Boolean	是否启用日志上报。

  表19 CoreGatewayOutboundNetworkConfiguration

  参数	类型	说明
  network_mode	String	网络模式。取值范围：public | vpc
  vpc_config	CoreGatewayVpcConfig	VPC网络配置。

  表20 CoreGatewayVpcConfig

  参数	类型	说明
  vpc_id	String	VPC ID，VPC网络的唯一标识
  subnet_id	String	子网ID，VPC子网的唯一标识。
  security_group_ids	Array	安全组ID列表。

  表21 CoreGatewayTag

  参数	类型	说明
  key	String	标签键。
  value	String	标签值。

  表22 CoreGatewayTargetConfiguration

  参数	类型	说明
  mcp_server	CoreGatewayMcpServerTargetConfiguration	MCP Server 配置
  openapi	CoreGatewayOpenApiTargetConfiguration	OpenAPI 配置
  dedicated_gateway_api	CoreGatewayDedicatedGatewayApiTargetConfiguration	专享网关API
  huawei_cloud_api	CoreGatewayHuaweiCloudApiTargetConfiguration	华为云API

  表23 CoreGatewayMcpServerTargetConfiguration

  参数	类型	说明
  endpoint	String	MCP服务器端点URL
  server_type	String	MCP服务器类型，取值范围： sse: 使用Server-Sent Events长连接 streamable_http: 使用可流式 HTTP 请求

  表24 CoreGatewayOpenApiTargetConfiguration

  参数	类型	说明
  payload	String	OpenAPI 规范目标配置，支持内联文档或从OBS获取规范文档
  obs	CoreGatewayObsConfiguration	OBS（对象存储服务）配置，用于从 OBS 获取 OpenAPI 规范文档

  表25 CoreGatewayDedicatedGatewayApiTargetConfiguration

  参数	类型	说明
  payload	String	OpenAPI 规范目标配置，支持内联文档或从OBS获取规范文档
  obs	CoreGatewayObsConfiguration	OBS（对象存储服务）配置，用于从OBS获取OpenAPI规范文档

  表26 CoreGatewayHuaweiCloudApiTargetConfiguration

  参数	类型	说明
  payload	String	OpenAPI 规范文档内容（JSON或YAML格式的内联内容）

  表27 CoreGatewayObsConfiguration

  参数	类型	说明
  bucket_name	String	OBS 桶名称
  object_key	String	OBS 对象键名（文件路径）：示例：specs/petstore.yaml

  表28 CoreGatewayCredentialProviderConfiguration

  参数	类型	说明
  credential_provider_type	String	凭证提供者类型； 取值范围： iam：使用网关 IAM 角色，当target_type取值为openapi时，不支持 oauth：使用 OAuth 2.0，当target_type取值为dedicated_gateway_api以及huawei_cloud_api时，不支持 api_key：使用 API 密钥，当target_type取值为dedicated_gateway_api以及huawei_cloud_api时，不支持 none：无认证 默认取值： 不涉及
  credential_provider	CoreGatewayCredentialProvider	凭证提供者配置

  表29 CoreGatewayCredentialProvider

  参数	类型	说明
  api_key_credential_provider	CoreGatewayApiKeyCredentialProvider	API KEY凭证提供者配置
  oauth_credential_provider	CoreGatewayOAuthCredentialProvider	OAuth凭证提供者配置
  iam_credential_provider	CoreGatewayIamCredentialProvider	Iam凭证提供者配置

  表30 CoreGatewayApiKeyCredentialProvider

  参数	类型	说明
  provider_name	String	凭证提供者名称
  credential_location	String	凭证传递位置； 取值范围： header：通过HTTP请求头传递API密钥 query：通过URL查询参数传递API密钥
  credential_parameter_name	String	凭证参数名称
  credential_prefix	String	凭证前缀（如 "Bearer "）

  表31 CoreGatewayOAuthCredentialProvider

  参数	类型	说明
  provider_name	String	凭证提供者名称
  grant_type	String	OAuth 授权类型； 取值范围： client_credentials：适用于服务器到服务器通信 authorization_code：适用于需要用户授权的应用
  scopes	Array	OAuth作用域列表
  default_return_url	String	默认返回URL
  custom_parameters	Object	自定义参数，键值对形式。

  表32 CoreGatewayIamCredentialProvider

  参数	类型	说明
  provider_name	String	凭证提供者名称

• 响应参数

  表33 ListCoreGatewaysResponse

  字段	类型	说明
  gateways	List[CoreGatewaySummary]	网关详情列表
  size	Integer	当前页返回的网关数量
  total	Integer	网关总数量

  表34 CoreGatewaySummary

  字段	类型	说明
  gateway_id	String	网关的唯一标识符
  name	String	目标名称
  status	String	目标状态。取值范围：active: 运行中 | inactive: 已停用 | creating: 创建中 | failed: 创建或运行失败 | deleting: 删除中 | updating: 更新中
  inactive_reason	String	目标服务离线状态原因。
  protocol_type	String	网关协议类型。
  authorizer_type	String	授权器类型。
  agency_name	string	委托名称，用于指定网关使用的委托身份。
  tags	Array	资源标签列表。 取值范围： 数组长度为 0-20。
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表35 ShowCoreGatewayResponse

  字段	类型	说明
  gateway_id	String	网关的唯一标识符
  name	String	网关名称。 取值范围： 长度为 2-40 个字符，
  description	String	网关的详细描述。 取值范围： 长度为 1-1000 个字符。
  status	String	目标状态。取值范围：active: 运行中 | inactive: 已停用 | creating: 创建中 | failed: 创建或运行失败 | deleting: 删除中 | updating: 更新中
  inactive_reason	String	目标服务离线状态原因。
  protocol_type	String	网关协议类型。
  protocol_configuration	Object	网关协议的自定义设置
  authorizer_type	String	授权器类型。
  agency_name	String	委托名称，用于指定网关使用的委托身份。
  endpoint_url	String	访问网关的 URL 端点。
  log_delivery_configuration	Object	日志上报配置。
  workload_identity	Object	工作负载身份标识，用于代理身份认证。
  agent_gateway_id	String	AgentGateway ID，关联底层 AgentGateway 实例。
  outbound_network_configuration	Object	网络模式。
  tags	Array	资源标签列表。 取值范围： 数组长度为 0-20。
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表36 ListCoreGatewayTargetsResponse

  字段	类型	说明
  targets	List[CoreGatewayTargetSummary]	网关详情列表
  size	Integer	当前页返回的网关数量
  total	Integer	网关总数量

  表37 CoreGatewayTargetSummary

  字段	类型	说明
  target_id	String	目标唯一标识符
  gateway_id	String	所属网关的标识符
  name	String	目标名称
  status	String	目标状态。取值范围：creating: 创建中 | updating: 更新中 | ready: 就绪可用 | failed: 失败 | deleting: 删除中 | synchronize_pending: 等待同步中 | synchronizing: 同步中 | active: 在线 | inactive: 离线
  inactive_reason	String	目标服务离线状态原因。
  target_type	String	目标服务类型。 取值范围：mcp_server: MCP 服务器 | openapi: 基于 OpenAPI 规范的 REST API
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表38 ShowCoreGatewayTargetResponse

  字段	类型	说明
  target_id	String	目标唯一标识符
  gateway_id	String	所属网关的标识符
  name	String	目标名称
  description	String	目标描述
  status	String	目标状态。取值范围：creating: 创建中 | updating: 更新中 | ready: 就绪可用 | failed: 失败 | deleting: 删除中 | synchronize_pending: 等待同步中 | synchronizing: 同步中 | active: 在线 | inactive: 离线
  inactive_reason	String	目标服务离线状态原因。
  target_type	String	目标服务类型。 取值范围：mcp_server: MCP 服务器 | openapi: 基于 OpenAPI 规范的 REST API
  target_configuration	Object	目标配置
  credential_provider_configuration	Object	凭证提供者配置
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

快速入门

1. 创建网关。

   # Client模式
   result = client.create_gateway(
       name="my-gateway",
       description="我的第一个MCP网关"
   )
   gateway_id = result.data.get("gateway_id")
   
   # CLI模式
   agentarts gateway create --name "my-gateway" --description "我的第一个MCP网关"

2. 创建目标。

   # Client模式
   target_result = client.create_gateway_target(
       gateway_id=gateway_id,
       target_configuration={
           "mcp_server": {
               "endpoint": "https://echo.example.com",
               "server_type": "sse"
           }
       }
   )
   target = target_result.data.get("target")
   target_id = target.get("target_id")
   
   # CLI模式
   agentarts gateway create-target <gateway-id> \
       --target-configuration '{\"mcp_server\":{\"endpoint\":\"https://example.com/mcp\",\"server_type\":\"sse\"}}'

3. 查询信息。

   # Client模式
   gateway_info = client.get_gateway(gateway_id)
   target_info = client.get_gateway_target(gateway_id, target_id)
   
   
   # CLI模式
   agentarts mcp-gateway get <gateway-id>
   agentarts mcp-gateway get-target <gateway-id> <target-id>

示例代码

from typing import Optional, List
from agentarts.sdk.gateway import GatewayClient

# 初始化客户端
client = GatewayClient()
# 创建MCP Gateway
result = client.create_gateway(
    name="production-echo-gateway",
    description="生产环境 Echo 服务网关",
    authorizer_type="iam"
)
gateway = result.data
print(f"创建的网关ID: {gateway.get('gateway_id')}")

# 更新网关描述
result = client.update_gateway(
    gateway_id=gateway.get('gateway_id'),
    description="更新后的网关描述"
)
updated_gateway = result.data
print(f"更新后的描述: {updated_gateway.get('description')}")

# 在网关下创建Target（MCP服务器类型）
result = client.create_gateway_target(
    gateway_id=gateway.get('gateway_id'),
    name="echo-service-target",
    description="Echo服务目标",
    target_configuration={
        "mcp_server": {
            "endpoint": "https://echo.example.com",
            "server_type": "sse"
        }
    }
)
target = result.data.get("target")
target_id = target.get("target_id")
print(f"目标创建成功，ID: {target_id}")

# 在网关下创建Target（OpenAPI内联文档类型）
result = client.create_gateway_target(
    gateway_id=gateway.get('gateway_id'),
    name="petstore-api",
    description="PetStore API目标",
    target_configuration={
        
        "openapi": {
          "payload": "{\"info\":{\"description\":\"Search & Content Management API (OpenAPI 3.0.0 compliant)\",\"title\":\"Search & Content API - APIs Scene\",\"version\":\"1.0.0\"},\"openapi\":\"3.0.0\",\"servers\":[{\"url\":\"https://api.example.com/v1\"}],\"paths\":{\"/api/resource/1\":{\"post\":{\"operationId\":\"createResource1\",\"summary\":\"Create resource 1\",\"requestBody\":{\"required\":true,\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ContentBase\"}}}},\"responses\":{\"201\":{\"description\":\"Created success\",\"content\":{\"application/json\":{\"schema\":{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"integer\"},\"title\":{\"type\":\"string\"}}}}}}}}}},\"components\":{\"schemas\":{\"ContentBase\":{\"type\":\"object\",\"required\":[\"title\"],\"properties\":{\"title\":{\"type\":\"string\"},\"isPublic\":{\"type\":\"boolean\"},\"tags\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"metadata\":{\"type\":\"object\",\"properties\":{\"createTime\":{\"type\":\"string\"},\"operator\":{\"type\":\"string\"}}}}}}}}"
        }
    }
)
target = result.data.get("target")
target_id = target.get("target_id")
print(f"OpenAPI目标创建成功，ID: {target_id}")

# 在网关下创建Target（OpenAPI OBS文档类型）
result = client.create_gateway_target(
    gateway_id=gateway.get('gateway_id'),
    name="petstore-api-obs",
    description="PetStore API目标（OBS）",
    target_configuration={
        "openapi": {
            "obs": {
                "bucket_name": "api-specs-bucket",
                "object_key": "specs/petstore.yaml"
            }
        }
    }
)
target = result.data.get("target")
target_id = target.get("target_id")
print(f"OpenAPI OBS 目标创建成功，ID: {target_id}")

# 查询网关信息
result = client.get_gateway(gateway.get('gateway_id'))
gateway_info = result.data
print(f"网关状态: {gateway_info.get('status')}")

# 查询目标信息
result = client.get_gateway_target(gateway.get('gateway_id'), target.get('target_id'))
target_info = result.data.get("target")
print(f"目标状态: {target_info.get('status')}")

# 列出网关下的所有目标
result = client.list_gateway_targets(gateway.get('gateway_id'))
targets = result.data
print(f"网关下有 {targets.get('total')} 个目标")

# 更新Target描述
result = client.update_gateway_target(
    gateway_id=gateway.get('gateway_id'),
    target_id=target.get('target_id'),
    description="更新后的Echo服务目标描述"
)
updated_target = result.data.get("target")
print(f"更新后的描述: {updated_target.get('description')}")

# 删除Target
client.delete_gateway_target(gateway.get('gateway_id'), target.get('target_id'))
print("目标已删除")

# 删除Gateway
client.delete_gateway(gateway.get('gateway_id'))
print("网关已删除")