fix(cli): Add --endpoint <name> to agentcore invoke, thread it ... (#986, #1554)

[aidandaly24]

Refs aws#986
Refs aws#1554

Issues

• Add --endpoint flag to agentcore invoke to target specific runtime endpoints aws/agentcore-cli#986 — agentcore invoke has no --endpoint flag, so users who create named runtime endpoints (version aliases like prod/staging via agentcore add runtime-endpoint) cannot target a specific endpoint from the CLI — invoke always hits the DEFAULT endpoint over SigV4. This is a missing-convenience feature gap, not a malfunction: a complete workaround exists today via --bearer-token (whose path already threads the endpoint qualifier) or by calling the API directly with qualifier.
• Support invoking a specific runtime endpoint with agentcore invoke --endpoint <name> aws/agentcore-cli#1554 — agentcore invoke can only ever hit a runtime's DEFAULT endpoint; there is no --endpoint flag, so named runtime endpoints created via agentcore add runtime-endpoint (e.g. control/treatment version aliases for A/B testing) cannot be smoke-tested directly. The only workaround is routing through a gateway. As a bonus, the same SigV4-qualifier gap means run eval --dataset --endpoint <name> against a SigV4 agent silently invokes DEFAULT while reading spans from the named-endpoint log group, so it can collect zero spans.

Root cause

The endpoint/qualifier is never carried from the CLI surface through resolution into the SigV4 SDK call. Verified at v0.20.2: no --endpoint registered on invoke (command.tsx:128-200); no endpoint field on InvokeOptions (types.ts:3-75); resolveInvokeTarget neither accepts nor returns one and ResolvedInvokeTarget has no endpoint field (resolve.ts:24-33,37-164); action.ts calls invokeAgentRuntimeStreaming (710) and invokeAgentRuntime (748) without passing endpoint; the SigV4 InvokeAgentRuntimeCommand is built without qualifier at agentcore.ts:362 and :458 even though InvokeAgentRuntimeOptions.endpoint exists (agentcore.ts:74) and the bearer-token path honors it via buildInvokeUrl (agentcore.ts:203-204). Premise real: deploy persists endpoints to runtimeEndpoints keyed ${agentName}/${endpointName} (outputs.ts:498); runtimes[].endpoints[name] modeled (agent-env.ts:345-346).

See root_cause field: verified at v0.20.2 HEAD e92c79a. invoke has no --endpoint (command.tsx/types.ts/action.ts), and the SigV4 InvokeAgentRuntimeCommand at agentcore.ts:362-370 & 458-466 omits the SDK-supported qualifier (models_0.d.ts:390-393); endpoint is only honored in the bearer path (buildInvokeUrl, agentcore.ts:201-205). Latent same-cause bug at scenario-executor.ts:75.

The fix

Add --endpoint <name> to invoke and plumb it through to the SDK qualifier. (1) Register the flag in command.tsx and add it to cliOptions/InvokeOptions (types.ts). (2) In resolveInvokeTarget (resolve.ts), accept an endpointName, validate it against project.runtimes[].endpoints[name] and/or deployedState...runtimeEndpoints[${agent}/${name}], and return it as endpoint/qualifier. (3) Pass endpoint into both invokeAgentRuntime (action.ts:748) and invokeAgentRuntimeStreaming (action.ts:710). (4) In agentcore.ts, add ...(options.endpoint && { qualifier: options.endpoint }) to the two SigV4 InvokeAgentRuntimeCommand builders (lines 362 and 458). DESIGN NOTE confirmed in SDK: the AWS InvokeAgentRuntime API targets endpoints via qualifier, which is the endpoint NAME, not the ARN (@aws-sdk/client-bedrock-agentcore models_0.d.ts:390-393: "an endpoint name that points to a specific version"); the runtime ARN is unchanged and deployed-state is used only to validate existence. The issue body's wording ("resolve the endpoint ARN and route to it") is technically loose. Also mirror this in the invoke TUI flow (useInvokeFlow.ts) for parity.

See the_fix field: register --endpoint on invoke, thread through InvokeOptions->action, AND set qualifier: options.endpoint on the SigV4 InvokeAgentRuntimeCommand (agentcore.ts:362-370,458-466). Reuse existing resolveEndpointName (cloudwatch.ts:9-11) for the AGENTCORE_RUNTIME_ENDPOINT fallback rather than re-implementing it at the command layer.

Files touched: src/cli/commands/invoke/command.tsx (register --endpoint, thread into InvokeOptions ~128-200, 425-462); src/cli/commands/invoke/types.ts (add endpoint to InvokeOptions ~3-75); src/cli/commands/invoke/resolve.ts (resolveInvokeTarget: accept+validate, return qualifier ~24-33,37-164); src/cli/commands/invoke/action.ts (pass endpoint into invokeAgentRuntime/Streaming ~710,748); src/cli/aws/agentcore.ts (add qualifier to both SigV4 InvokeAgentRuntimeCommand builders, lines 362 and 458). Optional parity: src/cli/tui/screens/invoke/useInvokeFlow.ts.

CLI only. src/cli/commands/invoke/command.tsx (register --endpoint, cliOptions type, options object); src/cli/commands/invoke/types.ts (add endpoint to InvokeOptions); src/cli/commands/invoke/action.ts (thread endpoint into invokeAgentRuntime / invokeAgentRuntimeStreaming, ~710-760); src/cli/aws/agentcore.ts (add qualifier: options.endpoint to InvokeAgentRuntimeCommand at 362-370 and 458-466 — the SigV4 fix; optionally MCP/A2A/AGUI builders too); reuse src/cli/aws/cloudwatch.ts resolveEndpointName for the env fallback. Note: run eval's --endpoint is registered in src/cli/commands/run/command.tsx (lines 92, 209), NOT commands/eval/ as the brief stated.

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

BEFORE (base HEAD, confirmed via git show): src/cli/commands/invoke/command.tsx has NO --endpoint flag, so agentcore invoke --endpoint prod "hi" would hit Commander's "error: unknown option '--endpoint'" (reproduced live: invoke --bogusflag -> "error: unknown option '--bogusflag'"); InvokeOptions in types.ts has NO endpoint field; and the SigV4 InvokeAgentRuntimeCommand at agentcore.ts ~362 (streaming) and ~459 (non-streaming) was constructed WITHOUT any qualifier, so every SigV4 invoke silently hit DEFAULT even though the bearer-token path already encoded ?qualifier= in buildInvokeUrl. AFTER (fix branch, rebuilt clean -> dist/cli/index.mjs): built invoke --help now lists --endpoint <name> Target a named runtime endpoint (version alias, e.g. prod/staging)...; node dist/cli/index.mjs invoke --endpoint prod "hi" parses cleanly (proceeds to "No agentcore project found" instead of "unknown option"). New unit file src/cli/aws/tests/agentcore-invoke-qualifier.test.ts (4 tests) proves both streaming and non-streaming commands carry qualifier:'prod'/'staging' when endpoint set and OMIT qualifier when unset. resolve.test.ts "named runtime endpoint resolution" (4 tests) proves: configured endpoints[].prod -> endpoint='prod'; deployed-only runtimeEndpoints['my-agent/staging'] -> endpoint='staging'; unknown 'nope' -> success:false ResourceNotFoundError "Endpoint 'nope' not found"; absent endpointName -> endpoint undefined. action.ts threads resolved+validated endpoint in

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.41%	13693 / 36595
🔵	Statements	36.67%	14557 / 39687
🔵	Functions	31.95%	2345 / 7339
🔵	Branches	31.28%	9060 / 28960

Generated in workflow #141 for commit e0bb133 by the Vitest Coverage Report Action