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_mcp_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
更新时间戳
快速入门
- 创建网关。
# 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网关" - 创建目标。
# 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\"}}' - 查询信息。
# 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("网关已删除") 
