agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/invoke/action.py

@@ -0,0 +1,840 @@
+"""Port of commands/invoke/action.ts: invoke a deployed runtime, harness, or gateway."""
+
+import json
+import sys
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.aws import (
+    DEFAULT_RUNTIME_USER_ID,
+    AguiInvokeOptions,
+    ExecuteBashOptions,
+    InvokeAgentRuntimeOptions,
+    McpInvokeOptions,
+    build_agui_run_input,
+    execute_bash_command,
+    extract_result,
+    get_or_create_payment_session,
+    invoke_a2a_runtime,
+    invoke_agent_runtime,
+    invoke_agent_runtime_streaming,
+    invoke_agui_runtime,
+    mcp_call_tool,
+    mcp_init_session,
+    mcp_list_tools,
+    parse_sse,
+)
+from agentcore.aws._http import http_request, sign_headers
+from agentcore.aws.agentcore import A2AInvokeOptions
+from agentcore.aws.agentcore_harness import invoke_harness
+from agentcore.aws.partition import dns_suffix
+from agentcore.cli.commands.invoke import _deps
+from agentcore.cli.commands.invoke.constants import ANSI
+from agentcore.cli.commands.invoke.resolve import resolve_invoke_target
+from agentcore.cli.commands.invoke.types import InvokeOptions, InvokeResult, result
+from agentcore.lib.errors.types import ResourceNotFoundError, ValidationError
+from agentcore.lib.schemas.io.config_io import ConfigIO
+from agentcore.logging import InvokeLogger
+
+
+@dataclass
+class InvokeContext:
+    project: Any
+    deployed_state: Any
+    aws_targets: list[Any]
+
+
+def load_invoke_config(config_io: ConfigIO | None = None) -> InvokeContext:
+    config_io = config_io or ConfigIO()
+    return InvokeContext(
+        project=config_io.read_project_spec(),
+        deployed_state=config_io.read_deployed_state(),
+        aws_targets=config_io.read_aws_deployment_targets(),
+    )
+
+
+def _write(text: str, stream: Any = None) -> None:
+    out = stream or sys.stdout
+    out.write(text)
+    out.flush()
+
+
+def _err_text(err: BaseException) -> str:
+    return str(err)
+
+
+def _drop_none(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {k: _drop_none(v) for k, v in value.items() if v is not None}
+    if isinstance(value, list):
+        return [_drop_none(v) for v in value]
+    return value
+
+
+def _compact(value: Any) -> str:
+    return json.dumps(_drop_none(value), separators=(",", ":"), ensure_ascii=False)
+
+
+def _is_json(text: str) -> bool:
+    try:
+        json.loads(text)
+        return True
+    except ValueError:
+        return False
+
+
+# ============================================================================
+# Gateway invoke
+# ============================================================================
+
+
+def _handle_gateway_invoke(context: InvokeContext, options: InvokeOptions) -> InvokeResult:
+    project, deployed_state, aws_targets = context.project, context.deployed_state, context.aws_targets
+    targets = deployed_state.targets or {}
+    target_names = list(targets)
+    if not target_names:
+        return result(False, error=ResourceNotFoundError("No deployed targets found. Run `agentcore deploy` first."))
+    selected = options.target_name if options.target_name is not None else target_names[0]
+    target_state = targets.get(selected)
+    target_config = next((t for t in aws_targets if t.name == selected), None)
+    if target_config is None:
+        return result(False, error=ResourceNotFoundError(f"Target config '{selected}' not found in aws-targets"))
+
+    resources = target_state.resources if target_state else None
+    gw_state = ((resources.gateways if resources else None) or {}).get(options.gateway) or (
+        ((resources.mcp.gateways if resources and resources.mcp else None) or {}).get(options.gateway)
+    )
+    if not gw_state:
+        return result(
+            False,
+            error=ResourceNotFoundError(f"Gateway '{options.gateway}' is not deployed. Run `agentcore deploy` first."),
+        )
+
+    gw_spec = next((g for g in (project.agent_core_gateways or []) if g.name == options.gateway), None)
+    is_mcp = gw_spec is not None and gw_spec.protocol_type == "MCP"
+    authorizer = gw_spec.authorizer_type if gw_spec is not None else None
+
+    if authorizer == "CUSTOM_JWT" and not options.bearer_token:
+        return result(False, error=ValidationError("Gateway requires --bearer-token (CUSTOM_JWT authorizer)."))
+
+    region = target_config.region
+    gateway_url = gw_state.gateway_url
+    if not gateway_url:
+        parts = (gw_state.gateway_arn or "").split(":")
+        r = parts[3] if len(parts) > 3 else ""
+        gateway_url = f"https://{gw_state.gateway_id}.gateway.bedrock-agentcore.{r}.{dns_suffix(r)}" if r else None
+    if not gateway_url:
+        return result(False, error=ValidationError("Could not determine gateway URL."))
+
+    gw_targets = list(gw_spec.targets or []) if gw_spec is not None else []
+    if not is_mcp:
+        if not options.gateway_target:
+            http_targets = [t.name for t in gw_targets if t.target_type == "httpRuntime"]
+            return result(
+                False,
+                error=ValidationError(
+                    f"--target-name is required for HTTP gateways. Available targets: {', '.join(http_targets)}"
+                ),
+            )
+        target_spec = next((t for t in gw_targets if t.name == options.gateway_target), None)
+        if target_spec is None:
+            return result(
+                False,
+                error=ResourceNotFoundError(
+                    f"Target '{options.gateway_target}' not found on gateway '{options.gateway}'."
+                ),
+            )
+        if target_spec.target_type != "httpRuntime":
+            return result(
+                False, error=ValidationError(f"Target '{options.gateway_target}' is not an httpRuntime target.")
+            )
+        invocation_url = f"{gateway_url}/{options.gateway_target}/invocations"
+        if not options.prompt:
+            return result(False, error=ValidationError("--prompt is required for HTTP gateway invoke."))
+        # Plain strings become {"prompt": "..."}; JSON prompts pass through unchanged.
+        body = options.prompt if _is_json(options.prompt) else json.dumps({"prompt": options.prompt})
+    else:
+        if not options.tool:
+            return result(False, error=ValidationError("--tool is required for MCP gateway invoke."))
+        invocation_url = gateway_url if gateway_url.endswith("/mcp") else f"{gateway_url}/mcp"
+        body = json.dumps(
+            {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "tools/call",
+                "params": {"name": options.tool, "arguments": json.loads(options.input) if options.input else {}},
+            },
+            separators=(",", ":"),
+        )
+
+    headers: dict[str, str] = {"content-type": "application/json"}
+    if options.session_id:
+        headers["x-amz-bedrock-agentcore-session-id"] = options.session_id
+    if is_mcp:
+        headers["Accept"] = "application/json, text/event-stream"
+        headers["Mcp-Protocol-Version"] = "2025-03-26"
+
+    fetch_headers = headers
+    if authorizer == "CUSTOM_JWT":
+        fetch_headers = {**headers, "authorization": f"Bearer {options.bearer_token}"}
+    elif authorizer == "AWS_IAM":
+        fetch_headers = sign_headers("POST", invocation_url, region=region, headers=headers, body=body)
+
+    response = http_request("POST", invocation_url, headers=fetch_headers, body=body)
+    if not response.ok:
+        return result(False, error=RuntimeError(f"Gateway invoke failed ({response.status}): {response.text()}"))
+
+    response_text = response.text()
+    if is_mcp:
+        response_body = response_text
+    elif "data: " in response_text:
+        response_body = parse_sse(response_text)
+    else:
+        response_body = extract_result(response_text)
+
+    return result(
+        True,
+        response=response_body,
+        agentName=options.gateway_target or options.gateway,
+        targetName=selected,
+    )
+
+
+# ============================================================================
+# Main invoke handler
+# ============================================================================
+
+
+def handle_invoke(context: InvokeContext, options: InvokeOptions | None = None) -> InvokeResult:
+    options = options or InvokeOptions()
+    project, deployed_state, aws_targets = context.project, context.deployed_state, context.aws_targets
+
+    if options.gateway:
+        return _handle_gateway_invoke(context, options)
+
+    harness_entries = project.harnesses or []
+    runtimes = project.runtimes or []
+    is_harness_invoke = options.harness_name is not None or (len(harness_entries) > 0 and len(runtimes) == 0)
+
+    if is_harness_invoke:
+        targets = deployed_state.targets or {}
+        target_names = list(targets)
+        if not target_names:
+            return result(
+                False, error=ResourceNotFoundError("No deployed targets found. Run `agentcore deploy` first.")
+            )
+        selected = options.target_name if options.target_name is not None else target_names[0]
+        if options.target_name and options.target_name not in target_names:
+            return result(
+                False,
+                error=ResourceNotFoundError(
+                    f"Target '{options.target_name}' not found. Available: {', '.join(target_names)}"
+                ),
+            )
+        target_config = next((t for t in aws_targets if t.name == selected), None)
+        if target_config is None:
+            return result(False, error=ResourceNotFoundError(f"Target config '{selected}' not found in aws-targets"))
+        return _handle_harness_invoke(project, targets.get(selected), target_config, selected, options)
+
+    if harness_entries and runtimes and not options.agent_name:
+        runtime_names = ", ".join(a.name for a in runtimes)
+        harness_names = ", ".join(h.name for h in harness_entries)
+        return result(
+            False,
+            error=ValidationError(
+                "Project has both runtimes and harnesses. Specify one:\n"
+                f"  --runtime: {runtime_names}\n"
+                f"  --harness: {harness_names}"
+            ),
+        )
+
+    resolved = resolve_invoke_target(
+        project=project,
+        deployed_state=deployed_state,
+        aws_targets=aws_targets,
+        agent_name=options.agent_name,
+        target_name=options.target_name,
+        bearer_token=options.bearer_token,
+        session_id=options.session_id,
+    )
+    if not resolved.success:
+        return result(False, error=resolved.error)
+
+    agent_spec = resolved.agent_spec
+    selected = resolved.target_name
+    region = resolved.target_config.region
+    runtime_arn = resolved.runtime_arn
+    baggage = resolved.baggage
+    options = options.with_(
+        bearer_token=resolved.bearer_token or options.bearer_token,
+        session_id=resolved.session_id or options.session_id,
+    )
+
+    if agent_spec.network_mode == "VPC" and not options.json:
+        print(
+            f"{ANSI.yellow}Warning: This agent uses VPC network mode. Ensure your VPC endpoints are configured for "
+            f"invocation.{ANSI.reset}",
+            flush=True,
+        )
+
+    protocol = agent_spec.protocol
+    if (
+        (options.payment_instrument_id or options.payment_session_id or options.auto_session)
+        and protocol
+        and protocol != "HTTP"
+    ):
+        return result(
+            False,
+            error=RuntimeError(
+                f"Payment flags are only supported for HTTP protocol agents. Agent '{agent_spec.name}' uses "
+                f"'{protocol}'."
+            ),
+        )
+
+    if options.auto_session and options.payment_session_id:
+        return result(
+            False,
+            error=RuntimeError("--auto-session and --payment-session-id are mutually exclusive. Use one or the other."),
+        )
+
+    # Payments end-user identity: --payment-user-id, falling back to --user-id.
+    resolved_payment_user_id = options.payment_user_id if options.payment_user_id is not None else options.user_id
+    options = options.with_(payment_user_id=resolved_payment_user_id)
+
+    using_payment_context = bool(options.payment_instrument_id or options.payment_session_id or options.auto_session)
+    project_has_payments = len(project.payments or []) > 0
+    if (using_payment_context or project_has_payments) and not resolved_payment_user_id:
+        _write(
+            f"{ANSI.yellow}Warning: no --payment-user-id (or --user-id) provided. Payments will be scoped to "
+            f'"{DEFAULT_RUNTIME_USER_ID}" on the agent. This is intended for single-user testing only; '
+            "production should set --payment-user-id per end user so wallets and budgets are not shared."
+            f"{ANSI.reset}\n",
+            sys.stderr,
+        )
+
+    if options.auto_session and not options.payment_session_id:
+        target_state = (deployed_state.targets or {}).get(selected)
+        payments = target_state.resources.payments if target_state and target_state.resources else None
+        first_manager = next(iter(payments.values()), None) if payments else None
+        if not first_manager or not first_manager.manager_arn:
+            return result(
+                False,
+                error=RuntimeError("--auto-session requires a deployed payment manager. Run `agentcore deploy` first."),
+            )
+        try:
+            first_name = next(iter(payments))
+            payment_spec = next((p for p in (project.payments or []) if p.name == first_name), None)
+            kwargs: dict[str, Any] = {}
+            if payment_spec is not None and payment_spec.default_spend_limit is not None:
+                kwargs["default_spend_limit"] = payment_spec.default_spend_limit
+            session = get_or_create_payment_session(
+                region=region,
+                user_id=resolved_payment_user_id or DEFAULT_RUNTIME_USER_ID,
+                manager_arn=first_manager.manager_arn,
+                **kwargs,
+            )
+            options = options.with_(payment_session_id=session)
+        except Exception as exc:  # noqa: BLE001
+            return result(False, error=RuntimeError(f"--auto-session failed to create payment session: {exc}"))
+
+    if options.exec:
+        return _handle_invoke_exec(region, runtime_arn, agent_spec.name, selected, options)
+
+    if protocol == "MCP":
+        mcp_opts = McpInvokeOptions(
+            region=region,
+            runtime_arn=runtime_arn,
+            user_id=options.user_id,
+            headers=options.headers,
+            bearer_token=options.bearer_token,
+        )
+        if options.prompt == "list-tools":
+            try:
+                listed = mcp_list_tools(mcp_opts)
+                return result(
+                    True,
+                    agentName=agent_spec.name,
+                    targetName=selected,
+                    response=_deps.format_mcp_tool_list(listed.tools),
+                )
+            except Exception as exc:  # noqa: BLE001
+                return result(False, error=RuntimeError(f"Failed to list MCP tools: {exc}"))
+        if options.prompt == "call-tool":
+            if not options.tool:
+                return result(
+                    False,
+                    error=RuntimeError(
+                        'MCP call-tool requires --tool <name>. Use "list-tools" to see available tools.'
+                    ),
+                )
+            args: dict[str, Any] = {}
+            if options.input:
+                try:
+                    args = json.loads(options.input)
+                except ValueError:
+                    return result(False, error=ValidationError(f"Invalid JSON for --input: {options.input}"))
+            try:
+                mcp_session_id = mcp_init_session(mcp_opts)
+                mcp_opts.mcp_session_id = mcp_session_id
+                response = mcp_call_tool(mcp_opts, options.tool, args)
+                return result(True, agentName=agent_spec.name, targetName=selected, response=response)
+            except Exception as exc:  # noqa: BLE001
+                return result(False, error=RuntimeError(f"Failed to call MCP tool: {exc}"))
+        if not options.prompt:
+            return result(
+                False,
+                error=ValidationError(
+                    "MCP agents require a command. Usage:\n  agentcore invoke list-tools\n"
+                    '  agentcore invoke call-tool --tool <name> --input \'{"arg": "value"}\''
+                ),
+            )
+
+    if not options.prompt:
+        return result(False, error=ValidationError('No prompt provided. Usage: agentcore invoke "your prompt"'))
+
+    if protocol == "A2A":
+        try:
+            a2a = invoke_a2a_runtime(
+                A2AInvokeOptions(
+                    region=region,
+                    runtime_arn=runtime_arn,
+                    user_id=options.user_id,
+                    session_id=options.session_id,
+                    headers=options.headers,
+                    bearer_token=options.bearer_token,
+                ),
+                options.prompt,
+            )
+            response = ""
+            for chunk in a2a.stream:
+                response += chunk
+                if options.stream:
+                    _write(chunk)
+            if options.stream:
+                _write("\n")
+            return result(True, agentName=agent_spec.name, targetName=selected, response=response)
+        except Exception as exc:  # noqa: BLE001
+            return result(False, error=RuntimeError(f"A2A invoke failed: {exc}"))
+
+    if protocol == "AGUI":
+        logger = InvokeLogger(agent_name=agent_spec.name, runtime_arn=runtime_arn, region=region)
+        try:
+            agui_input = build_agui_run_input(options.prompt, options.session_id)
+            logger.log_prompt(options.prompt, None, options.user_id)
+            agui = invoke_agui_runtime(
+                AguiInvokeOptions(
+                    region=region,
+                    runtime_arn=runtime_arn,
+                    session_id=options.session_id,
+                    user_id=options.user_id,
+                    logger=logger,
+                    headers=options.headers,
+                    bearer_token=options.bearer_token,
+                ),
+                agui_input,
+            )
+            response = ""
+            has_error = False
+            for chunk in agui.text_stream:
+                response += chunk
+                if chunk.startswith("Error: "):
+                    has_error = True
+                if options.stream:
+                    _write(chunk)
+            if options.stream:
+                _write("\n")
+            logger.log_response(response)
+            if has_error:
+                return result(
+                    False,
+                    error=RuntimeError(response),
+                    agentName=agent_spec.name,
+                    targetName=selected,
+                    response=response,
+                    sessionId=agui.session_id,
+                    logFilePath=logger.log_file_path,
+                )
+            return result(
+                True,
+                agentName=agent_spec.name,
+                targetName=selected,
+                response=response,
+                sessionId=agui.session_id,
+                logFilePath=logger.log_file_path,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.log_error(exc, "AGUI invoke failed")
+            return result(False, error=RuntimeError(f"AGUI invoke failed: {exc}"))
+
+    logger = InvokeLogger(
+        agent_name=agent_spec.name, runtime_arn=runtime_arn, region=region, session_id=options.session_id
+    )
+    logger.log_prompt(options.prompt, options.session_id, options.user_id)
+
+    invoke_options = InvokeAgentRuntimeOptions(
+        region=region,
+        runtime_arn=runtime_arn,
+        payload=options.prompt,
+        session_id=options.session_id,
+        user_id=options.user_id,
+        headers=options.headers,
+        bearer_token=options.bearer_token,
+        baggage=baggage,
+        payment_instrument_id=options.payment_instrument_id,
+        payment_session_id=options.payment_session_id,
+        payment_user_id=options.payment_user_id,
+    )
+
+    if options.stream:
+        full = ""
+        try:
+            invoke_options.logger = logger
+            streamed = invoke_agent_runtime_streaming(invoke_options)
+            for chunk in streamed.stream:
+                full += chunk
+                _write(chunk)
+            _write("\n")
+            logger.log_response(full)
+            return result(
+                True,
+                agentName=agent_spec.name,
+                targetName=selected,
+                response=full,
+                sessionId=streamed.session_id,
+                logFilePath=logger.log_file_path,
+            )
+        except Exception as exc:
+            logger.log_error(exc, "invoke streaming failed")
+            raise
+
+    response = invoke_agent_runtime(invoke_options)
+    logger.log_response(response.content)
+    return result(
+        True,
+        agentName=agent_spec.name,
+        targetName=selected,
+        response=response.content,
+        sessionId=response.session_id,
+        logFilePath=logger.log_file_path,
+    )
+
+
+# ============================================================================
+# Harness invoke
+# ============================================================================
+
+
+def _spec_get(spec: Any, attr: str) -> Any:
+    if spec is None:
+        return None
+    if isinstance(spec, dict):
+        camel = "".join(p if i == 0 else p.capitalize() for i, p in enumerate(attr.split("_")))
+        return spec.get(camel, spec.get(attr))
+    return getattr(spec, attr, None)
+
+
+def build_harness_base_opts(options: InvokeOptions, harness_spec: Any = None) -> dict[str, Any]:
+    """Per-invocation harness overrides, as keyword arguments for :func:`invoke_harness`."""
+    base: dict[str, Any] = {}
+    if (
+        options.model_id
+        or options.model_provider
+        or options.api_key_arn
+        or options.api_base
+        or options.additional_params
+    ):
+        provider = options.model_provider or _spec_get(harness_spec, "provider")
+        model_id = options.model_id or _spec_get(harness_spec, "model_id") or ""
+        api_key_arn = options.api_key_arn or _spec_get(harness_spec, "api_key_arn")
+        api_base = options.api_base or _spec_get(harness_spec, "api_base")
+        additional_params = options.additional_params or _spec_get(harness_spec, "additional_params")
+        if provider == "open_ai":
+            base["model"] = {
+                "openAiModelConfig": {"modelId": model_id, **({"apiKeyArn": api_key_arn} if api_key_arn else {})}
+            }
+        elif provider == "gemini":
+            base["model"] = {
+                "geminiModelConfig": {"modelId": model_id, **({"apiKeyArn": api_key_arn} if api_key_arn else {})}
+            }
+        elif provider == "lite_llm":
+            config: dict[str, Any] = {"modelId": model_id}
+            if api_key_arn:
+                config["apiKeyArn"] = api_key_arn
+            if api_base:
+                config["apiBase"] = api_base
+            if additional_params:
+                config["additionalParams"] = additional_params
+            base["model"] = {"liteLlmModelConfig": config}
+        else:
+            base["model"] = {"bedrockModelConfig": {"modelId": model_id}}
+    if options.tools:
+        base["tools"] = [{"type": t.strip(), "name": t.strip()} for t in options.tools.split(",")]
+    if options.max_iterations is not None:
+        base["max_iterations"] = options.max_iterations
+    if options.max_tokens is not None:
+        base["max_tokens"] = options.max_tokens
+    if options.harness_timeout is not None:
+        base["timeout_seconds"] = options.harness_timeout
+    if options.skills:
+        skills = []
+        for s in options.skills.split(","):
+            trimmed = s.strip()
+            if trimmed.startswith("s3://"):
+                skills.append({"s3Uri": trimmed})
+            elif trimmed.startswith("https://"):
+                skills.append({"gitUrl": trimmed})
+            else:
+                skills.append({"path": trimmed})
+        base["skills"] = skills
+    if options.system_prompt:
+        base["system_prompt"] = [{"text": options.system_prompt}]
+    if options.allowed_tools:
+        base["allowed_tools"] = [t.strip() for t in options.allowed_tools.split(",")]
+    if options.actor_id:
+        base["actor_id"] = options.actor_id
+    return base
+
+
+def _handle_invoke_exec(
+    region: str, runtime_arn: str, agent_name: str, target_name: str | None, options: InvokeOptions
+) -> InvokeResult:
+    logger = InvokeLogger(agent_name=agent_name, runtime_arn=runtime_arn, region=region, session_id=options.session_id)
+    command = options.prompt
+    if not command:
+        return result(False, error=ValidationError("--exec requires a command (prompt)"))
+    logger.log_prompt(command, options.session_id, options.user_id)
+
+    try:
+        executed = execute_bash_command(
+            ExecuteBashOptions(
+                region=region,
+                runtime_arn=runtime_arn,
+                command=command,
+                session_id=options.session_id,
+                timeout=options.timeout,
+                headers=options.headers,
+                bearer_token=options.bearer_token,
+            )
+        )
+        stdout = ""
+        stderr = ""
+        exit_code: int | None = None
+        status: str | None = None
+        for event in executed.stream:
+            kind = event.get("type")
+            if kind == "stdout" and event.get("data"):
+                stdout += event["data"]
+                if not options.json:
+                    _write(event["data"])
+            elif kind == "stderr" and event.get("data"):
+                stderr += event["data"]
+                if not options.json:
+                    _write(event["data"], sys.stderr)
+            elif kind == "stop":
+                exit_code = event.get("exitCode")
+                status = event.get("status")
+
+        logger.log_response(stdout or stderr or f"exit code: {'undefined' if exit_code is None else exit_code}")
+        payload = _compact({"stdout": stdout, "stderr": stderr, "exitCode": exit_code, "status": status})
+
+        if options.json:
+            if exit_code == 0:
+                return result(
+                    True,
+                    exitCode=exit_code,
+                    agentName=agent_name,
+                    targetName=target_name,
+                    response=payload,
+                    logFilePath=logger.log_file_path,
+                )
+            return result(
+                False,
+                exitCode=exit_code,
+                error=RuntimeError(f"Command exited with code {'undefined' if exit_code is None else exit_code}"),
+                agentName=agent_name,
+                targetName=target_name,
+                response=payload,
+                logFilePath=logger.log_file_path,
+            )
+
+        if exit_code is None:
+            return result(
+                False,
+                error=RuntimeError("Command stream ended without exit code"),
+                agentName=agent_name,
+                targetName=target_name,
+                logFilePath=logger.log_file_path,
+            )
+        if exit_code != 0:
+            suffix = " (timed out)" if status == "TIMED_OUT" else ""
+            return result(
+                False,
+                exitCode=exit_code,
+                error=RuntimeError(f"Command exited with code {exit_code}{suffix}"),
+                agentName=agent_name,
+                targetName=target_name,
+                response=payload,
+                logFilePath=logger.log_file_path,
+            )
+        return result(
+            True, exitCode=exit_code, agentName=agent_name, targetName=target_name, logFilePath=logger.log_file_path
+        )
+    except Exception as exc:
+        logger.log_error(exc, "exec command failed")
+        raise
+
+
+def handle_harness_invoke_by_arn(harness_arn: str, region: str, options: InvokeOptions) -> InvokeResult:
+    if not options.prompt:
+        return result(
+            False,
+            error=ValidationError(
+                'No prompt provided. Usage: agentcore invoke --harness-arn <arn> --region <region> "your prompt"'
+            ),
+        )
+    session_id = options.session_id or str(uuid.uuid4())
+    if options.exec:
+        return _handle_invoke_exec(region, harness_arn, "external-harness", None, options.with_(session_id=session_id))
+    logger = InvokeLogger(agent_name="external-harness", runtime_arn=harness_arn, region=region, session_id=session_id)
+    logger.log_prompt(options.prompt, session_id, options.user_id)
+    return _stream_harness_invoke(
+        region, harness_arn, session_id, options.prompt, options, logger, build_harness_base_opts(options)
+    )
+
+
+def _stream_harness_invoke(
+    region: str,
+    harness_arn: str,
+    session_id: str,
+    prompt: str,
+    options: InvokeOptions,
+    logger: InvokeLogger,
+    base_opts: dict[str, Any],
+) -> InvokeResult:
+    full = ""
+    try:
+        stream = invoke_harness(
+            region=region,
+            harness_arn=harness_arn,
+            runtime_session_id=session_id,
+            messages=[{"role": "user", "content": [{"text": prompt}]}],
+            bearer_token=options.bearer_token,
+            **base_opts,
+        )
+        for event in stream:
+            if options.verbose:
+                print(_compact(event), flush=True)
+                continue
+            kind = event.get("type")
+            if kind == "contentBlockDelta":
+                delta = event.get("delta") or {}
+                if delta.get("type") == "text":
+                    text = delta.get("text") or ""
+                    full += text
+                    if not options.json:
+                        _write(text)
+            elif kind == "messageStop":
+                if not options.json and event.get("stopReason") not in ("tool_use", "tool_result"):
+                    _write("\n")
+            elif kind == "error":
+                message = f"{event.get('errorType')}: {event.get('message')}"
+                logger.log_error(RuntimeError(message), "stream error")
+                if options.json:
+                    return result(False, error=RuntimeError(message))
+                _write(f"\nError: {event.get('message')}\n", sys.stderr)
+
+        logger.log_response(full)
+        if options.json:
+            return result(
+                True,
+                response=_compact({"text": full, "sessionId": session_id}),
+                sessionId=session_id,
+                logFilePath=logger.log_file_path,
+            )
+        return result(True, sessionId=session_id, logFilePath=logger.log_file_path)
+    except Exception as exc:  # noqa: BLE001
+        logger.log_error(exc, "harness invoke failed")
+        return result(False, error=RuntimeError(f"Harness invoke failed: {exc}"), logFilePath=logger.log_file_path)
+
+
+def _handle_harness_invoke(
+    project: Any, target_state: Any, target_config: Any, selected: str, options: InvokeOptions
+) -> InvokeResult:
+    entries = project.harnesses or []
+    if not entries:
+        return result(False, error=ValidationError("No harnesses defined in configuration"))
+
+    harness_name = options.harness_name
+    if not harness_name:
+        if len(entries) > 1:
+            names = ", ".join(h.name for h in entries)
+            return result(
+                False, error=ValidationError(f"Multiple harnesses found. Use --harness to specify one: {names}")
+            )
+        harness_name = entries[0].name
+
+    if not any(h.name == harness_name for h in entries):
+        names = ", ".join(h.name for h in entries)
+        return result(False, error=ResourceNotFoundError(f"Harness '{harness_name}' not found. Available: {names}"))
+
+    resources = target_state.resources if target_state else None
+    harness_state = ((resources.harnesses if resources else None) or {}).get(harness_name)
+    if not harness_state:
+        return result(
+            False,
+            error=ValidationError(
+                f"Harness '{harness_name}' is not deployed to target '{selected}'. Run `agentcore deploy` first."
+            ),
+        )
+
+    session_id = options.session_id or str(uuid.uuid4())
+    region = target_config.region
+    options = options.with_(session_id=session_id)
+
+    harness_spec = None
+    try:
+        harness_spec = ConfigIO().read_harness_spec(harness_name)
+    except Exception:  # noqa: BLE001, S110 - spec read is best-effort
+        pass
+
+    if harness_spec is not None and harness_spec.authorizer_type == "CUSTOM_JWT" and not options.bearer_token:
+        if _deps.can_fetch_harness_token(harness_name):
+            try:
+                token = _deps.token_of(_deps.fetch_harness_token(harness_name, deploy_target=selected))
+                options = options.with_(bearer_token=token)
+            except Exception as exc:  # noqa: BLE001
+                return result(
+                    False,
+                    error=ValidationError(
+                        f"CUSTOM_JWT harness requires a bearer token. Auto-fetch failed: {exc}\n"
+                        "Provide one manually with --bearer-token."
+                    ),
+                )
+        else:
+            return result(
+                False,
+                error=ValidationError(
+                    f"Harness '{harness_name}' is configured for CUSTOM_JWT but no bearer token is available.\n"
+                    "Either provide --bearer-token or re-add the harness with --client-id and --client-secret to "
+                    "enable auto-fetch."
+                ),
+            )
+
+    if not options.prompt:
+        return result(
+            False, error=ValidationError('No prompt provided. Usage: agentcore invoke --harness <name> "your prompt"')
+        )
+
+    if options.exec:
+        return _handle_invoke_exec(region, harness_state.harness_arn, harness_name, selected, options)
+
+    logger = InvokeLogger(
+        agent_name=harness_name, runtime_arn=harness_state.harness_arn, region=region, session_id=session_id
+    )
+    logger.log_prompt(options.prompt, session_id, options.user_id)
+    base_opts = build_harness_base_opts(options, harness_spec.model if harness_spec is not None else None)
+    out = _stream_harness_invoke(
+        region, harness_state.harness_arn, session_id, options.prompt, options, logger, base_opts
+    )
+    return {**out, "targetName": selected}