Skip to content

Close gap in botocore model registration onboarding #133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HellcatOvO wants to merge 1 commit into
base: main
Choose a base branch
from
+70 −14
Open

Close gap in botocore model registration onboarding #133

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 37 additions & 13 deletions aws-transform-agent-toolkit/POWER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <user-project>
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 <user-project>
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
Expand All @@ -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

Expand Down Expand Up @@ -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"
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion aws-transform-agent-toolkit/mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
}
}
}
32 changes: 32 additions & 0 deletions aws-transform-agent-toolkit/steering/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
Loading