From ccf3377952c8341103eefe9c13b848fe3fcddd6e Mon Sep 17 00:00:00 2001 From: Evelyn Xu Date: Wed, 20 May 2026 17:44:41 -0700 Subject: [PATCH] Close gap in botocore model registration onboarding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tightens the AWS Transform Agent Toolkit power's onboarding so users can't silently end up without registered botocore service models — the symptom that surfaces much later as `Unknown service: 'transformagenticservice'`. Two compounding root causes, both fixable in docs and mcp.json: 1. No version floor on installs. Users who installed before May 13 (when only the v0.0.1 name-reservation placeholder existed on PyPI) ended up with a package that imports but ships no botocore model JSONs, so `aws configure add-model` had nothing to point at. 2. No verification step. `aws configure add-model` exits 0 even when the source path is empty, so users only discovered the failure at deploy time. Changes: - POWER.md Step 2: install line now uses `pip install --upgrade '...>=1.0.0'` so users on placeholder v0.0.1 are pulled forward and new users skip it entirely. Adds an `importlib.metadata.version` print to make the resolved version visible. Adds a boto3 sanity check (`Models OK`) immediately after `aws configure add-model` that fails fast with `UnknownServiceError` if registration didn't take. Adds a one-line clarification that host-level model registration is sufficient for the uvx-launched MCP server. - POWER.md Step 5 + mcp.json: pins `agent-builder-mcp-aws-transform>=1.0.0` on the uvx args so Kiro re-resolves to a real release on next launch. Adds guidance on `uv cache clean --force` for the rare case where a previous resolution is still cached. - troubleshooting.md entry 30: fallback recovery recipe covering the three symptoms in the report, with explicit cross-reference back to Step 2 commands and a note correcting the uvx-isolation misconception. --- aws-transform-agent-toolkit/POWER.md | 50 ++++++++++++++----- aws-transform-agent-toolkit/mcp.json | 2 +- .../steering/troubleshooting.md | 32 ++++++++++++ 3 files changed, 70 insertions(+), 14 deletions(-) diff --git a/aws-transform-agent-toolkit/POWER.md b/aws-transform-agent-toolkit/POWER.md index de7e14d..a208667 100644 --- a/aws-transform-agent-toolkit/POWER.md +++ b/aws-transform-agent-toolkit/POWER.md @@ -32,36 +32,42 @@ Before using this power, ensure the following are installed and configured: ### Step 2: Install AWS Transform Agent SDK -Install the SDK from PyPI into a virtual environment: +Install the SDK from PyPI into a virtual environment. The `--upgrade` flag plus the `>=1.0.0` floor ensures users on an older release are pulled forward to the latest stable and never land on the v0.0.1 name-reservation placeholder. +macOS/Linux: ```bash cd python3 -m venv .venv && source .venv/bin/activate -pip install agent-builder-sdk-aws-transform \ - agent-builder-agentic-mcp-aws-transform \ - agent-builder-types-aws-transform \ - agent-builder-mcp-client-aws-transform +pip install --upgrade \ + 'agent-builder-sdk-aws-transform>=1.0.0' \ + 'agent-builder-agentic-mcp-aws-transform>=1.0.0' \ + 'agent-builder-types-aws-transform>=1.0.0' \ + 'agent-builder-mcp-client-aws-transform>=1.0.0' ``` Windows PowerShell: ```powershell cd py -3 -m venv .venv; .venv\Scripts\Activate.ps1 -pip install agent-builder-sdk-aws-transform ` - agent-builder-agentic-mcp-aws-transform ` - agent-builder-types-aws-transform ` - agent-builder-mcp-client-aws-transform +pip install --upgrade ` + 'agent-builder-sdk-aws-transform>=1.0.0' ` + 'agent-builder-agentic-mcp-aws-transform>=1.0.0' ` + 'agent-builder-types-aws-transform>=1.0.0' ` + 'agent-builder-mcp-client-aws-transform>=1.0.0' ``` -**Verify installation:** +**Verify installation and version:** ```bash python3 -c "import agent_builder_sdk; print('SDK OK')" +python3 -c "from importlib.metadata import version; print('SDK version:', version('agent-builder-sdk-aws-transform'))" ``` +The printed version must be `1.0.0` or higher. If you see `0.0.1`, re-run the install command above — that release is a placeholder and ships without the botocore models. + **Register botocore service models:** -The SDK ships with custom botocore service models that must be registered before use: +The SDK ships with custom botocore service models that must be registered before use. `aws configure add-model` writes the JSONs to `~/.aws/models/`, which boto3 reads regardless of which virtualenv (or `uvx` environment) the client runs in — host registration is sufficient for the MCP server too. macOS/Linux: ```bash @@ -79,7 +85,15 @@ aws configure add-model --service-name atxagentregistryexternal --service-model aws configure add-model --service-name transformagenticservice --service-model "file://$SDK_MODELS\transformagenticservice\2018-05-10\service-2.json" ``` -**CRITICAL**: Without these models, the SDK will fail at runtime with `Unknown service: 'transformagenticservice'`. +**Confirm both models are resolvable by boto3:** + +```bash +python3 -c "import boto3; boto3.client('transformagenticservice', region_name='us-east-1'); boto3.client('atxagentregistryexternal', region_name='us-east-1'); print('Models OK')" +``` + +This forces boto3 to load each service model. If the JSONs aren't in `~/.aws/models/` or the SDK install was the placeholder, this raises `UnknownServiceError` immediately — surface it now rather than discover it during a real registration call. + +**CRITICAL**: Without these models, the SDK will fail at runtime with `Unknown service: 'transformagenticservice'`. See `steering/troubleshooting.md` for recovery steps if either verification command fails. ### Step 3: Set up IAM roles @@ -156,7 +170,7 @@ The MCP server is installed via `uvx` (see `mcp.json`). To pass environment vari "mcpServers": { "aws-transform-agent-toolkit": { "command": "uvx", - "args": ["agent-builder-mcp-aws-transform"], + "args": ["--from", "agent-builder-mcp-aws-transform>=1.0.0", "agent-builder-mcp"], "env": { "AWS_PROFILE": "my-profile", "AWS_REGION": "us-east-1" @@ -170,6 +184,16 @@ The MCP server is installed via `uvx` (see `mcp.json`). To pass environment vari - `AWS_PROFILE`: AWS CLI profile to use for credentials (set via `aws configure` or `aws sso login`) - `AWS_REGION`: AWS region for the AWS Transform (defaults to us-east-1) +The `>=1.0.0` floor on the package spec prevents `uvx` from resolving to the v0.0.1 placeholder. Because the spec changed, `uvx` will re-resolve on next launch — for most users a Kiro restart is enough. + +If a previous resolution is still cached and you suspect the MCP server is stuck on an old version, evict it and restart Kiro: + +```bash +uv cache clean --force agent-builder-mcp-aws-transform +``` + +Then quit and relaunch Kiro. `--force` removes cache files while Kiro's MCP server may still reference them; the in-memory server keeps working but may fail on a lazy load, which the relaunch resolves. If you'd prefer not to use `--force`, quit Kiro first, then run `uv cache clean agent-builder-mcp-aws-transform` (without `--force`). + Restart Kiro after making changes. ## Deployment Automation diff --git a/aws-transform-agent-toolkit/mcp.json b/aws-transform-agent-toolkit/mcp.json index cd95d7d..cd61641 100644 --- a/aws-transform-agent-toolkit/mcp.json +++ b/aws-transform-agent-toolkit/mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "aws-transform-agent-toolkit": { "command": "uvx", - "args": ["--from", "agent-builder-mcp-aws-transform", "agent-builder-mcp"] + "args": ["--from", "agent-builder-mcp-aws-transform>=1.0.0", "agent-builder-mcp"] } } } diff --git a/aws-transform-agent-toolkit/steering/troubleshooting.md b/aws-transform-agent-toolkit/steering/troubleshooting.md index ed9ec3a..7d5ff7a 100644 --- a/aws-transform-agent-toolkit/steering/troubleshooting.md +++ b/aws-transform-agent-toolkit/steering/troubleshooting.md @@ -39,6 +39,7 @@ description: "Field-tested troubleshooting guide for common AWS Transform agent | 27 | ATX_CHAT messaging undocumented | Chat messages don't appear | Use A2A format with `extensions` + `userSelection: "jobCreator"` (see orchestrator-patterns.md) | | 28 | Background execution undocumented | Orchestrator exceeds delayed_timeout | Spawn daemon thread from LLM tool | | 29 | S3 connector auth denied | `Partner not authorized to access this type of connector` | Fall back to direct S3 tools; request connector access from AWS Transform team | +| 30 | Stale SDK install or `uvx` cache | `Models OK` check raises `UnknownServiceError`, MCP server reports placeholder v0.0.1, or `pip` reports `Package(s) not found` | Re-run upgrade install + `aws configure add-model`; for the MCP server, bust the `uvx` cache once | ## Detailed Issues @@ -192,6 +193,37 @@ Forward-looking field for A2A agent discovery. Required by `PublishAgentVersion` **Cause:** Publisher not authorized for S3 connector type at AWS Transform level. `list_s3_connectors()` succeeds but data plane calls fail. **Fix:** Fall back to direct S3 tools (`download_s3_file`/`upload_s3_file`). Contact AWS Transform team to request S3 connector authorization. Always register both connector and direct S3 tools. +### 30. Stale SDK Install or `uvx` Cache + +**Symptom:** Any of the following: +- The `Models OK` verification command in onboarding raises `botocore.exceptions.UnknownServiceError: Unknown service: 'transformagenticservice'` (or `'atxagentregistryexternal'`). +- `python3 -c "from importlib.metadata import version; print(version('agent-builder-sdk-aws-transform'))"` prints `0.0.1`. +- The MCP server reports the placeholder version, or `pip` reports `Package(s) not found: agent-builder-mcp-aws-transform`. + +**Cause:** The pinned floors and `--upgrade` flag in onboarding prevent this on a clean machine. You'll only hit it if the SDK was installed before May 13 (when the v0.0.1 name-reservation placeholder was the only release on PyPI), or if a previous `uvx` invocation cached an old resolution. + +**Fix:** + +1. Re-run the upgrade install from `POWER.md` Step 2: + ```bash + pip install --upgrade \ + 'agent-builder-sdk-aws-transform>=1.0.0' \ + 'agent-builder-agentic-mcp-aws-transform>=1.0.0' \ + 'agent-builder-types-aws-transform>=1.0.0' \ + 'agent-builder-mcp-client-aws-transform>=1.0.0' + ``` +2. Re-run `aws configure add-model` for both services. The model JSONs only exist in the real release, so registration done against v0.0.1 was a no-op. +3. Re-run the `Models OK` boto3 sanity check. +4. For the MCP server, evict the cached resolution and restart Kiro: + ```bash + uv cache clean --force agent-builder-mcp-aws-transform + ``` + Then quit and relaunch Kiro — the new `mcp.json` args trigger a fresh `uvx` resolution on startup. + + *Optional:* If you'd prefer not to use `--force`, quit Kiro first, then run `uv cache clean agent-builder-mcp-aws-transform` (without `--force`). + +**Note:** `uvx` runs the MCP server in its own environment, but boto3 in that environment still reads service models from `~/.aws/models/`. Host-level `aws configure add-model` is sufficient — there is no need to register models inside the `uvx` environment. + ## Debugging Techniques ### CloudWatch Logs