fix(bma): pass the Gateway to BMA as connector_id

[siwachabhi]

Description

client.py in the Bedrock Managed Agents (BMA) template sends a Gateway tool that BMA rejects. With --gateway, the session fails:

Error code: 400 - {'error': {'code': 'validation_error', 'message': "Invalid 'agent.tools[0]': value is not valid under any of the schemas listed in the 'oneOf' keyword.", 'param': 'agent.tools[0]', 'type': 'invalid_request_error'}}

The AWS mcp tool identifies the Gateway by its ARN in connector_id. It has no transport field, and BMA removed the required field. BMA calls the Gateway from the service side with the session role, which already has bedrock-agentcore:InvokeGateway on gateway/*.

Changes:

• client.py sends {"type": "mcp", "server_label": "team_tools", "connector_id": <Gateway ARN>}. --gateway takes the Gateway ARN.
• The extra input asks the agent to list the Gateway tools, so it works with any Gateway. The old input asked for documentation and runbook tools that only one sample Gateway has.
• README.md tells the user to give the ARN, to use the flag only for a new session, and that the Gateway must support MCP version 2025-03-26. Without it, the agent gets no Gateway tools and BMA shows no error.

Related Issue

No issue. A user reported the 400 error during the BMA preview.

Documentation PR

The AgentCore developer guide page runtime-get-started-bma gets a matching change in a separate internal docs review.

Type of Change

• Bug fix

Testing

• I ran npm run test:unit (441 files, 6352 tests pass). I did not run npm run test:integ.
• I ran npm run typecheck
• I ran npm run lint (0 errors, 35 warnings that existed before)
• I ran npm run test:update-snapshots and committed the updated snapshots

End-to-end test in us-east-1 with CLI v0.31.1: a BMA project, a Gateway from agentcore add gateway --protocol-type MCP --authorizer-type AWS_IAM, and a Lambda target that returns a value the model cannot guess.

Case	Result
Old tool (required, connection_origin, transport)	400 oneOf error
connector_id only, environment: none	The agent calls the tool and returns the exact value
connector_id, Runtime environment	Same
connector_id + required: true	400 oneOf error
connector_id + connection_origin: "service"	Works; the field is not needed
Gateway with no version list (CLI default)	Works
Gateway with supportedVersions: ["2025-11-25"] only	No error, but the agent has no Gateway tools
Gateway with ["2025-11-25", "2025-03-26"]	Works
This template's client.py --runtime <ARN> --gateway <Gateway ARN>	The skill runs, and the agent lists the Gateway tool

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works (the snapshot covers the template; no Python test exists for client.py)
• I have updated the documentation accordingly
• My changes generate no new warnings

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Small, self-contained update to the vended BMA sample client:

• client.py switches the Gateway tool from the old transport.server_url + connection_origin: service shape to the newer connector_id: <gateway ARN> form, and updates --gateway's help text accordingly.
• README.md is updated to tell users to pass the Gateway ARN and documents the 2025-03-26 MCP protocol-version caveat (silent empty tool list if the Gateway doesn't advertise it).
• The assets.snapshot.test.ts.snap snapshot is updated to match both files.

I verified agentcore deploy does emit the gateway ARN in its output (actions.ts constructs the line from gateway.gatewayArn), so the README's "ARN from the output of agentcore deploy" is accurate. (Side note, not for this PR: that line is still labeled Gateway URLs: in src/cli/commands/deploy/actions.ts:853 even though it prints ARNs — worth a follow-up but out of scope here.)

No telemetry considerations — this is content inside a vended Python sample. LGTM.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	41.6%	15969 / 38384
🔵	Statements	40.85%	17036 / 41697
🔵	Functions	35.55%	2744 / 7718
🔵	Branches	34.62%	10666 / 30805

Generated in workflow #4542 for commit c2d17d6 by the Vitest Coverage Report Action

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)