fix(registry): migrate Agent Registry from preview to GA

[omrsamer]

Agent Registry graduated out of AgentCore into its own AWS service. The rename is a silent break: the deprecated bedrock-agentcore-control model still exposes the Registry operations with the old descriptorType, so preview code keeps getting HTTP 200s under an IAM prefix it no longer has. Nothing raises UnknownOperation; the deploy-path auto-register is best-effort, so an AccessDenied under the old prefix surfaces only as a "skipped" log line.

Migration

• clients bedrock-agentcore{,-control} → agent-registry{,-control} (both sign as agent-registry); IAM prefix agent-registry:*
• descriptorType → recordType; enum MCP|A2A|CUSTOM|AGENT_SKILLS → MCP|AGENT|CUSTOM|SKILL (preview spellings kept as input aliases)
• descriptors reshaped to *.data / dataSchemaVersion; added mcpServer and agentSkillsDefinition builders
• SearchRegistryRecords → SearchDiscoverableRegistryRecords with the GA structured filter shape
• boto3 >= 1.43.66 hard floor — the first release carrying the service models

Verified against the live GA service

Not just the boto3 models: a throwaway registry, every descriptor builder submitted through the shipping adapter (loaded via importlib, deliberately fed under-specified input so the normalizers were exercised rather than bypassed), and the approval lifecycle end to end. 24/24 live checks. That found four defects the rename alone would have left in place.

1. Every redeploy silently failed to re-register. name + recordVersion is a uniqueness key and recordVersion is "1.0" for everything the platform registers, so the second deployment of an agent raised ConflictException inside the best-effort handler. The governance record stayed frozen at the first deployment's runtime ARN and endpoint — stale forever, nothing surfaced anywhere. register() is now an upsert, which needs the new agent-registry:UpdateRegistryRecord grant on the status_update step role. Updating content demotes APPROVED → DRAFT, so an upsert cannot slip changed content past an old approval.

2. available() reported a still-provisioning registry as usable. It returned True the instant GetRegistry succeeded, but a registry in CREATING/UPDATING/DELETING rejects CreateRegistryRecord. Enabling federation on a freshly created registry — the common sequence — therefore passed validation and raced into that conflict on first deploy. Now gated on READY, with registry_status() keeping "not READY" distinct from "could not ask"; POST /aws-config returns 409 instead of a 400 blaming the registryId.

3. Search could show a stale APPROVED badge. The data plane is a search index, not the record store: a record demoted to DRAFT keeps being served as APPROVED for 20+ minutes (measured, stable across polling — not eventual consistency catching up). Combined with the upsert, which demotes on every redeploy, this is reachable on the ordinary path. GET /aws-search now reconciles each hit's status against the control plane and reports status_authoritative: false — dropping status rather than serving the index's copy — when it cannot. Approval gating always read the control plane and was never affected; a new AST-level guard test keeps it that way.

4. Descriptor content contracts were wrong — each an outright rejection by the live schema validator, reported only as an unactionable descriptor-wide error:

descriptor	contract
a2aAgentCard	card needs url; each skill needs all of id/name/description/tags (empty tags ok, absent not)
mcpServer	server.json with a namespaced <namespace>/<server> name (a bare name is rejected), plus description and version
agentSkillsDefinition	must omit dataSchemaVersion entirely, unlike every other descriptor
tools / skills payloads	must be objects ({"tools": [...]}), never bare arrays

Under-specified input is normalized rather than forwarded. UpdateRegistryRecord also takes a different shape from Create — every branch and scalar leaf wrapped in an optionalValue patch envelope — which otherwise fails in botocore's client-side validation and never reaches AWS.

Also fixed

An unqueryable registry was indistinguishable from a rejected integration: gating swallowed every error into "nothing is approved", so an AccessDenied on ListRegistryRecords rendered as a 403 telling the operator their integrations had been rejected. Absent data and negative data are now distinct (RegistryQueryFailed → 503). Gating stays fail-closed for a successful query that finds no approval.

IAM is proven, not asserted

iam:SimulateCustomPolicy against the synthesized template: the API role allows all 9 operations the adapter's call sites make; the step role allows 6 and denies 3. Those 3 denials are correct for its code path (auto-register only reads status, creates, looks up, updates) and are now pinned by a test — granting the deploy pipeline approval permissions would let a record approve itself.

The dependency floor is verified in the built artifact, not just the pin: backend/lib/ ships verbatim into the Lambda and PYTHONPATH shadows the runtime's boto3, so the bundle was rebuilt and confirmed to resolve boto3 1.43.81 and construct both GA clients (15 control ops, 3 data ops).

Gates

Both ruff gates, 1286 backend tests, 47 infra tests + cdk synth, tsc -b, 253 vitest, eslint (0 errors), npm run build. The same change is applied byte-identically in Agentic-ai-self-service (aws-samples/sample-ai-agent-factory#fix/agent-registry-ga).

Not covered: no full cdk deploy + UI deploy was run, so residual risk is wiring-level rather than registry-level; the policy simulation and bundle verification are what narrow it to that.

🤖 Generated with Claude Code