docs: module 7 walkthrough — adding a gateway target

[Robobc]

What

Module 7 is where the platform stops being something you deployed and becomes something you extend — and it had narration but no instructions. docs/GATEWAY_TARGETS.md fills that in, written from the two targets that already work in this repo rather than invented: the web-search built-in connector and the sample-tool Lambda.

Covers both paths with a table that decides which one you want:

	Built-in connector	Lambda target
You write	nothing	handler + tool schema
Good for	capabilities AWS operates	your APIs, data, logic

The details it spends space on

These are the ones that cost real debugging here, so they're called out rather than left to be rediscovered:

• The connector config only survives synth via add_property_override — the L1 property mapping predates connector targets and silently drops the key, so the target deploys with no connector and the tool simply never appears.
• A connector needs its own action on the gateway role (bedrock-agentcore:InvokeWebSearch on arn:…:aws:tool/web-search.v1 — literal aws where an account id goes). Missing it deploys clean and fails at call time.
• Connectors are regional — gate them like app.py does instead of failing the deploy elsewhere.
• A Lambda tool's name arrives in the context, not the event: context.client_context.custom["bedrockAgentCoreToolName"] as <target>___<tool>, and the handler must dispatch on the suffix.
• tool_schema uses CloudFormation PascalCase, not MCP's JSON casing.
• Description is read by a model deciding whether to call the tool. Write it for that reader.

It also answers what a participant hits immediately after: the default orchestrator pattern has no tools, so proving "an agent uses my tool" needs a tool-consuming pattern; and a new tool inherits the gateway's opt-in controls (Cedar names tools <Target>___<tool>, the egress interceptor masks its output too).

Verified

• Every claim checked against the code it describes: handler context key, tool_configs shape, the gateway_stack override, the IAM action, the region gate.
• Links and cross-file anchors resolve.
• check-workshop-flow passes — narration is sed-extracted, so the MODULE_EXPLAIN[7] edit had to stay one physical line — and the migration dry run prints module 7.
• pytest 115 passed.

[github-actions]

Commit: a5d3ff1 | Updated: 2026-08-19 19:43:11 UTC

Security Scan Results

Scanner	S	C	H	M	L	I	Time	Action	Result	Thresh
bandit	0	0	0	0	0	0	740ms	0	PASSED	MED (g)
cdk-nag	0	0	0	0	0	0	6.4s	0	PASSED	MED (g)
cfn-nag	0	0	0	0	0	0	9ms	0	PASSED	MED (g)
checkov	0	0	0	0	0	0	5.2s	0	PASSED	MED (g)
detect-secrets	0	0	0	0	0	0	641ms	0	PASSED	MED (g)
grype	0	0	0	0	0	0	1m 1s	0	PASSED	MED (g)
npm-audit	0	0	0	0	0	0	173ms	0	PASSED	MED (g)
opengrep	0	0	0	0	0	0	16.7s	0	PASSED	MED (g)
semgrep	0	0	0	0	0	0	<1ms	0	MISSING	MED (g)
syft	0	0	0	0	0	0	2.2s	0	PASSED	MED (g)