agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/_gateway_target_wizard.py

@@ -0,0 +1,293 @@
+"""Prompt-based port of tui/screens/mcp AddGatewayTargetScreen / useAddGatewayTargetWizard / Flow.
+
+Question order: name -> target type -> type-specific steps -> gateway -> outbound auth -> confirm,
+following the step lists in useAddGatewayTargetWizard.ts.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+import typer
+
+from agentcore.cli import interactive
+from agentcore.cli.commands.add._common import first_issue, js_url_ok
+from agentcore.cli.errors import get_error_message
+from agentcore.schema import PASSTHROUGH_PROTOCOL_TYPES, TARGET_TYPE_AUTH_CONFIG, ToolName
+
+if TYPE_CHECKING:
+    from agentcore.primitives.gateway_target import GatewayTargetPrimitive
+
+TARGET_TYPE_OPTIONS = [
+    ("mcpServer", "MCP Server endpoint", "Connect to an existing MCP-compatible server"),
+    ("apiGateway", "API Gateway REST API", "Connect to an existing Amazon API Gateway REST API"),
+    ("openApiSchema", "OpenAPI Schema", "Auto-derive tools from an OpenAPI JSON spec"),
+    ("smithyModel", "Smithy Model", "Auto-derive tools from a Smithy JSON model"),
+    ("lambdaFunctionArn", "Lambda function", "Connect to an existing AWS Lambda function"),
+    ("httpRuntime", "HTTP Runtime", "Route HTTP traffic to an AgentCore runtime"),
+    ("connector", "Knowledge Base", "Wire an existing Knowledge Base to this gateway as a connector target"),
+    ("passthrough", "Passthrough", "Route to external HTTPS endpoint"),
+    ("webSearch", "Amazon Web Search", "Wire the Amazon Web Search managed connector to this gateway"),
+]
+AUTH_OPTION_LABELS = {
+    "NONE": ("No authorization", "No outbound authentication"),
+    "OAUTH": ("OAuth 2LO", "OAuth 2.0 client credentials"),
+    "API_KEY": ("API Key", "API key credential"),
+    "GATEWAY_IAM_ROLE": ("Gateway IAM Role", "Gateway signs with SigV4"),
+    "JWT_PASSTHROUGH": ("JWT Passthrough", "Forward caller JWT token"),
+}
+ENTER_KB_ID_MANUALLY = "__enter_kb_id__"
+_KB_ID = re.compile(r"^[A-Z0-9]{10}$")
+
+
+def _required(label: str):
+    return lambda v: None if v.strip() else f"{label} is required"
+
+
+def _auth_types(target_type: str) -> list[str]:
+    config = TARGET_TYPE_AUTH_CONFIG.get(target_type)
+    if config is None:
+        return ["NONE"]
+    valid = getattr(config, "valid_auth_types", None)
+    if valid is None and isinstance(config, dict):
+        valid = config.get("validAuthTypes")
+    return list(valid or [])
+
+
+def _prompt_outbound_auth(target_type: str, credentials: list[dict[str, Any]]) -> dict[str, Any] | None:
+    types = _auth_types(target_type)
+    if not types:
+        return None
+    choice = interactive.select(
+        "Outbound authorization",
+        [
+            interactive.Choice(AUTH_OPTION_LABELS[t][0], t, AUTH_OPTION_LABELS[t][1])
+            for t in types
+            if t in AUTH_OPTION_LABELS
+        ],
+    )
+    if choice in ("NONE", "JWT_PASSTHROUGH", "GATEWAY_IAM_ROLE"):
+        return {"type": choice}
+    return {"type": choice, "credentialName": _pick_credential(choice, credentials)}
+
+
+def _pick_credential(auth_type: str, credentials: list[dict[str, Any]]) -> str:
+    vendor = "OAuthCredentialProvider" if auth_type == "OAUTH" else "ApiKeyCredentialProvider"
+    names = [c["name"] for c in credentials if c.get("authorizerType") == vendor and c.get("usage") != "inbound"]
+    create_new = object()
+    choice = (
+        interactive.select(
+            "Select a credential",
+            [interactive.Choice(n, n) for n in names] + [interactive.Choice("Create a new credential", create_new)],
+        )
+        if names
+        else create_new
+    )
+    if choice is not create_new:
+        return choice
+    # Inline creation, as upstream useCreateIdentity.
+    from agentcore.primitives.credential import PRIMITIVE as credential_primitive
+
+    created = credential_primitive.add_interactive(identity_type=vendor)
+    if created is None:
+        raise typer.Exit(130)
+    return created
+
+
+def run_add_gateway_target_wizard(primitive: GatewayTargetPrimitive) -> None:  # noqa: C901, PLR0912, PLR0915
+    project = primitive._project()
+    gateways = [g["name"] for g in project.get("agentCoreGateways", [])]
+    if not gateways:
+        typer.echo(
+            "No gateways found. Create a gateway first with 'agentcore add gateway' before adding a gateway target.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    existing_targets = {t["name"] for g in project.get("agentCoreGateways", []) for t in g.get("targets", [])}
+    credentials = project.get("credentials", [])
+
+    name = interactive.text(
+        "Name",
+        validate=lambda v: (
+            first_issue(ToolName, v) or ("Gateway target name already exists" if v in existing_targets else None)
+        ),
+    )
+    target_type = interactive.select(
+        "Select target type", [interactive.Choice(t, i, d) for i, t, d in TARGET_TYPE_OPTIONS]
+    )
+
+    def pick_gateway() -> str:
+        return (
+            gateways[0]
+            if len(gateways) == 1
+            else interactive.select("Select gateway", [interactive.Choice(g, g) for g in gateways])
+        )
+
+    lines: list[tuple[str, str]] = [("Name", name)]
+    create: Any
+
+    if target_type == "apiGateway":
+        rest_api_id = interactive.text("REST API ID", validate=_required("REST API ID"))
+        stage = interactive.text("Stage", default="prod", validate=_required("Stage"))
+        filter_path = interactive.text("Tool filter path", default="/*")
+        methods = interactive.text("Tool filter methods (comma-separated)", default="GET")
+        gateway = pick_gateway()
+        auth = interactive.select(
+            "Outbound authorization",
+            [
+                interactive.Choice("API Key", "API_KEY", "API key credential"),
+                interactive.Choice("No authorization", "NONE", "No outbound authentication"),
+            ],
+        )
+        config: dict[str, Any] = {
+            "name": name,
+            "gateway": gateway,
+            "restApiId": rest_api_id,
+            "stage": stage,
+            "toolFilters": [
+                {
+                    "filterPath": filter_path or "/*",
+                    "methods": [m.strip() for m in methods.split(",") if m.strip()] or ["GET"],
+                }
+            ],
+        }
+        if auth == "API_KEY":
+            config["outboundAuth"] = {"type": "API_KEY", "credentialName": _pick_credential("API_KEY", credentials)}
+        lines += [("Type", "API Gateway"), ("REST API", rest_api_id), ("Stage", stage), ("Gateway", gateway)]
+        create = lambda: primitive.create_api_gateway_target(config)  # noqa: E731
+    elif target_type in ("openApiSchema", "smithyModel"):
+        source = interactive.text("Schema file path (relative to project root) or S3 URI", validate=_required("Schema"))
+        schema_source = {"s3": {"uri": source}} if source.startswith("s3://") else {"inline": {"path": source}}
+        gateway = pick_gateway()
+        config = {"name": name, "targetType": target_type, "schemaSource": schema_source, "gateway": gateway}
+        if target_type == "openApiSchema":
+            auth = _prompt_outbound_auth("openApiSchema", credentials)
+            if auth and auth["type"] != "NONE":
+                config["outboundAuth"] = auth
+        lines += [("Type", target_type), ("Schema", source), ("Gateway", gateway)]
+        create = lambda: primitive.create_schema_based_gateway_target(config)  # noqa: E731
+    elif target_type == "lambdaFunctionArn":
+        lambda_arn = interactive.text("Lambda function ARN", validate=_required("Lambda ARN"))
+        tool_schema = interactive.text("Tool schema JSON file", validate=_required("Tool schema file"))
+        gateway = pick_gateway()
+        config = {"name": name, "gateway": gateway, "lambdaArn": lambda_arn, "toolSchemaFile": tool_schema}
+        lines += [("Type", "Lambda function"), ("Lambda ARN", lambda_arn), ("Gateway", gateway)]
+        create = lambda: primitive.create_lambda_function_arn_target(config)  # noqa: E731
+    elif target_type == "httpRuntime":
+        runtimes = [r["name"] for r in project.get("runtimes", [])]
+        if not runtimes:
+            typer.echo("No runtimes found. Add an agent first.", err=True)
+            raise typer.Exit(1)
+        runtime = interactive.select("Select runtime", [interactive.Choice(r, r) for r in runtimes])
+        endpoints = list((next(r for r in project["runtimes"] if r["name"] == runtime).get("endpoints") or {}).keys())
+        endpoint = None
+        if endpoints:
+            endpoint = interactive.select(
+                "Select runtime endpoint",
+                [interactive.Choice("DEFAULT", None), *[interactive.Choice(e, e) for e in endpoints]],
+            )
+        gateway = pick_gateway()
+        auth = _prompt_outbound_auth("httpRuntime", credentials)
+        config = {"name": name, "gateway": gateway, "runtime": runtime, "endpoint": endpoint, "outboundAuth": auth}
+        lines += [("Type", "HTTP Runtime"), ("Runtime", runtime), ("Gateway", gateway)]
+        create = lambda: primitive.create_http_runtime_target(config)  # noqa: E731
+    elif target_type == "connector":
+        kbs = [kb["name"] for kb in project.get("knowledgeBases", [])]
+        kb = interactive.select(
+            "Select a knowledge base",
+            [
+                *[interactive.Choice(k, k) for k in kbs],
+                interactive.Choice("Enter an existing KB ID manually...", ENTER_KB_ID_MANUALLY),
+            ],
+        )
+        if kb == ENTER_KB_ID_MANUALLY:
+            kb = interactive.text(
+                "Knowledge base ID (10 uppercase alphanumerics)",
+                validate=lambda v: None if _KB_ID.match(v) else "Must be a 10-character Bedrock KB id",
+            )
+        gateway = pick_gateway()
+        config = {"name": name, "gateway": gateway, "connectorId": "bedrock-knowledge-bases", "knowledgeBaseId": kb}
+        lines += [("Type", "Knowledge Base"), ("Knowledge Base", kb), ("Gateway", gateway)]
+        create = lambda: primitive.create_connector_gateway_target(config)  # noqa: E731
+    elif target_type == "webSearch":
+        gateway = pick_gateway()
+        excludes = interactive.text("Domains to exclude (comma-separated, optional)")
+        domains = [d.strip() for d in excludes.split(",") if d.strip()]
+        config = {"name": name, "gateway": gateway, **({"excludeDomains": domains} if domains else {})}
+        lines += [("Type", "Amazon Web Search"), ("Gateway", gateway)]
+        if domains:
+            lines.append(("Exclude Domains", ", ".join(domains)))
+        create = lambda: primitive.create_web_search_gateway_target(config)  # noqa: E731
+    elif target_type == "passthrough":
+        endpoint = interactive.text(
+            "HTTPS endpoint URL",
+            validate=lambda v: (
+                None if re.match(r"^https://[a-zA-Z0-9\-.]+(:[0-9]{1,5})?(/.*)?$", v) else "Must be a valid HTTPS URL"
+            ),
+        )
+        protocol = interactive.select(
+            "Passthrough protocol", list(("CUSTOM", *[p for p in PASSTHROUGH_PROTOCOL_TYPES if p != "CUSTOM"]))
+        )
+        stickiness = interactive.text("Stickiness identifier (optional)").strip() or None
+        timeout = None
+        if stickiness:
+            timeout_raw = interactive.text(
+                "Stickiness timeout in seconds (optional)",
+                validate=lambda v: (
+                    None if not v or (v.isdigit() and 1 <= int(v) <= 86400) else "Must be a number between 1 and 86400"
+                ),
+            )
+            timeout = int(timeout_raw) if timeout_raw else None
+        gateway = pick_gateway()
+        auth = _prompt_outbound_auth("passthrough", credentials)
+        if auth and auth["type"] == "GATEWAY_IAM_ROLE":
+            auth["service"] = interactive.text("SigV4 signing service", validate=_required("Signing service"))
+            region = interactive.text("SigV4 signing region (optional)").strip()
+            if region:
+                auth["region"] = region
+        config = {
+            "name": name,
+            "gateway": gateway,
+            "passthroughEndpoint": endpoint,
+            "protocolType": protocol,
+            "stickinessIdentifier": stickiness,
+            "stickinessTimeout": timeout,
+            "outboundAuth": auth,
+        }
+        lines += [("Type", "Passthrough"), ("Endpoint", endpoint), ("Protocol", protocol), ("Gateway", gateway)]
+        create = lambda: primitive.create_passthrough_target(config)  # noqa: E731
+    else:  # mcpServer
+        endpoint = interactive.text(
+            "MCP server endpoint URL",
+            validate=lambda v: (
+                None
+                if js_url_ok(v) and v.split(":", 1)[0].lower() in ("http", "https")
+                else "Endpoint must be a valid URL (e.g. https://example.com/mcp)"
+            ),
+        )
+        gateway = pick_gateway()
+        auth = _prompt_outbound_auth("mcpServer", credentials)
+        desc = f"Tool for {name}"
+        config = {
+            "name": name,
+            "description": desc,
+            "endpoint": endpoint,
+            "gateway": gateway,
+            "toolDefinition": {"name": name, "description": desc, "inputSchema": {"type": "object"}},
+        }
+        if auth and auth["type"] != "NONE":
+            config["outboundAuth"] = auth
+        lines += [("Type", "MCP Server endpoint"), ("Endpoint", endpoint), ("Gateway", gateway)]
+        create = lambda: primitive.create_external_gateway_target(config)  # noqa: E731
+
+    for label, value in lines:
+        typer.echo(f"  {label}: {value}")
+    if not interactive.confirm("Add this gateway target?", default=True):
+        return
+    try:
+        result = create()
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"Error: {get_error_message(exc)}", err=True)
+        raise typer.Exit(1) from None
+    typer.echo(f"Added gateway target '{result['toolName']}'")