gateway sdk-j9九游会登录

场景介绍

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,
      log_delivery_configuration: optional[coregatewaylogdeliveryconfigurationrequestbody] = none,
  ) -> requestresult

  表3 更新网关参数说明

  参数	类型	是否必选	说明
  gateway_id	str	是	要更新的gateway的唯一标识符
  description	optional[str]	否	网关的详细描述
  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	搜索操作配置
  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 coregatewayauthorizerconfiguration

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

  表15 coregatewaycustomjwtauthorizerconfiguration

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

  表16 coregatewaykeyauthauthorizerconfiguration

  参数	类型	说明
  api_keys	array	api 密钥列表。

  表17 coregatewaylogdeliveryconfigurationrequestbody

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

  表18 coregatewayoutboundnetworkconfiguration

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

  表19 coregatewayvpcconfig

  参数	类型	说明
  vpc_id	string	vpc id，vpc网络的唯一标识
  subnet_id	string	子网id，vpc子网的唯一标识。
  security_group_ids	array	安全组id列表。

  表20 coregatewaytag

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

• 响应参数

  表21 listcoregatewaysresponse

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

  表22 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	更新时间戳

  表23 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	更新时间戳

  表24 listcoregatewaytargetsresponse

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

  表25 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	更新时间戳

  表26 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  \
       --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 
   agentarts mcp-gateway get-target  

示例代码

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("网关已删除")