agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/gateway_target.py

@@ -0,0 +1,988 @@
+"""Gateway target add/remove (port of src/cli/primitives/GatewayTargetPrimitive.ts).
+
+Target types: scaffolded MCP tools (Python, Lambda or AgentCore Runtime host), existing MCP server
+endpoints, API Gateway REST APIs, OpenAPI / Smithy schemas, Lambda function ARNs, HTTP runtimes,
+connectors (bedrock-knowledge-bases, web-search) and passthrough endpoints.
+
+The project spec is handled as its camelCase JSON form and validated on write by ``ConfigIO``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from dataclasses import dataclass, field
+from typing import Any
+
+import typer
+from pydantic import ValidationError as PydanticValidationError
+
+from agentcore.cli import interactive
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.run_command import run_cli_command
+from agentcore.lib.constants import APP_DIR, MCP_APP_SUBDIR
+from agentcore.lib.errors.types import ResourceNotFoundError, ValidationError, to_error
+from agentcore.lib.result import Err, Ok, serialize_result
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.lib.schemas.io.path_resolver import find_config_root, require_config_root
+from agentcore.lib.utils.json_format import to_json_string
+from agentcore.operations.connectors import translate_connector
+from agentcore.primitives._gateway_validation import validate_add_gateway_target_options
+from agentcore.primitives.base import (
+    PASSTHROUGH_PROTOCOL_TYPES,
+    SOURCE_CODE_NOTE,
+    BasePrimitive,
+    RemovableResource,
+    RemovalPreview,
+    SchemaChange,
+    emit_json,
+)
+from agentcore.schema import CONNECTOR_ID_VALUES, DEFAULT_PYTHON_VERSION, AgentCoreCliMcpDefs, ToolDefinition
+from agentcore.templates import get_template_tool_definitions, render_gateway_target_template
+
+MCP_DEFS_FILE = "mcp-defs.json"
+DEFAULT_NODE_VERSION = "NODE_20"
+DEFAULT_HANDLER = "handler.lambda_handler"
+
+TYPE_DESCRIPTION = (
+    "Target type (required): mcp-server, api-gateway, open-api-schema, smithy-model, lambda-function-arn, "
+    "http-runtime, connector, passthrough [non-interactive]"
+)
+
+HELP_EPILOG = """\b
+Target types and their options:
+
+  http-runtime — Route to an AgentCore runtime
+    --runtime <name>               Runtime from your project
+    --runtime-endpoint <name>      Endpoint / version alias (optional)
+
+  mcp-server — Connect to an MCP-compatible server
+    --endpoint <url>               Server endpoint URL
+    --host <host>                  Lambda or AgentCoreRuntime
+    --language <lang>              Python, TypeScript, or Other
+
+  api-gateway — Connect to an Amazon API Gateway REST API
+    --rest-api-id <id>             REST API ID
+    --stage <stage>                Deployment stage
+
+  open-api-schema / smithy-model — Auto-derive tools from a schema
+    --schema <path>                Schema file path or S3 URI
+    --schema-s3-account <id>       S3 bucket owner account ID
+
+  lambda-function-arn — Connect to an AWS Lambda function
+    --lambda-arn <arn>             Lambda function ARN
+    --tool-schema-file <path>      Tool schema JSON file
+
+  connector — Wire a managed AWS connector (bedrock-knowledge-bases, web-search)
+    --connector <id>               bedrock-knowledge-bases or web-search
+    --knowledge-base-id <id>       Project KB name or 10-char external KB id (for KB connectors)
+    --exclude-domains <list>       Comma-separated domains to exclude (for web-search connector)
+
+  passthrough — Route to an external HTTPS endpoint
+    --passthrough-endpoint <url>   HTTPS endpoint URL
+    --stickiness-identifier <expr> Session routing expression (optional)
+    --stickiness-timeout <seconds> Sticky session timeout in seconds (optional)
+
+  Auth (--outbound-auth <type>, --credential-name <name>) — valid types per target:
+    mcp-server                     oauth or none
+    lambda-function-arn            oauth or none
+    http-runtime                   oauth or none
+    open-api-schema                oauth or api-key (required)
+    api-gateway                    api-key or none
+    smithy-model                   none (uses gateway IAM role)
+    passthrough                    gateway-iam-role, oauth, or jwt-passthrough
+"""
+
+OUTBOUND_AUTH_MAP = {
+    "oauth": "OAUTH",
+    "api-key": "API_KEY",
+    "api_key": "API_KEY",
+    "none": "NONE",
+    "gateway_iam_role": "GATEWAY_IAM_ROLE",
+    "gateway-iam-role": "GATEWAY_IAM_ROLE",
+    "jwt_passthrough": "JWT_PASSTHROUGH",
+    "jwt-passthrough": "JWT_PASSTHROUGH",
+}
+
+
+@dataclass
+class AddGatewayTargetOptions:
+    name: str
+    language: str = "Python"
+    description: str | None = None
+    gateway: str | None = None
+    host: str | None = None
+
+
+@dataclass
+class GatewayTargetWizardState:
+    name: str
+    description: str
+    source_path: str
+    language: str
+    host: str
+    tool_definition: dict[str, Any]
+    gateway: str | None = None
+
+
+@dataclass
+class RemovableGatewayTarget(RemovableResource):
+    gateway_name: str = ""
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+def _mcp_fields(project: dict[str, Any]) -> dict[str, Any]:
+    spec = {"agentCoreGateways": project.get("agentCoreGateways", [])}
+    for key in ("mcpRuntimeTools", "unassignedTargets"):
+        if key in project:
+            spec[key] = project[key]
+    return spec
+
+
+def _csv(value: str | None) -> list[str] | None:
+    return [s.strip() for s in value.split(",")] if value is not None else None
+
+
+def _outbound_auth(auth_type: str | None, credential_name: str | None) -> dict[str, Any] | None:
+    """``{type, credentialName}`` as upstream's object spread (credentialName dropped when undefined)."""
+    if not auth_type:
+        return None
+    auth: dict[str, Any] = {"type": OUTBOUND_AUTH_MAP.get(auth_type.lower(), "NONE")}
+    if credential_name is not None:
+        auth["credentialName"] = credential_name
+    return auth
+
+
+class GatewayTargetPrimitive(BasePrimitive):
+    kind = "gateway-target"
+    label = "Gateway Target"
+
+    def _project(self) -> dict[str, Any]:
+        return to_jsonable(self.read_project_spec())
+
+    def _read_mcp_defs_or_empty(self) -> dict[str, Any]:
+        if self.config_io.config_exists("mcpDefs"):
+            return to_jsonable(self.config_io.read_mcp_defs())
+        return {"tools": {}}
+
+    # --- add (scaffolded tool) ----------------------------------------------------------
+
+    def add(self, options: AddGatewayTargetOptions) -> Ok[dict[str, Any]] | Err[Exception]:
+        try:
+            config = self._build_gateway_target_config(options)
+            result = self._create_tool_from_wizard(config)
+            return Ok({"toolName": result["toolName"], "sourcePath": result["projectPath"]})
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    @staticmethod
+    def _build_gateway_target_config(options: AddGatewayTargetOptions) -> GatewayTargetWizardState:
+        source_path = f"{APP_DIR}/{MCP_APP_SUBDIR}/{options.name}"
+        description = options.description if options.description is not None else f"Tool for {options.name}"
+        return GatewayTargetWizardState(
+            name=options.name,
+            description=description,
+            source_path=source_path,
+            language=options.language,
+            host=options.host or "AgentCoreRuntime",
+            tool_definition={"name": options.name, "description": description, "inputSchema": {"type": "object"}},
+            gateway=options.gateway,
+        )
+
+    def _create_tool_from_wizard(self, config: GatewayTargetWizardState) -> dict[str, str]:
+        if config.language not in ("Python", "TypeScript", "Other"):
+            raise ValueError(f'Gateway targets for language "{config.language}" are not yet supported.')
+
+        project = self._project()
+        if config.host == "Lambda":
+            tool_defs = [to_jsonable(t) for t in get_template_tool_definitions(config.name, "Lambda")]
+        else:
+            tool_defs = [config.tool_definition]
+        for tool_def in tool_defs:
+            try:
+                ToolDefinition.model_validate(tool_def)
+            except PydanticValidationError as exc:
+                from agentcore.primitives.knowledge_base import zod_error_message
+
+                raise ValueError(zod_error_message(exc)) from None
+
+        if not config.gateway:
+            raise ValueError("Gateway name is required for gateway targets.")
+        gateway = self._find_gateway(project, config.gateway)
+        self._check_target_name(gateway, config.name)
+        for tool_def in tool_defs:
+            for existing in gateway["targets"]:
+                if any(t["name"] == tool_def["name"] for t in existing.get("toolDefinitions") or []):
+                    raise ValueError(f'Tool "{tool_def["name"]}" already exists in gateway "{gateway["name"]}".')
+
+        if config.language == "Other":
+            raise ValueError('Language "Other" is not yet supported for gateway targets. Use Python or TypeScript.')
+
+        if config.host == "Lambda":
+            compute: dict[str, Any] = {
+                "host": "Lambda",
+                "implementation": {"path": config.source_path, "language": config.language, "handler": DEFAULT_HANDLER},
+            }
+            if config.language == "Python":
+                compute["pythonVersion"] = DEFAULT_PYTHON_VERSION
+            else:
+                compute["nodeVersion"] = DEFAULT_NODE_VERSION
+        else:
+            compute = {
+                "host": "AgentCoreRuntime",
+                "implementation": {"path": config.source_path, "language": "Python", "handler": "server.py:main"},
+                "runtime": {
+                    "artifact": "CodeZip",
+                    "pythonVersion": DEFAULT_PYTHON_VERSION,
+                    "name": config.name,
+                    "entrypoint": "server.py:main",
+                    "codeLocation": config.source_path,
+                    "networkMode": "PUBLIC",
+                },
+            }
+        gateway["targets"].append(
+            {
+                "name": config.name,
+                "targetType": "mcpServer" if config.host == "AgentCoreRuntime" else "lambda",
+                "toolDefinitions": tool_defs,
+                "compute": compute,
+            }
+        )
+        self.write_project_spec(project)
+
+        mcp_defs_path = os.path.join(require_config_root(), MCP_DEFS_FILE)
+        try:
+            mcp_defs = self._read_mcp_defs_file(mcp_defs_path)
+            for tool_def in tool_defs:
+                if tool_def["name"] in mcp_defs["tools"]:
+                    raise ValueError(f'Tool definition "{tool_def["name"]}" already exists in mcp-defs.json.')
+                mcp_defs["tools"][tool_def["name"]] = tool_def
+            os.makedirs(require_config_root(), exist_ok=True)
+            with open(mcp_defs_path, "w", encoding="utf-8") as fh:
+                fh.write(to_json_string(mcp_defs, 2))
+        except Exception as exc:  # noqa: BLE001
+            raise ValueError(f"MCP saved, but failed to update mcp-defs.json: {exc}") from None
+
+        project_root = os.path.dirname(require_config_root())
+        render_gateway_target_template(
+            config.name, os.path.join(project_root, config.source_path), config.language, config.host
+        )
+        return {"mcpDefsPath": mcp_defs_path, "toolName": config.name, "projectPath": config.source_path}
+
+    @staticmethod
+    def _read_mcp_defs_file(path: str) -> dict[str, Any]:
+        if not os.path.exists(path):
+            return {"tools": {}}
+        with open(path, encoding="utf-8") as fh:
+            parsed = json.load(fh)
+        try:
+            return to_jsonable(AgentCoreCliMcpDefs.model_validate(parsed))
+        except PydanticValidationError:
+            raise ValueError("Invalid mcp-defs.json. Fix it before adding a new gateway target.") from None
+
+    # --- add (registered, no code generation) -------------------------------------------
+
+    @staticmethod
+    def _find_gateway(project: dict[str, Any], name: str) -> dict[str, Any]:
+        gateway = next((g for g in project.get("agentCoreGateways", []) if g["name"] == name), None)
+        if gateway is None:
+            raise ValueError(f'Gateway "{name}" not found.')
+        gateway.setdefault("targets", [])
+        return gateway
+
+    @staticmethod
+    def _check_target_name(gateway: dict[str, Any], name: str) -> None:
+        if any(t["name"] == name for t in gateway["targets"]):
+            raise ValueError(f'Target "{name}" already exists in gateway "{gateway["name"]}".')
+
+    def _append_target(self, gateway_name: str, target: dict[str, Any], require_gateway_msg: bool = False) -> str:
+        project = self._project()
+        gateway = self._find_gateway(project, gateway_name)
+        self._check_target_name(gateway, target["name"])
+        gateway["targets"].append(target)
+        self.write_project_spec(project)
+        return target["name"]
+
+    def create_external_gateway_target(self, config: dict[str, Any]) -> dict[str, str]:
+        """Register an existing MCP server endpoint (``McpServerTargetConfig`` as camelCase dict)."""
+        target: dict[str, Any] = {
+            "name": config["name"],
+            "targetType": "mcpServer",
+            "endpoint": config["endpoint"],
+            "toolDefinitions": [config["toolDefinition"]],
+        }
+        if config.get("outboundAuth"):
+            target["outboundAuth"] = config["outboundAuth"]
+        if not config.get("gateway"):
+            raise ValueError(
+                "Gateway is required. A gateway target must be attached to a gateway. Create a gateway first with "
+                "'agentcore add gateway'."
+            )
+        return {"toolName": self._append_target(config["gateway"], target), "projectPath": ""}
+
+    def create_api_gateway_target(self, config: dict[str, Any]) -> dict[str, str]:
+        target: dict[str, Any] = {
+            "name": config["name"],
+            "targetType": "apiGateway",
+            "apiGateway": {
+                "restApiId": config["restApiId"],
+                "stage": config["stage"],
+                "apiGatewayToolConfiguration": {
+                    "toolFilters": config.get("toolFilters") or [{"filterPath": "/*", "methods": ["GET"]}]
+                },
+            },
+        }
+        if config.get("outboundAuth"):
+            target["outboundAuth"] = config["outboundAuth"]
+        return {"toolName": self._append_target(config["gateway"], target)}
+
+    def create_schema_based_gateway_target(self, config: dict[str, Any]) -> dict[str, str]:
+        target: dict[str, Any] = {
+            "name": config["name"],
+            "targetType": config["targetType"],
+            "schemaSource": config["schemaSource"],
+        }
+        if config.get("outboundAuth"):
+            target["outboundAuth"] = config["outboundAuth"]
+        return {"toolName": self._append_target(config["gateway"], target)}
+
+    def create_lambda_function_arn_target(self, config: dict[str, Any]) -> dict[str, str]:
+        target = {
+            "name": config["name"],
+            "targetType": "lambdaFunctionArn",
+            "lambdaFunctionArn": {"lambdaArn": config["lambdaArn"], "toolSchemaFile": config["toolSchemaFile"]},
+        }
+        return {"toolName": self._append_target(config["gateway"], target)}
+
+    def create_http_runtime_target(self, config: dict[str, Any]) -> dict[str, str]:
+        http_runtime: dict[str, Any] = {"runtime": config["runtime"]}
+        if config.get("endpoint"):
+            http_runtime["runtimeEndpoint"] = config["endpoint"]
+        target: dict[str, Any] = {"name": config["name"], "targetType": "httpRuntime", "httpRuntime": http_runtime}
+        auth = config.get("outboundAuth")
+        if auth and auth.get("type") != "NONE":
+            out: dict[str, Any] = {"type": auth["type"], "credentialName": auth.get("credentialName")}
+            if auth.get("scopes"):
+                out["scopes"] = auth["scopes"]
+            target["outboundAuth"] = {k: v for k, v in out.items() if v is not None}
+        return {"toolName": self._append_target(config["gateway"], target)}
+
+    def create_connector_gateway_target(self, config: dict[str, Any]) -> dict[str, str]:
+        """bedrock-knowledge-bases connector: ``knowledgeBaseId`` is a project KB name or a literal KB id."""
+        target = {
+            "name": config["name"],
+            "targetType": "connector",
+            "connectorId": "bedrock-knowledge-bases",
+            "configurations": translate_connector(
+                "bedrock-knowledge-bases", {"knowledgeBaseId": config["knowledgeBaseId"]}
+            ),
+        }
+        return {"toolName": self._append_target(config["gateway"], target)}
+
+    def create_passthrough_target(self, config: dict[str, Any]) -> dict[str, str]:
+        outbound_auth: dict[str, Any] | None = None
+        auth = config.get("outboundAuth")
+        if auth and auth.get("type") != "NONE":
+            if auth["type"] == "GATEWAY_IAM_ROLE":
+                outbound_auth = {"type": "GATEWAY_IAM_ROLE", "service": auth.get("service")}
+                if auth.get("region"):
+                    outbound_auth["region"] = auth["region"]
+            elif auth["type"] == "JWT_PASSTHROUGH":
+                outbound_auth = {"type": "JWT_PASSTHROUGH"}
+            else:
+                outbound_auth = {"type": auth["type"], "credentialName": auth.get("credentialName")}
+                if auth.get("scopes"):
+                    outbound_auth["scopes"] = auth["scopes"]
+            outbound_auth = {k: v for k, v in outbound_auth.items() if v is not None}
+
+        passthrough: dict[str, Any] = {
+            "endpoint": config["passthroughEndpoint"],
+            "protocolType": config.get("protocolType") or "CUSTOM",
+        }
+        if config.get("stickinessIdentifier"):
+            stickiness: dict[str, Any] = {"identifier": config["stickinessIdentifier"]}
+            if config.get("stickinessTimeout"):
+                stickiness["timeout"] = config["stickinessTimeout"]
+            passthrough["stickinessConfiguration"] = stickiness
+        target: dict[str, Any] = {"name": config["name"], "targetType": "passthrough", "passthrough": passthrough}
+        if outbound_auth:
+            target["outboundAuth"] = outbound_auth
+        return {"toolName": self._append_target(config["gateway"], target)}
+
+    def create_web_search_gateway_target(self, config: dict[str, Any]) -> dict[str, str]:
+        target = {
+            "name": config["name"],
+            "targetType": "connector",
+            "connectorId": "web-search",
+            "configurations": translate_connector("web-search", {"excludeDomains": config.get("excludeDomains")}),
+        }
+        return {"toolName": self._append_target(config["gateway"], target)}
+
+    # --- remove -------------------------------------------------------------------------
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [
+                RemovableGatewayTarget(
+                    t["name"], gateway_name=g["name"], extra={"type": "gateway-target", "gatewayName": g["name"]}
+                )
+                for g in self._project().get("agentCoreGateways", [])
+                for t in g.get("targets", [])
+            ]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_existing_tool_names(self) -> list[str]:
+        try:
+            return [
+                d["name"]
+                for g in self._project().get("agentCoreGateways", [])
+                for t in g.get("targets", [])
+                for d in t.get("toolDefinitions") or []
+            ]
+        except Exception:  # noqa: BLE001
+            return []
+
+    @staticmethod
+    def _compute_removed_tool_mcp_spec(mcp_spec: dict[str, Any], tool: RemovableGatewayTarget) -> dict[str, Any]:
+        return {
+            **mcp_spec,
+            "agentCoreGateways": [
+                g
+                if g["name"] != tool.gateway_name
+                else {**g, "targets": [t for t in g["targets"] if t["name"] != tool.name]}
+                for g in mcp_spec["agentCoreGateways"]
+            ],
+        }
+
+    @staticmethod
+    def _compute_removed_tool_mcp_defs(
+        mcp_spec: dict[str, Any], mcp_defs: dict[str, Any], tool: RemovableGatewayTarget
+    ) -> dict[str, Any]:
+        gateway = next((g for g in mcp_spec["agentCoreGateways"] if g["name"] == tool.gateway_name), None)
+        target = next((t for t in (gateway or {}).get("targets", []) if t["name"] == tool.name), None)
+        names = [d["name"] for d in (target or {}).get("toolDefinitions") or []]
+        tools = {k: v for k, v in mcp_defs.get("tools", {}).items() if k not in names}
+        return {**mcp_defs, "tools": tools}
+
+    @staticmethod
+    def _tool_path(target: dict[str, Any]) -> str | None:
+        implementation = (target.get("compute") or {}).get("implementation") or {}
+        return implementation.get("path")
+
+    def _find(self, name: str) -> RemovableGatewayTarget | None:
+        return next((t for t in self.get_removable() if t.name == name), None)  # type: ignore[return-value]
+
+    def remove(self, name: str) -> Ok[None] | Err[Exception]:
+        tool = self._find(name)
+        if tool is None:
+            return Err(ResourceNotFoundError(f'Gateway target "{name}" not found.'))
+        return self.remove_gateway_target(tool)
+
+    def remove_gateway_target(self, tool: RemovableGatewayTarget) -> Ok[None] | Err[Exception]:
+        try:
+            project = self._project()
+            mcp_spec = _mcp_fields(project)
+            mcp_defs = self._read_mcp_defs_or_empty()
+            project_root = self.config_io.get_project_root()
+
+            gateway = next((g for g in mcp_spec["agentCoreGateways"] if g["name"] == tool.gateway_name), None)
+            if gateway is None:
+                return Err(ResourceNotFoundError(f'Gateway "{tool.gateway_name}" not found.'))
+            target = next((t for t in gateway["targets"] if t["name"] == tool.name), None)
+            if target is None:
+                return Err(ResourceNotFoundError(f'Target "{tool.name}" not found in gateway "{tool.gateway_name}".'))
+            tool_path = self._tool_path(target)
+
+            new_defs = self._compute_removed_tool_mcp_defs(mcp_spec, mcp_defs, tool)
+            self.write_project_spec({**project, **self._compute_removed_tool_mcp_spec(mcp_spec, tool)})
+            self.config_io.write_mcp_defs(new_defs)
+
+            if tool_path:
+                tool_dir = os.path.join(project_root, tool_path)
+                if os.path.exists(tool_dir):
+                    shutil.rmtree(tool_dir, ignore_errors=True)
+            return Ok(None)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def preview_remove(self, name: str) -> RemovalPreview:
+        tool = self._find(name)
+        if tool is None:
+            raise Exception(f'Gateway target "{name}" not found.')
+        return self.preview_remove_gateway_target(tool)
+
+    def preview_remove_gateway_target(self, tool: RemovableGatewayTarget) -> RemovalPreview:
+        project = self._project()
+        mcp_spec = _mcp_fields(project)
+        mcp_defs = self._read_mcp_defs_or_empty()
+        project_root = self.config_io.get_project_root()
+
+        gateway = next((g for g in mcp_spec["agentCoreGateways"] if g["name"] == tool.gateway_name), None)
+        if gateway is None:
+            raise Exception(f'Gateway "{tool.gateway_name}" not found.')
+        target = next((t for t in gateway["targets"] if t["name"] == tool.name), None)
+        if target is None:
+            raise Exception(f'Target "{tool.name}" not found in gateway "{tool.gateway_name}".')
+
+        summary = [f"Removing gateway target: {tool.name} (from {tool.gateway_name})"]
+        directories: list[str] = []
+        tool_path = self._tool_path(target)
+        if tool_path:
+            tool_dir = os.path.join(project_root, tool_path)
+            if os.path.exists(tool_dir):
+                directories.append(tool_dir)
+                summary.append(f"Deleting directory: {tool_path}")
+        for tool_def in target.get("toolDefinitions") or []:
+            if tool_def["name"] in mcp_defs.get("tools", {}):
+                summary.append(f"Removing tool definition: {tool_def['name']}")
+
+        changes = [
+            SchemaChange(
+                "agentcore/agentcore.json", project, {**project, **self._compute_removed_tool_mcp_spec(mcp_spec, tool)}
+            )
+        ]
+        after_defs = self._compute_removed_tool_mcp_defs(mcp_spec, mcp_defs, tool)
+        if json.dumps(mcp_defs) != json.dumps(after_defs):
+            changes.append(SchemaChange("agentcore/mcp-defs.json", mcp_defs, after_defs))
+        return RemovalPreview(summary, directories, changes)
+
+    # --- CLI ----------------------------------------------------------------------------
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:  # noqa: C901
+        @add_app.command(
+            "gateway-target",
+            help="Add a target to a gateway for routing requests to backends",
+            epilog=HELP_EPILOG,
+        )
+        def add_command(  # noqa: PLR0913
+            name: str | None = typer.Option(None, "--name", help="Target name [non-interactive]"),
+            description: str | None = typer.Option(None, "--description", help="Target description [non-interactive]"),
+            gateway: str | None = typer.Option(
+                None, "--gateway", help="Gateway to attach this target to [non-interactive]"
+            ),
+            type_: str | None = typer.Option(None, "--type", help=TYPE_DESCRIPTION),
+            connector: str | None = typer.Option(
+                None,
+                "--connector",
+                help="Connector id (for connector type): bedrock-knowledge-bases or web-search [non-interactive]",
+            ),
+            knowledge_base_id: list[str] = typer.Option(
+                [],
+                "--knowledge-base-id",
+                help=(
+                    "KB reference for connector type — either a project KB name (entry in knowledgeBases[]) or a "
+                    "10-char Bedrock KB id for an external KB. [non-interactive]"
+                ),
+            ),
+            exclude_domains: list[str] = typer.Option(
+                [],
+                "--exclude-domains",
+                help="Comma-separated domains to exclude from results (for --connector web-search) [non-interactive]",
+            ),
+            endpoint: str | None = typer.Option(
+                None, "--endpoint", help="Server endpoint URL (for mcp-server type) [non-interactive]"
+            ),
+            language: str | None = typer.Option(
+                None, "--language", help="Language of target code: Python, TypeScript, Other [non-interactive]"
+            ),
+            host: str | None = typer.Option(
+                None, "--host", help="Where to run the target: Lambda or AgentCoreRuntime [non-interactive]"
+            ),
+            outbound_auth: str | None = typer.Option(
+                None,
+                "--outbound-auth",
+                help='Outbound auth type; valid values depend on --type (see "Auth" below) [non-interactive]',
+            ),
+            credential_name: str | None = typer.Option(
+                None, "--credential-name", help="Existing credential name for outbound auth [non-interactive]"
+            ),
+            oauth_client_id: str | None = typer.Option(
+                None,
+                "--oauth-client-id",
+                help="OAuth client ID — creates credential inline (for oauth auth) [non-interactive]",
+            ),
+            oauth_client_secret: str | None = typer.Option(
+                None,
+                "--oauth-client-secret",
+                help="OAuth client secret — creates credential inline (for oauth auth) [non-interactive]",
+            ),
+            oauth_discovery_url: str | None = typer.Option(
+                None,
+                "--oauth-discovery-url",
+                help="OAuth discovery URL — creates credential inline (for oauth auth) [non-interactive]",
+            ),
+            oauth_scopes: str | None = typer.Option(
+                None, "--oauth-scopes", help="OAuth scopes, comma-separated (for oauth auth) [non-interactive]"
+            ),
+            rest_api_id: str | None = typer.Option(
+                None, "--rest-api-id", help="REST API ID (for api-gateway type) [non-interactive]"
+            ),
+            stage: str | None = typer.Option(
+                None, "--stage", help="Deployment stage (for api-gateway type) [non-interactive]"
+            ),
+            tool_filter_path: str | None = typer.Option(
+                None, "--tool-filter-path", help="Tool filter path pattern, e.g. /pets/* [non-interactive]"
+            ),
+            tool_filter_methods: str | None = typer.Option(
+                None, "--tool-filter-methods", help="Comma-separated HTTP methods, e.g. GET,POST [non-interactive]"
+            ),
+            schema: str | None = typer.Option(
+                None,
+                "--schema",
+                help="Schema file path or S3 URI (for open-api-schema / smithy-model type) [non-interactive]",
+            ),
+            schema_s3_account: str | None = typer.Option(
+                None,
+                "--schema-s3-account",
+                help="S3 bucket owner account ID for cross-account access (for schema on S3) [non-interactive]",
+            ),
+            lambda_arn: str | None = typer.Option(
+                None, "--lambda-arn", help="Lambda function ARN (for lambda-function-arn type) [non-interactive]"
+            ),
+            tool_schema_file: str | None = typer.Option(
+                None,
+                "--tool-schema-file",
+                help="Tool schema JSON file path (for lambda-function-arn type) [non-interactive]",
+            ),
+            runtime: str | None = typer.Option(
+                None, "--runtime", help="Runtime from your project (for http-runtime type) [non-interactive]"
+            ),
+            runtime_endpoint: str | None = typer.Option(
+                None,
+                "--runtime-endpoint",
+                help="Runtime endpoint / version alias (for http-runtime type) [non-interactive]",
+            ),
+            passthrough_endpoint: str | None = typer.Option(
+                None, "--passthrough-endpoint", help="HTTPS endpoint URL for passthrough targets [non-interactive]"
+            ),
+            passthrough_protocol: str | None = typer.Option(
+                None,
+                "--passthrough-protocol",
+                help="Passthrough protocol: MCP | A2A | INFERENCE | CUSTOM (default: CUSTOM) [non-interactive]",
+            ),
+            stickiness_identifier: str | None = typer.Option(
+                None,
+                "--stickiness-identifier",
+                help="Session routing expression for passthrough targets [non-interactive]",
+            ),
+            stickiness_timeout: str | None = typer.Option(
+                None,
+                "--stickiness-timeout",
+                help="Sticky session timeout in seconds (1-86400) [non-interactive]",
+            ),
+            signing_service: str | None = typer.Option(
+                None,
+                "--signing-service",
+                help="SigV4 signing service name for passthrough GATEWAY_IAM_ROLE auth [non-interactive]",
+            ),
+            signing_region: str | None = typer.Option(
+                None,
+                "--signing-region",
+                help="SigV4 signing region for passthrough (defaults to project region) [non-interactive]",
+            ),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+
+            o: dict[str, Any] = {
+                "name": name,
+                "description": description,
+                "gateway": gateway,
+                "type": type_,
+                "connector": connector,
+                "knowledgeBaseId": list(knowledge_base_id or []),
+                "excludeDomains": exclude_domains[0] if exclude_domains else None,
+                "endpoint": endpoint,
+                "language": language,
+                "host": host,
+                "outboundAuthType": outbound_auth,
+                "credentialName": credential_name,
+                "oauthClientId": oauth_client_id,
+                "oauthClientSecret": oauth_client_secret,
+                "oauthDiscoveryUrl": oauth_discovery_url,
+                "oauthScopes": oauth_scopes,
+                "restApiId": rest_api_id,
+                "stage": stage,
+                "toolFilterPath": tool_filter_path,
+                "toolFilterMethods": tool_filter_methods,
+                "schema": schema,
+                "schemaS3Account": schema_s3_account,
+                "lambdaArn": lambda_arn,
+                "toolSchemaFile": tool_schema_file,
+                "runtime": runtime,
+                "runtimeEndpoint": runtime_endpoint,
+                "passthroughEndpoint": passthrough_endpoint,
+                "passthroughProtocol": passthrough_protocol,
+                "stickinessIdentifier": stickiness_identifier,
+                "stickinessTimeout": stickiness_timeout,
+                "signingService": signing_service,
+                "signingRegion": signing_region,
+            }
+            user_passed_any_flag = (
+                as_json or any(v not in (None, False, []) for v in o.values()) or bool(exclude_domains)
+            )
+            if not user_passed_any_flag:
+                try:
+                    interactive.require_tty()
+                    self.add_interactive()
+                except typer.Exit:
+                    raise
+                except Exception as exc:  # noqa: BLE001
+                    typer.echo(get_error_message(exc), err=True)
+                    raise typer.Exit(1) from None
+                raise typer.Exit(0)
+
+            run_cli_command(as_json, lambda: self._run_add(o, exclude_domains, as_json))
+
+        @remove_app.command("gateway-target", help="Remove a gateway target from the project")
+        def remove_command(
+            name: str | None = typer.Option(None, "--name", help="Name of resource to remove [non-interactive]"),
+            yes: bool = typer.Option(False, "-y", "--yes", help="Skip confirmation prompt [non-interactive]"),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            self._run_remove(name, yes, as_json)
+
+    def _run_add(self, o: dict[str, Any], exclude_domains_all: list[str], as_json: bool) -> None:  # noqa: C901, PLR0912, PLR0915
+        if len(exclude_domains_all) > 1:
+            raise ValidationError(
+                "--exclude-domains may only be specified once. Pass all domains as a single comma-separated value."
+            )
+        validation = validate_add_gateway_target_options(o)
+        if not validation.valid:
+            raise ValidationError(validation.error or "")
+
+        def done(tool_name: str, text: str | None = None, **extra: Any) -> None:
+            if as_json:
+                emit_json({"success": True, "toolName": tool_name, **extra})
+            else:
+                typer.echo(text or f"Added gateway target '{tool_name}'")
+
+        target_type = o["type"]
+        auth = _outbound_auth(o["outboundAuthType"], o["credentialName"])
+
+        if target_type == "apiGateway":
+            config: dict[str, Any] = {
+                "name": o["name"],
+                "gateway": o["gateway"],
+                "restApiId": o["restApiId"],
+                "stage": o["stage"],
+            }
+            if o["toolFilterPath"]:
+                config["toolFilters"] = [
+                    {"filterPath": o["toolFilterPath"], "methods": _csv(o["toolFilterMethods"]) or ["GET"]}
+                ]
+            if auth:
+                config["outboundAuth"] = auth
+            done(self.create_api_gateway_target(config)["toolName"])
+            return
+
+        if target_type in ("openApiSchema", "smithyModel") and o["schema"]:
+            schema = o["schema"]
+            if schema.startswith("s3://"):
+                s3: dict[str, Any] = {"uri": schema}
+                if o["schemaS3Account"]:
+                    s3["bucketOwnerAccountId"] = o["schemaS3Account"]
+                schema_source: dict[str, Any] = {"s3": s3}
+            else:
+                schema_source = {"inline": {"path": schema}}
+            config = {
+                "name": o["name"],
+                "targetType": target_type,
+                "schemaSource": schema_source,
+                "gateway": o["gateway"],
+            }
+            if auth:
+                config["outboundAuth"] = auth
+            done(self.create_schema_based_gateway_target(config)["toolName"])
+            return
+
+        if target_type == "lambdaFunctionArn":
+            config = {
+                "name": o["name"],
+                "gateway": o["gateway"],
+                "lambdaArn": o["lambdaArn"],
+                "toolSchemaFile": o["toolSchemaFile"],
+            }
+            done(self.create_lambda_function_arn_target(config)["toolName"])
+            return
+
+        if target_type == "httpRuntime":
+            config = {
+                "name": o["name"],
+                "gateway": o["gateway"],
+                "runtime": o["runtime"],
+                "endpoint": o["runtimeEndpoint"] if o["runtimeEndpoint"] is not None else o["endpoint"],
+            }
+            if o["outboundAuthType"] and o["outboundAuthType"] != "NONE":
+                config["outboundAuth"] = {
+                    "type": OUTBOUND_AUTH_MAP.get(o["outboundAuthType"].lower(), "NONE"),
+                    "credentialName": o["credentialName"],
+                    "scopes": _csv(o["oauthScopes"]),
+                }
+            done(self.create_http_runtime_target(config)["toolName"])
+            return
+
+        if target_type == "connector":
+            valid = ", ".join(CONNECTOR_ID_VALUES)
+            if not o["connector"]:
+                raise ValidationError(f"--connector is required for connector targets ({valid}).")
+            if o["connector"] not in CONNECTOR_ID_VALUES:
+                raise ValidationError(f"Unknown --connector value '{o['connector']}'. Valid: {valid}.")
+            if o["connector"] == "web-search":
+                excludes = (
+                    [d.strip() for d in o["excludeDomains"].split(",") if d.strip()]
+                    if isinstance(o["excludeDomains"], str)
+                    else None
+                )
+                config = {"name": o["name"], "gateway": o["gateway"]}
+                if excludes:
+                    config["excludeDomains"] = excludes
+                tool_name = self.create_web_search_gateway_target(config)["toolName"]
+                suffix = f" (excludeDomains={','.join(excludes)})" if excludes else ""
+                done(tool_name, f"Added web-search gateway target '{tool_name}' on '{o['gateway']}'{suffix}")
+                return
+
+            kb_refs = o["knowledgeBaseId"] or []
+            if not kb_refs:
+                raise ValidationError(f"--knowledge-base-id is required for --connector {o['connector']}.")
+            if len(kb_refs) > 1:
+                raise ValidationError(
+                    "--knowledge-base-id may only be specified once for --connector bedrock-knowledge-bases."
+                )
+            resolved_name = o["name"] or f"kb-{o['gateway']}-{kb_refs[0]}".replace("_", "-")[:128]
+            config = {
+                "name": resolved_name,
+                "gateway": o["gateway"],
+                "connectorId": o["connector"],
+                "knowledgeBaseId": kb_refs[0],
+            }
+            tool_name = self.create_connector_gateway_target(config)["toolName"]
+            done(
+                tool_name,
+                f"Added connector gateway target '{tool_name}' on '{o['gateway']}' → {o['connector']} (KB {kb_refs[0]})",
+            )
+            return
+
+        if target_type == "passthrough":
+            if not o["passthroughEndpoint"]:
+                raise ValidationError("--passthrough-endpoint is required for passthrough type")
+            from agentcore.primitives._gateway_validation import js_parse_int
+
+            timeout = js_parse_int(o["stickinessTimeout"]) if o["stickinessTimeout"] else None
+            raw_protocol = o["passthroughProtocol"]
+            protocol = raw_protocol.upper() if raw_protocol is not None else "CUSTOM"
+            if protocol not in PASSTHROUGH_PROTOCOL_TYPES:
+                raise ValidationError(
+                    f'Invalid --passthrough-protocol "{raw_protocol}". Must be one of: '
+                    f"{', '.join(PASSTHROUGH_PROTOCOL_TYPES)}"
+                )
+            passthrough_auth: dict[str, Any] | None = None
+            if o["outboundAuthType"]:
+                mapped = OUTBOUND_AUTH_MAP.get(o["outboundAuthType"].lower(), "NONE")
+                if mapped == "GATEWAY_IAM_ROLE":
+                    if not o["signingService"]:
+                        raise ValidationError(
+                            "--signing-service is required when --outbound-auth is GATEWAY_IAM_ROLE for passthrough "
+                            "targets"
+                        )
+                    passthrough_auth = {"type": "GATEWAY_IAM_ROLE", "service": o["signingService"]}
+                    if o["signingRegion"]:
+                        passthrough_auth["region"] = o["signingRegion"]
+                elif mapped == "JWT_PASSTHROUGH":
+                    passthrough_auth = {"type": "JWT_PASSTHROUGH"}
+                elif mapped != "NONE":
+                    passthrough_auth = {
+                        "type": mapped,
+                        "credentialName": o["credentialName"],
+                        "scopes": _csv(o["oauthScopes"]),
+                    }
+            config = {
+                "name": o["name"],
+                "gateway": o["gateway"],
+                "passthroughEndpoint": o["passthroughEndpoint"],
+                "protocolType": protocol,
+                "stickinessIdentifier": o["stickinessIdentifier"],
+                "stickinessTimeout": timeout,
+                "outboundAuth": passthrough_auth,
+            }
+            done(self.create_passthrough_target(config)["toolName"])
+            return
+
+        if target_type == "mcpServer" and o["endpoint"]:
+            desc = o["description"] if o["description"] is not None else f"Tool for {o['name']}"
+            config = {
+                "name": o["name"],
+                "description": desc,
+                "endpoint": o["endpoint"],
+                "gateway": o["gateway"],
+                "toolDefinition": {"name": o["name"], "description": desc, "inputSchema": {"type": "object"}},
+            }
+            if auth:
+                config["outboundAuth"] = auth
+            result = self.create_external_gateway_target(config)
+            done(result["toolName"], sourcePath=result["projectPath"] or None)
+            return
+
+        result = self.add(
+            AddGatewayTargetOptions(
+                name=o["name"],
+                description=o["description"],
+                language=o["language"] or "Python",
+                gateway=o["gateway"],
+                host=o["host"],
+            )
+        )
+        if not result.success:
+            raise result.error
+        if as_json:
+            emit_json(serialize_result(result))
+        else:
+            typer.echo(f"Added gateway target '{result.value['toolName']}'")
+            if result.value["sourcePath"]:
+                typer.echo(f"Tool code: {result.value['sourcePath']}")
+
+    def _run_remove(self, name: str | None, yes: bool, as_json: bool) -> None:
+        try:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+            if name or yes or as_json:
+                if not name:
+                    emit_json({"success": False, "error": "--name is required"})
+                    raise typer.Exit(1)
+                result = self.remove(name)
+                emit_json(
+                    {
+                        "success": result.success,
+                        "resourceType": self.kind,
+                        "resourceName": name,
+                        "message": f"Removed gateway target '{name}'" if result.success else None,
+                        "note": SOURCE_CODE_NOTE if result.success else None,
+                        "error": None if result.success else get_error_message(result.error),
+                    }
+                )
+                raise typer.Exit(0 if result.success else 1)
+            interactive.require_tty()
+            self.remove_interactive()
+        except typer.Exit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            if as_json:
+                emit_json({"success": False, "error": get_error_message(exc)})
+            else:
+                typer.echo(f"Error: {get_error_message(exc)}", err=True)
+            raise typer.Exit(1) from None
+
+    # --- interactive (port of tui/screens/mcp AddGatewayTargetScreen + Flow) -----------------
+
+    def add_interactive(self) -> None:
+        from agentcore.primitives._gateway_target_wizard import run_add_gateway_target_wizard
+
+        run_add_gateway_target_wizard(self)
+
+
+PRIMITIVE = GatewayTargetPrimitive()