agentcore-cli 0.31.1__py3-none-any.whl

agentcore/aws/agentcore_control.py

@@ -0,0 +1,994 @@
+"""AgentCore control-plane reads (port of ``agentcore-control.ts``).
+
+Results are TypedDicts keyed like upstream's return objects (camelCase); optional fields that
+upstream leaves ``undefined`` are omitted. Timestamps are ``datetime`` (upstream: ``Date``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any, Literal, NotRequired, TypedDict, TypeVar
+
+from botocore.client import BaseClient
+
+from agentcore.aws._aws_errors import aws_error_name, get_error_message
+from agentcore.aws._util import drop_none, warn
+from agentcore.aws.account import create_aws_client
+from agentcore.aws.stage_endpoint import control_plane_endpoint, is_prerelease_stage
+from agentcore.lib.utils.json_format import to_json_string
+
+T = TypeVar("T")
+
+PAGE_SIZE = 100
+
+
+def create_control_client(region: str) -> BaseClient:
+    """``bedrock-agentcore-control`` client; honours ``AGENTCORE_STAGE`` for pre-release endpoints.
+
+    Create one per logical operation and reuse it for related calls.
+    """
+    endpoint = control_plane_endpoint(region) if is_prerelease_stage() else None
+    return create_aws_client("bedrock-agentcore-control", region, endpoint_url=endpoint)
+
+
+def _paginate_all(
+    region: str, fetch_page: Callable[[dict[str, Any], BaseClient], tuple[list[T], str | None]]
+) -> list[T]:
+    """Collect every item across pages, reusing a single client."""
+    client = create_control_client(region)
+    items: list[T] = []
+    next_token: str | None = None
+    while True:
+        page, next_token = fetch_page({"region": region, "max_results": PAGE_SIZE, "next_token": next_token}, client)
+        items.extend(page)
+        if not next_token:
+            return items
+
+
+def _list_params(max_results: int | None, next_token: str | None, **extra: Any) -> dict[str, Any]:
+    return drop_none({**extra, "maxResults": max_results, "nextToken": next_token})
+
+
+def _fetch_tags(client: BaseClient, resource_arn: str | None, resource_label: str) -> dict[str, str] | None:
+    """Resource tags, or ``None`` when the ARN is missing, there are no tags, or the call fails."""
+    if not resource_arn:
+        return None
+    try:
+        tags = client.list_tags_for_resource(resourceArn=resource_arn).get("tags")
+        if tags:
+            return tags
+    except Exception as exc:  # noqa: BLE001 - tags are best-effort
+        warn(f"Warning: Failed to fetch tags for {resource_label}: {get_error_message(exc)}")
+    return None
+
+
+def resolve_vpc_id_from_subnets(subnet_ids: list[str], region: str) -> str:
+    """VPC that ``subnet_ids`` belong to, via ``ec2:DescribeSubnets`` (port of ``vpc-utils.resolveVpcIdFromSubnets``).
+
+    All subnets must resolve to one VPC; DescribeSubnets does not guarantee response order, so the
+    first result is never trusted blindly.
+    """
+    joined = ", ".join(subnet_ids)
+    try:
+        subnets = create_aws_client("ec2", region).describe_subnets(SubnetIds=subnet_ids).get("Subnets") or []
+    except Exception as exc:
+        raise RuntimeError(
+            f"Failed to resolve VPC ID from subnets [{joined}]: ec2:DescribeSubnets permission is required. "
+            f"Cause: {get_error_message(exc)}"
+        ) from exc
+
+    vpc_ids = list(dict.fromkeys(s["VpcId"] for s in subnets if s.get("VpcId")))
+    if not vpc_ids:
+        raise RuntimeError(
+            f"ec2:DescribeSubnets returned no VPC ID for subnets [{joined}]. Verify the subnets exist and "
+            "ec2:DescribeSubnets permission is granted."
+        )
+    if len(vpc_ids) > 1:
+        raise RuntimeError(
+            f"Subnets [{joined}] span multiple VPCs ({', '.join(vpc_ids)}). "
+            "All subnets for a container build must be in the same VPC."
+        )
+    return vpc_ids[0]
+
+
+# ============================================================================
+# Agent runtime status
+# ============================================================================
+
+
+class AgentRuntimeStatusResult(TypedDict):
+    runtimeId: str
+    status: str
+
+
+def get_agent_runtime_status(*, region: str, runtime_id: str) -> AgentRuntimeStatusResult:
+    client = create_control_client(region)
+    response = client.get_agent_runtime(agentRuntimeId=runtime_id)
+    status = response.get("status")
+    if not status:
+        raise RuntimeError(f"No status returned for runtime {runtime_id}")
+    return {"runtimeId": runtime_id, "status": status}
+
+
+# ============================================================================
+# Agent runtimes — list & get
+# ============================================================================
+
+
+class AgentRuntimeSummary(TypedDict):
+    agentRuntimeId: str
+    agentRuntimeArn: str
+    agentRuntimeName: str
+    description: str
+    status: str
+    lastUpdatedAt: NotRequired[datetime]
+
+
+class ListAgentRuntimesResult(TypedDict):
+    runtimes: list[AgentRuntimeSummary]
+    nextToken: NotRequired[str]
+
+
+def list_agent_runtimes(
+    *, region: str, max_results: int | None = None, next_token: str | None = None, client: BaseClient | None = None
+) -> ListAgentRuntimesResult:
+    """One page of AgentCore runtimes."""
+    client = client or create_control_client(region)
+    response = client.list_agent_runtimes(**_list_params(max_results, next_token))
+    runtimes: list[AgentRuntimeSummary] = [
+        drop_none(  # type: ignore[misc]
+            {
+                "agentRuntimeId": r.get("agentRuntimeId") or "",
+                "agentRuntimeArn": r.get("agentRuntimeArn") or "",
+                "agentRuntimeName": r.get("agentRuntimeName") or "",
+                "description": r.get("description") or "",
+                "status": r.get("status") or "UNKNOWN",
+                "lastUpdatedAt": r.get("lastUpdatedAt"),
+            }
+        )
+        for r in response.get("agentRuntimes") or []
+    ]
+    return drop_none({"runtimes": runtimes, "nextToken": response.get("nextToken")})  # type: ignore[return-value]
+
+
+def list_all_agent_runtimes(*, region: str) -> list[AgentRuntimeSummary]:
+    def page(opts: dict[str, Any], client: BaseClient) -> tuple[list[AgentRuntimeSummary], str | None]:
+        result = list_agent_runtimes(**opts, client=client)
+        return result["runtimes"], result.get("nextToken")
+
+    return _paginate_all(region, page)
+
+
+class CustomJwtAuthorizerDetail(TypedDict):
+    discoveryUrl: str
+    allowedAudience: NotRequired[list[str]]
+    allowedClients: NotRequired[list[str]]
+    allowedScopes: NotRequired[list[str]]
+
+
+class AgentRuntimeDetail(TypedDict):
+    agentRuntimeId: str
+    agentRuntimeArn: str
+    agentRuntimeName: str
+    status: str
+    description: NotRequired[str]
+    roleArn: str
+    networkMode: str
+    networkConfig: NotRequired[dict[str, Any]]
+    """Schema ``NetworkConfig`` shape: ``{subnets, securityGroups, vpcId?}``."""
+    protocol: str
+    runtimeVersion: NotRequired[str]
+    entryPoint: NotRequired[list[str]]
+    build: Literal["CodeZip", "Container"]
+    authorizerType: NotRequired[str]
+    authorizerConfiguration: NotRequired[dict[str, CustomJwtAuthorizerDetail]]
+    environmentVariables: NotRequired[dict[str, str]]
+    tags: NotRequired[dict[str, str]]
+    lifecycleConfiguration: NotRequired[dict[str, int]]
+    requestHeaderAllowlist: NotRequired[list[str]]
+
+
+def _jwt_authorizer(jwt: dict[str, Any]) -> CustomJwtAuthorizerDetail:
+    return drop_none(  # type: ignore[return-value]
+        {
+            "discoveryUrl": jwt.get("discoveryUrl") or "",
+            "allowedAudience": jwt.get("allowedAudience"),
+            "allowedClients": jwt.get("allowedClients"),
+            "allowedScopes": jwt.get("allowedScopes"),
+        }
+    )
+
+
+def get_agent_runtime_detail(*, region: str, runtime_id: str) -> AgentRuntimeDetail:
+    """Full details of a runtime, including tags."""
+    client = create_control_client(region)
+    response = client.get_agent_runtime(agentRuntimeId=runtime_id)
+
+    artifact = response.get("agentRuntimeArtifact") or {}
+    is_container = bool(artifact.get("containerConfiguration"))
+    code_config = artifact.get("codeConfiguration") or {}
+
+    network = response.get("networkConfiguration") or {}
+    network_mode = network.get("networkMode") or "PUBLIC"
+    network_config: dict[str, Any] | None = None
+    if network_mode == "VPC" and network.get("networkModeConfig"):
+        mode_config = network["networkModeConfig"]
+        subnets = mode_config.get("subnets") or []
+        security_groups = mode_config.get("securityGroups") or []
+        # Only Container builds need the VPC ID (CodeBuild can't infer it); skipping it for CodeZip
+        # avoids an ec2:DescribeSubnets call and its IAM requirement.
+        vpc_id = resolve_vpc_id_from_subnets(subnets, region) if is_container and subnets else None
+        network_config = drop_none({"subnets": subnets, "securityGroups": security_groups, "vpcId": vpc_id})
+
+    authorizer_type: str | None = None
+    authorizer_configuration: dict[str, Any] | None = None
+    jwt = (response.get("authorizerConfiguration") or {}).get("customJWTAuthorizer")
+    if jwt:
+        authorizer_type = "CUSTOM_JWT"
+        authorizer_configuration = {"customJwtAuthorizer": _jwt_authorizer(jwt)}
+
+    env_vars = response.get("environmentVariables") or None
+
+    lifecycle = response.get("lifecycleConfiguration")
+    lifecycle_configuration = (
+        drop_none(
+            {
+                "idleRuntimeSessionTimeout": lifecycle.get("idleRuntimeSessionTimeout"),
+                "maxLifetime": lifecycle.get("maxLifetime"),
+            }
+        )
+        if lifecycle is not None
+        else None
+    )
+
+    allowlist = (response.get("requestHeaderConfiguration") or {}).get("requestHeaderAllowlist") or None
+
+    tags = _fetch_tags(client, response.get("agentRuntimeArn"), "runtime")
+
+    return drop_none(  # type: ignore[return-value]
+        {
+            "agentRuntimeId": response.get("agentRuntimeId") or "",
+            "agentRuntimeArn": response.get("agentRuntimeArn") or "",
+            "agentRuntimeName": response.get("agentRuntimeName") or "",
+            "status": response.get("status") or "UNKNOWN",
+            "description": response.get("description"),
+            "roleArn": response.get("roleArn") or "",
+            "networkMode": network_mode,
+            "networkConfig": network_config,
+            "protocol": (response.get("protocolConfiguration") or {}).get("serverProtocol") or "HTTP",
+            "runtimeVersion": code_config.get("runtime"),
+            "entryPoint": code_config.get("entryPoint"),
+            "build": "Container" if is_container else "CodeZip",
+            "authorizerType": authorizer_type,
+            "authorizerConfiguration": authorizer_configuration,
+            "environmentVariables": env_vars,
+            "tags": tags,
+            "lifecycleConfiguration": lifecycle_configuration,
+            "requestHeaderAllowlist": allowlist,
+        }
+    )
+
+
+# ============================================================================
+# Memories — list & get
+# ============================================================================
+
+
+class MemorySummary(TypedDict):
+    memoryId: str
+    memoryArn: str
+    status: str
+    createdAt: NotRequired[datetime]
+    updatedAt: NotRequired[datetime]
+
+
+class ListMemoriesResult(TypedDict):
+    memories: list[MemorySummary]
+    nextToken: NotRequired[str]
+
+
+def list_memories(
+    *, region: str, max_results: int | None = None, next_token: str | None = None, client: BaseClient | None = None
+) -> ListMemoriesResult:
+    client = client or create_control_client(region)
+    response = client.list_memories(**_list_params(max_results, next_token))
+    memories: list[MemorySummary] = [
+        drop_none(  # type: ignore[misc]
+            {
+                "memoryId": m.get("id") or "",
+                "memoryArn": m.get("arn") or "",
+                "status": m.get("status") or "UNKNOWN",
+                "createdAt": m.get("createdAt"),
+                "updatedAt": m.get("updatedAt"),
+            }
+        )
+        for m in response.get("memories") or []
+    ]
+    return drop_none({"memories": memories, "nextToken": response.get("nextToken")})  # type: ignore[return-value]
+
+
+def list_all_memories(*, region: str) -> list[MemorySummary]:
+    def page(opts: dict[str, Any], client: BaseClient) -> tuple[list[MemorySummary], str | None]:
+        result = list_memories(**opts, client=client)
+        return result["memories"], result.get("nextToken")
+
+    return _paginate_all(region, page)
+
+
+class MemoryStrategyDetail(TypedDict):
+    type: str
+    name: NotRequired[str]
+    description: NotRequired[str]
+    namespaceTemplates: NotRequired[list[str]]
+    reflectionNamespaceTemplates: NotRequired[list[str]]
+
+
+class MemoryIndexedKey(TypedDict):
+    key: str
+    type: str
+
+
+class MemoryDetail(TypedDict):
+    memoryId: str
+    memoryArn: str
+    name: str
+    status: str
+    description: NotRequired[str]
+    eventExpiryDuration: int
+    strategies: list[MemoryStrategyDetail]
+    indexedKeys: NotRequired[list[MemoryIndexedKey]]
+    tags: NotRequired[dict[str, str]]
+    encryptionKeyArn: NotRequired[str]
+    executionRoleArn: NotRequired[str]
+
+
+def get_memory_detail(*, region: str, memory_id: str) -> MemoryDetail:
+    """Full details of a memory, including strategies, indexed keys and tags."""
+    client = create_control_client(region)
+    memory = client.get_memory(memoryId=memory_id).get("memory")
+    if not memory:
+        raise RuntimeError(f"No memory found for ID {memory_id}")
+    for required in ("id", "arn", "name"):
+        if not memory.get(required):
+            raise RuntimeError(f"Memory {memory_id} is missing required field: {required}")
+    if memory.get("eventExpiryDuration") is None:
+        raise RuntimeError(f"Memory {memory_id} is missing required field: eventExpiryDuration")
+
+    tags = _fetch_tags(client, memory["arn"], "memory")
+
+    indexed_keys: list[MemoryIndexedKey] = []
+    for k in memory.get("indexedKeys") or []:
+        if not k.get("key") or not k.get("type"):
+            warn(f"Warning: Skipping malformed indexed key from API response: {to_json_string(k, indent=None)}")
+            continue
+        indexed_keys.append({"key": k["key"], "type": k["type"]})
+
+    strategies: list[MemoryStrategyDetail] = []
+    for s in memory.get("strategies") or []:
+        if not s.get("type"):
+            raise RuntimeError(f"Memory {memory_id} has a strategy with missing required field: type")
+        # Prefer namespaceTemplates; fall back to the deprecated namespaces field.
+        namespace_templates = s.get("namespaceTemplates")
+        if namespace_templates is None:
+            namespace_templates = s.get("namespaces")
+        reflection = ((s.get("configuration") or {}).get("reflection") or {}).get("episodicReflectionConfiguration")
+        reflection = reflection or {}
+        reflection_templates = reflection.get("namespaceTemplates")
+        if reflection_templates is None:
+            reflection_templates = reflection.get("namespaces")
+        strategy: dict[str, Any] = drop_none(
+            {"type": s["type"], "name": s.get("name"), "description": s.get("description")}
+        )
+        if namespace_templates:
+            strategy["namespaceTemplates"] = namespace_templates
+        if reflection_templates:
+            strategy["reflectionNamespaceTemplates"] = reflection_templates
+        strategies.append(strategy)  # type: ignore[arg-type]
+
+    detail: dict[str, Any] = drop_none(
+        {
+            "memoryId": memory["id"],
+            "memoryArn": memory["arn"],
+            "name": memory["name"],
+            "status": memory.get("status") or "UNKNOWN",
+            "description": memory.get("description"),
+            "eventExpiryDuration": memory["eventExpiryDuration"],
+            "tags": tags,
+            "encryptionKeyArn": memory.get("encryptionKeyArn"),
+            "executionRoleArn": memory.get("memoryExecutionRoleArn"),
+        }
+    )
+    if indexed_keys:
+        detail["indexedKeys"] = indexed_keys
+    detail["strategies"] = strategies
+    return detail  # type: ignore[return-value]
+
+
+# ============================================================================
+# Evaluators
+# ============================================================================
+
+
+class GetEvaluatorLlmConfig(TypedDict):
+    modelProvider: NotRequired[str]
+    model: str
+    instructions: str
+    ratingScale: dict[str, list[dict[str, Any]]]
+    """``{"numerical": [{value, label, definition}]}`` or ``{"categorical": [{label, definition}]}``."""
+
+
+class GetEvaluatorResult(TypedDict):
+    evaluatorId: str
+    evaluatorArn: str
+    evaluatorName: str
+    level: str
+    status: str
+    description: NotRequired[str]
+    evaluatorConfig: NotRequired[dict[str, Any]]
+    """``{"llmAsAJudge": GetEvaluatorLlmConfig}`` or ``{"codeBased": {"lambdaArn": str}}``."""
+    kmsKeyArn: NotRequired[str]
+    tags: NotRequired[dict[str, str]]
+
+
+def _map_evaluator_config(config: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not config:
+        return None
+    llm = config.get("llmAsAJudge")
+    if llm:
+        # Flatten the model-config union into the CLI's provider + model fields.
+        model_provider: str | None = None
+        model = ""
+        model_config = llm.get("modelConfig") or {}
+        if model_config.get("bedrockEvaluatorModelConfig"):
+            model = model_config["bedrockEvaluatorModelConfig"].get("modelId") or ""
+        elif model_config.get("responsesEvaluatorModelConfig"):
+            model_provider = "OpenResponses"
+            model = model_config["responsesEvaluatorModelConfig"].get("modelId") or ""
+
+        rating_scale: dict[str, list[dict[str, Any]]] = {}
+        scale = llm.get("ratingScale") or {}
+        if scale.get("numerical"):
+            rating_scale["numerical"] = [
+                {"value": n.get("value") or 0, "label": n.get("label") or "", "definition": n.get("definition") or ""}
+                for n in scale["numerical"]
+            ]
+        elif scale.get("categorical"):
+            rating_scale["categorical"] = [
+                {"label": c.get("label") or "", "definition": c.get("definition") or ""} for c in scale["categorical"]
+            ]
+
+        llm_config: dict[str, Any] = {}
+        if model_provider:
+            llm_config["modelProvider"] = model_provider
+        llm_config.update({"model": model, "instructions": llm.get("instructions") or "", "ratingScale": rating_scale})
+        return {"llmAsAJudge": llm_config}
+
+    code_based = config.get("codeBased")
+    if code_based and code_based.get("lambdaConfig"):
+        return {"codeBased": {"lambdaArn": code_based["lambdaConfig"].get("lambdaArn") or ""}}
+    return None
+
+
+def get_evaluator(*, region: str, evaluator_id: str) -> GetEvaluatorResult:
+    client = create_control_client(region)
+    try:
+        response = client.get_evaluator(evaluatorId=evaluator_id)
+    except Exception as exc:
+        if aws_error_name(exc) in ("ResourceNotFoundException", "ValidationException"):
+            raise RuntimeError(
+                f'Evaluator "{evaluator_id}" not found. Verify the evaluator ID or ARN is correct.'
+            ) from exc
+        raise
+
+    if not response.get("evaluatorId"):
+        raise RuntimeError(f"No evaluator found for ID {evaluator_id}")
+
+    evaluator_config = _map_evaluator_config(response.get("evaluatorConfig"))
+    tags = _fetch_tags(client, response.get("evaluatorArn"), "evaluator")
+
+    return drop_none(  # type: ignore[return-value]
+        {
+            "evaluatorId": response["evaluatorId"],
+            "evaluatorArn": response.get("evaluatorArn") or "",
+            "evaluatorName": response.get("evaluatorName") or "",
+            "level": response.get("level") or "SESSION",
+            "status": response.get("status") or "UNKNOWN",
+            "description": response.get("description"),
+            "evaluatorConfig": evaluator_config,
+            "kmsKeyArn": response.get("kmsKeyArn"),
+            "tags": tags,
+        }
+    )
+
+
+class EvaluatorSummary(TypedDict):
+    evaluatorId: str
+    evaluatorArn: str
+    evaluatorName: str
+    evaluatorType: str
+    level: NotRequired[str]
+    status: str
+    description: NotRequired[str]
+
+
+class ListEvaluatorsResult(TypedDict):
+    evaluators: list[EvaluatorSummary]
+    nextToken: NotRequired[str]
+
+
+def list_evaluators(
+    *, region: str, max_results: int | None = None, next_token: str | None = None, client: BaseClient | None = None
+) -> ListEvaluatorsResult:
+    client = client or create_control_client(region)
+    response = client.list_evaluators(**_list_params(max_results, next_token))
+    evaluators: list[EvaluatorSummary] = [
+        drop_none(  # type: ignore[misc]
+            {
+                "evaluatorId": e.get("evaluatorId") or "",
+                "evaluatorArn": e.get("evaluatorArn") or "",
+                "evaluatorName": e.get("evaluatorName") or "",
+                "evaluatorType": e.get("evaluatorType") or "Custom",
+                "level": e.get("level"),
+                "status": e.get("status") or "UNKNOWN",
+                "description": e.get("description"),
+            }
+        )
+        for e in response.get("evaluators") or []
+    ]
+    return drop_none({"evaluators": evaluators, "nextToken": response.get("nextToken")})  # type: ignore[return-value]
+
+
+def list_all_evaluators(*, region: str) -> list[EvaluatorSummary]:
+    """All custom evaluators (``Builtin.*`` evaluators are filtered out; only custom ones can be imported)."""
+
+    def page(opts: dict[str, Any], client: BaseClient) -> tuple[list[EvaluatorSummary], str | None]:
+        result = list_evaluators(**opts, client=client)
+        items = [e for e in result["evaluators"] if not e["evaluatorName"].startswith("Builtin.")]
+        return items, result.get("nextToken")
+
+    return _paginate_all(region, page)
+
+
+# ============================================================================
+# Online evaluation configs
+# ============================================================================
+
+
+class OnlineEvalConfigSummary(TypedDict):
+    onlineEvaluationConfigId: str
+    onlineEvaluationConfigArn: str
+    onlineEvaluationConfigName: str
+    description: NotRequired[str]
+    status: str
+    executionStatus: str
+
+
+class ListOnlineEvalConfigsResult(TypedDict):
+    configs: list[OnlineEvalConfigSummary]
+    nextToken: NotRequired[str]
+
+
+def list_online_evaluation_configs(
+    *, region: str, max_results: int | None = None, next_token: str | None = None, client: BaseClient | None = None
+) -> ListOnlineEvalConfigsResult:
+    client = client or create_control_client(region)
+    response = client.list_online_evaluation_configs(**_list_params(max_results, next_token))
+    configs: list[OnlineEvalConfigSummary] = [
+        drop_none(  # type: ignore[misc]
+            {
+                "onlineEvaluationConfigId": c.get("onlineEvaluationConfigId") or "",
+                "onlineEvaluationConfigArn": c.get("onlineEvaluationConfigArn") or "",
+                "onlineEvaluationConfigName": c.get("onlineEvaluationConfigName") or "",
+                "description": c.get("description"),
+                "status": c.get("status") or "UNKNOWN",
+                "executionStatus": c.get("executionStatus") or "UNKNOWN",
+            }
+        )
+        for c in response.get("onlineEvaluationConfigs") or []
+    ]
+    return drop_none({"configs": configs, "nextToken": response.get("nextToken")})  # type: ignore[return-value]
+
+
+def list_all_online_evaluation_configs(*, region: str) -> list[OnlineEvalConfigSummary]:
+    def page(opts: dict[str, Any], client: BaseClient) -> tuple[list[OnlineEvalConfigSummary], str | None]:
+        result = list_online_evaluation_configs(**opts, client=client)
+        return result["configs"], result.get("nextToken")
+
+    return _paginate_all(region, page)
+
+
+OnlineEvalExecutionStatus = Literal["ENABLED", "DISABLED"]
+
+
+class UpdateOnlineEvalStatusResult(TypedDict):
+    configId: str
+    executionStatus: str
+    status: str
+
+
+def update_online_eval_execution_status(
+    *, region: str, online_evaluation_config_id: str, execution_status: OnlineEvalExecutionStatus
+) -> UpdateOnlineEvalStatusResult:
+    """Pause/resume an online evaluation config."""
+    return update_online_eval_config(
+        region=region, online_evaluation_config_id=online_evaluation_config_id, execution_status=execution_status
+    )
+
+
+def update_online_eval_config(
+    *, region: str, online_evaluation_config_id: str, execution_status: OnlineEvalExecutionStatus | None = None
+) -> UpdateOnlineEvalStatusResult:
+    client = create_control_client(region)
+    params: dict[str, Any] = {"onlineEvaluationConfigId": online_evaluation_config_id}
+    if execution_status:
+        params["executionStatus"] = execution_status
+    response = client.update_online_evaluation_config(**params)
+    return {
+        "configId": response.get("onlineEvaluationConfigId") or online_evaluation_config_id,
+        "executionStatus": response.get("executionStatus") or execution_status or "UNKNOWN",
+        "status": response.get("status") or "UNKNOWN",
+    }
+
+
+class GetOnlineEvalConfigResult(TypedDict):
+    configId: str
+    configArn: str
+    configName: str
+    status: str
+    executionStatus: str
+    description: NotRequired[str]
+    failureReason: NotRequired[str]
+    outputLogGroupName: NotRequired[str]
+    samplingPercentage: NotRequired[float]
+    serviceNames: NotRequired[list[str]]
+    """CloudWatch data-source service names (e.g. ``projectName_agentName.DEFAULT``)."""
+    evaluatorIds: NotRequired[list[str]]
+
+
+def get_online_evaluation_config(*, region: str, config_id: str) -> GetOnlineEvalConfigResult:
+    client = create_control_client(region)
+    response = client.get_online_evaluation_config(onlineEvaluationConfigId=config_id)
+    if not response.get("onlineEvaluationConfigId"):
+        raise RuntimeError(f"No online evaluation config found for ID {config_id}")
+
+    log_group = ((response.get("outputConfig") or {}).get("cloudWatchConfig") or {}).get("logGroupName")
+    sampling = ((response.get("rule") or {}).get("samplingConfig") or {}).get("samplingPercentage")
+    data_source = response.get("dataSourceConfig") or {}
+    service_names = (
+        (data_source.get("cloudWatchLogs") or {}).get("serviceNames") if "cloudWatchLogs" in data_source else None
+    )
+    evaluator_ids = [e["evaluatorId"] for e in response.get("evaluators") or [] if e.get("evaluatorId")]
+
+    return drop_none(  # type: ignore[return-value]
+        {
+            "configId": response["onlineEvaluationConfigId"],
+            "configArn": response.get("onlineEvaluationConfigArn") or "",
+            "configName": response.get("onlineEvaluationConfigName") or "",
+            "status": response.get("status") or "UNKNOWN",
+            "executionStatus": response.get("executionStatus") or "UNKNOWN",
+            "description": response.get("description"),
+            "failureReason": response.get("failureReason"),
+            "outputLogGroupName": log_group,
+            "samplingPercentage": sampling,
+            "serviceNames": service_names,
+            "evaluatorIds": evaluator_ids,
+        }
+    )
+
+
+# ============================================================================
+# Gateways — list & get
+# ============================================================================
+
+
+class GatewaySummary(TypedDict):
+    gatewayId: str
+    name: str
+    status: str
+    description: NotRequired[str]
+    authorizerType: str
+
+
+class GatewayDetail(TypedDict):
+    gatewayId: str
+    gatewayArn: str
+    gatewayUrl: NotRequired[str]
+    name: str
+    status: str
+    description: NotRequired[str]
+    authorizerType: str
+    roleArn: NotRequired[str]
+    authorizerConfiguration: NotRequired[dict[str, Any]]
+    """``{"customJwtAuthorizer": {discoveryUrl, allowedAudience?, allowedClients?, allowedScopes?, customClaims?}}``"""
+    protocolType: NotRequired[str]
+    protocolConfiguration: NotRequired[dict[str, Any]]
+    exceptionLevel: NotRequired[str]
+    policyEngineConfiguration: NotRequired[dict[str, str]]
+    tags: NotRequired[dict[str, str]]
+
+
+class ListGatewaysResult(TypedDict):
+    gateways: list[GatewaySummary]
+    nextToken: NotRequired[str]
+
+
+def list_gateways_page(
+    *, region: str, max_results: int | None = None, next_token: str | None = None, client: BaseClient | None = None
+) -> ListGatewaysResult:
+    client = client or create_control_client(region)
+    response = client.list_gateways(**_list_params(max_results, next_token))
+    gateways: list[GatewaySummary] = [
+        drop_none(  # type: ignore[misc]
+            {
+                "gatewayId": g.get("gatewayId") or "",
+                "name": g.get("name") or "",
+                "status": g.get("status") or "UNKNOWN",
+                "description": g.get("description"),
+                "authorizerType": g.get("authorizerType") or "NONE",
+            }
+        )
+        for g in response.get("items") or []
+    ]
+    return drop_none({"gateways": gateways, "nextToken": response.get("nextToken")})  # type: ignore[return-value]
+
+
+def list_all_gateways(*, region: str) -> list[GatewaySummary]:
+    def page(opts: dict[str, Any], client: BaseClient) -> tuple[list[GatewaySummary], str | None]:
+        result = list_gateways_page(**opts, client=client)
+        return result["gateways"], result.get("nextToken")
+
+    return _paginate_all(region, page)
+
+
+def _map_custom_claim(c: dict[str, Any]) -> dict[str, Any]:
+    match_value = c.get("authorizingClaimMatchValue") or {}
+    claim_match_value = match_value.get("claimMatchValue") or {}
+    return {
+        "inboundTokenClaimName": c.get("inboundTokenClaimName") or "",
+        "inboundTokenClaimValueType": c.get("inboundTokenClaimValueType") or "STRING",
+        "authorizingClaimMatchValue": {
+            "claimMatchValue": drop_none(
+                {
+                    "matchValueString": claim_match_value.get("matchValueString"),
+                    "matchValueStringList": claim_match_value.get("matchValueStringList"),
+                }
+            ),
+            "claimMatchOperator": match_value.get("claimMatchOperator") or "EQUALS",
+        },
+    }
+
+
+def get_gateway_detail(*, region: str, gateway_id: str) -> GatewayDetail:
+    client = create_control_client(region)
+    response = client.get_gateway(gatewayIdentifier=gateway_id)
+
+    authorizer_configuration: dict[str, Any] | None = None
+    jwt = (response.get("authorizerConfiguration") or {}).get("customJWTAuthorizer")
+    if jwt:
+        authorizer = dict(_jwt_authorizer(jwt))
+        if jwt.get("customClaims") is not None:
+            authorizer["customClaims"] = [_map_custom_claim(c) for c in jwt["customClaims"]]
+        authorizer_configuration = {"customJwtAuthorizer": authorizer}
+
+    protocol_configuration: dict[str, Any] | None = None
+    protocol = response.get("protocolConfiguration") or {}
+    if "mcp" in protocol:
+        protocol_configuration = {"mcp": drop_none({"searchType": (protocol.get("mcp") or {}).get("searchType")})}
+
+    tags = _fetch_tags(client, response.get("gatewayArn"), "gateway")
+
+    # The service returns protocolType 'MCP' or null (null = non-MCP gateway).
+    protocol_type = "MCP" if response.get("protocolType") == "MCP" else "None"
+    policy_engine = response.get("policyEngineConfiguration")
+
+    return drop_none(  # type: ignore[return-value]
+        {
+            "gatewayId": response.get("gatewayId") or "",
+            "gatewayArn": response.get("gatewayArn") or "",
+            "gatewayUrl": response.get("gatewayUrl"),
+            "name": response.get("name") or "",
+            "status": response.get("status") or "UNKNOWN",
+            "description": response.get("description"),
+            "authorizerType": response.get("authorizerType") or "NONE",
+            "roleArn": response.get("roleArn"),
+            "authorizerConfiguration": authorizer_configuration,
+            "protocolType": protocol_type,
+            "protocolConfiguration": protocol_configuration,
+            "exceptionLevel": response.get("exceptionLevel"),
+            "policyEngineConfiguration": {
+                "arn": policy_engine.get("arn") or "",
+                "mode": policy_engine.get("mode") or "",
+            }
+            if policy_engine
+            else None,
+            "tags": tags,
+        }
+    )
+
+
+# ============================================================================
+# Gateway targets — list & get
+# ============================================================================
+
+
+class GatewayTargetSummary(TypedDict):
+    targetId: str
+    name: str
+    status: str
+    description: NotRequired[str]
+
+
+class GatewayTargetDetail(TypedDict):
+    targetId: str
+    name: str
+    status: str
+    description: NotRequired[str]
+    targetConfiguration: NotRequired[dict[str, Any]]
+    """``{"mcp": {mcpServer?, apiGateway?, openApiSchema?, smithyModel?, lambda?}, "http": {...}}``"""
+    credentialProviderConfigurations: list[dict[str, Any]]
+
+
+class ListGatewayTargetsResult(TypedDict):
+    targets: list[GatewayTargetSummary]
+    nextToken: NotRequired[str]
+
+
+def list_gateway_targets_page(
+    *,
+    region: str,
+    gateway_id: str,
+    max_results: int | None = None,
+    next_token: str | None = None,
+    client: BaseClient | None = None,
+) -> ListGatewayTargetsResult:
+    client = client or create_control_client(region)
+    response = client.list_gateway_targets(**_list_params(max_results, next_token, gatewayIdentifier=gateway_id))
+    targets: list[GatewayTargetSummary] = [
+        drop_none(  # type: ignore[misc]
+            {
+                "targetId": t.get("targetId") or "",
+                "name": t.get("name") or "",
+                "status": t.get("status") or "UNKNOWN",
+                "description": t.get("description"),
+            }
+        )
+        for t in response.get("items") or []
+    ]
+    return drop_none({"targets": targets, "nextToken": response.get("nextToken")})  # type: ignore[return-value]
+
+
+def list_all_gateway_targets(*, region: str, gateway_id: str) -> list[GatewayTargetSummary]:
+    client = create_control_client(region)
+    items: list[GatewayTargetSummary] = []
+    next_token: str | None = None
+    while True:
+        result = list_gateway_targets_page(
+            region=region, gateway_id=gateway_id, max_results=PAGE_SIZE, next_token=next_token, client=client
+        )
+        items.extend(result["targets"])
+        next_token = result.get("nextToken")
+        if not next_token:
+            return items
+
+
+def _map_schema_source(source: dict[str, Any]) -> dict[str, Any]:
+    s3 = source.get("s3")
+    return drop_none(
+        {
+            "s3": drop_none({"uri": s3.get("uri") or "", "bucketOwnerAccountId": s3.get("bucketOwnerAccountId")})
+            if s3
+            else None,
+            "inlinePayload": source.get("inlinePayload"),
+        }
+    )
+
+
+def _map_mcp_target(mcp: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    if mcp.get("mcpServer"):
+        out["mcpServer"] = {"endpoint": mcp["mcpServer"].get("endpoint") or ""}
+    if mcp.get("apiGateway"):
+        api = mcp["apiGateway"]
+        tool_config = api.get("apiGatewayToolConfiguration")
+        mapped_tool_config = None
+        if tool_config:
+            filters = tool_config.get("toolFilters")
+            overrides = tool_config.get("toolOverrides")
+            mapped_tool_config = drop_none(
+                {
+                    "toolFilters": [
+                        {"filterPath": f.get("filterPath") or "", "methods": f.get("methods") or []} for f in filters
+                    ]
+                    if filters is not None
+                    else None,
+                    "toolOverrides": [
+                        drop_none(
+                            {
+                                "name": o.get("name") or "",
+                                "path": o.get("path") or "",
+                                "method": o.get("method") or "",
+                                "description": o.get("description"),
+                            }
+                        )
+                        for o in overrides
+                    ]
+                    if overrides is not None
+                    else None,
+                }
+            )
+        out["apiGateway"] = drop_none(
+            {
+                "restApiId": api.get("restApiId") or "",
+                "stage": api.get("stage") or "",
+                "apiGatewayToolConfiguration": mapped_tool_config,
+            }
+        )
+    if mcp.get("openApiSchema"):
+        out["openApiSchema"] = _map_schema_source(mcp["openApiSchema"])
+    if mcp.get("smithyModel"):
+        out["smithyModel"] = _map_schema_source(mcp["smithyModel"])
+    if mcp.get("lambda"):
+        out["lambda"] = drop_none(
+            {"lambdaArn": mcp["lambda"].get("lambdaArn") or "", "toolSchema": mcp["lambda"].get("toolSchema")}
+        )
+    return out
+
+
+def _map_runtime_ref(ref: dict[str, Any]) -> dict[str, Any]:
+    return drop_none({"runtimeArn": ref.get("arn") or ref.get("runtimeArn") or "", "qualifier": ref.get("qualifier")})
+
+
+def _map_credential_provider_configuration(c: dict[str, Any]) -> dict[str, Any]:
+    provider = c.get("credentialProvider")
+    mapped_provider = None
+    if provider:
+        oauth = provider.get("oauthCredentialProvider")
+        api_key = provider.get("apiKeyCredentialProvider")
+        mapped_provider = drop_none(
+            {
+                "oauthCredentialProvider": drop_none(
+                    {"providerArn": oauth.get("providerArn") or "", "scopes": oauth.get("scopes")}
+                )
+                if oauth
+                else None,
+                "apiKeyCredentialProvider": {"providerArn": api_key.get("providerArn") or ""} if api_key else None,
+            }
+        )
+    return drop_none(
+        {"credentialProviderType": c.get("credentialProviderType") or "", "credentialProvider": mapped_provider}
+    )
+
+
+def get_gateway_target_detail(*, region: str, gateway_id: str, target_id: str) -> GatewayTargetDetail:
+    client = create_control_client(region)
+    response = client.get_gateway_target(gatewayIdentifier=gateway_id, targetId=target_id)
+
+    target_configuration: dict[str, Any] | None = None
+    raw_config = response.get("targetConfiguration") or {}
+    if "mcp" in raw_config:
+        target_configuration = {"mcp": _map_mcp_target(raw_config.get("mcp") or {})}
+    if "http" in raw_config:
+        http = raw_config.get("http") or {}
+        target_configuration = target_configuration or {}
+        http_out: dict[str, Any] = {}
+        if http.get("agentcoreRuntime"):
+            http_out["agentcoreRuntime"] = _map_runtime_ref(http["agentcoreRuntime"])
+        if http.get("runtimeTargetConfiguration"):
+            http_out["runtimeTargetConfiguration"] = _map_runtime_ref(http["runtimeTargetConfiguration"])
+        target_configuration["http"] = http_out
+
+    credential_configs = [
+        _map_credential_provider_configuration(c) for c in response.get("credentialProviderConfigurations") or []
+    ]
+
+    return drop_none(  # type: ignore[return-value]
+        {
+            "targetId": response.get("targetId") or "",
+            "name": response.get("name") or "",
+            "status": response.get("status") or "UNKNOWN",
+            "description": response.get("description"),
+            "targetConfiguration": target_configuration,
+            "credentialProviderConfigurations": credential_configs,
+        }
+    )