Build and deploy your first AWS Transform agent using Kiro
The AWS Transform Agent Toolkit in Kiro scaffolds, builds, and deploys a working agent from a written spec. This walkthrough builds a simple one end to end.
Series: Stop Being The Runtime - Custom Agents on AWS Transform (3 articles)
- 2Build and deploy your first AWS Transform agent using Kiro This article
This walkthrough gets you a deployed Hello World agent in your AWS account in about fifteen minutes. You start with a prompt that describes what you want; from there, you and Kiro work through the build, confirm a few registration fields, and approve the deploy. The finished agent collects a name and city in chat, saves the result as a downloadable artifact, and reads it back on request.
Prerequisites
- AWS Transform configured in your AWS account
- If you have multiple AWS profiles, AWS Transform must be your default profile
- Kiro installed
This walkthrough deploys a container image and an Amazon Bedrock AgentCore runtime in your AWS account. Use a development or sandbox account.
Install the Agent Toolkit Power
Install the AWS Transform Agent Toolkit power in Kiro.
If the link doesn't work in your setup, open Kiro's Powers marketplace and search "AWS Transform Agent Toolkit" instead.
Once installed, the power shows up in your Kiro sidebar.
The AWS Transform Agent Toolkit installed in Kiro, ready to activate.
Activate the power
Click "Try Power." Kiro reads its steering documents, checks your local setup (Python, Docker or Finch, AWS credentials), and shows you what the toolkit can do: search AWS Transform documentation, build agents, package and deploy them, register them with the platform, and manage skills.
Kiro runs a quick documentation search to prove the connection works, then lands on a "What's next?" screen with a few starting options.
After activation, Kiro validates your setup and explains what the toolkit can do. Note the file tree: no agent code yet, it waits for you.
Build your Hello World agent
The prompt in full:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
Build me a Hello World agent for AWS Transform.
## What this agent does
1. Greets the user and asks for their name and city
2. User provides their name and city in chat
3. Agent compiles a short profile card (plain text)
4. Saves the profile card as an artifact
5. If the user asks the agent to read back their profile, it retrieves and displays the artifact
## Artifacts
Save the profile card as a customer-visible workspace artifact so the user can download it from the Artifacts tab.
Required upload parameters:
| Parameter | Required value | Why |
|---|---|---|
| `visibility` | `EXTERNAL` | Only EXTERNAL artifacts appear in the user-facing Artifacts tab. INTERNAL artifacts are stored but hidden from the user. |
| `categoryType` | `CUSTOMER_OUTPUT` | The category for user deliverables. Do NOT use `AGENT_OUTPUT`. |
| `fileType` | `TXT` | Profile card is plain text. |
| `label` | `profile-card.txt` | Download filename. |
The default `ArtifactStore.upload_artifact` helper uploads with INTERNAL visibility. To make the profile card customer-visible in the Artifacts tab, use the EXTERNAL upload flow directly:
1. `client.create_artifact_upload_url(artifactReference={"artifactType": {"categoryType": "CUSTOMER_OUTPUT", "fileType": "TXT"}}, contentDigest={"sha256": digest}, visibility="EXTERNAL", label="profile-card.txt", requestContext=...)`
2. `client.get_artifact_metadata(...)`, then PUT the bytes to the presigned URL
3. `client.complete_artifact_upload(artifactId=..., requestContext=...)`
Reuse `calculate_digest` (base64 sha256) and `upload_from_presigned_url` from `agent_builder_sdk.agentic_framework.common`, and build the request context from the `WORKSPACE_ID` / `JOB_ID` / `AGENT_INSTANCE_ID` env vars plus the runtime auth token (subclass `ArtifactStore` to reuse its `_create_request_context()`).
## Reporting behavior
Report artifact outcomes truthfully based on the actual tool result. Only claim the profile card was saved to the Artifacts tab when the upload returned a real `artifact_id`. If the upload did not happen (for example, missing workspace context), say so plainly and state the reason. NEVER fabricate an explanation such as the file being saved "in the system" but hidden from the user's view.
## Deployment requirements
- Agent type: ORCHESTRATOR_AGENT
- a2aSupported: true
- jobOrchestrator: true
- Chat UI label: "Hello World"
- Use AsyncBaseOrchestrator base class
- Model: us.anthropic.claude-sonnet-4-5-20250929-v1:0
- Build locally with Finch or Docker (ARM64) rather than CodeBuild
- Container base: python:3.11-slim
## Dockerfile requirements
The container image MUST:
1. Base on python:3.11-slim, ARM64
2. Register the botocore service models inside the container (atxagentregistryexternal and transformagenticservice)
3. Create the Agentic MCP shim at /home/amazon/AgentBuilderAgenticMCP/bin/agent-builder-agentic-mcp (an executable that runs python -m agent_builder_agentic_mcp "$@")
4. Expose port 8080 and provide a health check
## What this agent is NOT
- It does NOT interact with any AWS service beyond the AWS Transform artifact store
- It does NOT register in the marketplace
## Registration: immutable fields
These fields CANNOT be changed after registration. Get them right on the first pass:
| Field | Required value |
|---|---|
| `a2aSupported` | `true` |
| `type` | `ORCHESTRATOR_AGENT` |
| `jobOrchestrator` | `true` |
| `chatUILabel` | `Hello World` |
## Publish: a2aSupported again
`a2aSupported` must ALSO be set to `true` in a second place: the `agentCard.capabilities` block of the `publish-agent-version` call. This is separate from the registration metadata flag above. Set it in both places so the agent receives chat input; if it is set only in registration and not here at publish time, the agent passes its health check but will not process messages.
```json
{
"capabilities": {
"restartable": true,
"a2aSupported": true,
"legacyDashboard": false,
"legacyTaskLink": false,
"webAppV2": true,
"legacyRestartable": false,
"extensions": [...]
}
}
```Every field in that prompt is deliberate. Two deserve their own note: the model you pin, and the four fields you cannot change after registration.
A note on models
The prompt pins one model:
us.anthropic.claude-sonnet-4-5-20250929-v1:0. That was a current cross-region inference profile in July 2026, and it's the one this walkthrough was built and tested against. Model IDs change over time, though, and an agent built on a retired model can fail without an obvious error, so pick a current one before you build.List the inference profiles available in your account:
1
aws bedrock list-inference-profiles --region us-east-1Use one of the returned IDs as the model in the prompt. Note the region prefix (
us.) on each ID: these are cross-region inference profiles, and that prefix is what makes them work. (A bare ID without it, like anthropic.claude-sonnet-4-5-20250929-v1:0, returns a ValidationException about on-demand throughput.)Hand it to Kiro
Paste the whole prompt into the Kiro chat and send it. Kiro reads the toolkit's steering docs, generates the agent code, and builds out the project. When it finishes, you have a complete agent:
1
2
3
4
5
6
7
8
agent/
├── Dockerfile # orchestrator template: botocore models + MCP shim baked in
├── requirements.txt # SDK deps pinned to validated versions
└── src/orchestrator/
├── app.py # AgentRuntimeServer(delayed_timeout=3600); model us.anthropic.claude-sonnet-4-5
├── profile_tools.py # save_profile_card / read_profile_card
├── artifact_uploader.py # ArtifactStore subclass forcing EXTERNAL visibility
└── prompts/system_prompt.mdBefore you deploy: the verification checklist
These registration fields are locked in once Kiro registers the agent. Verify them before you approve that step.
| Field | Required value | Why it matters |
|---|---|---|
a2aSupported | true | Set this to true (in both places, below) so the agent receives chat messages |
type | ORCHESTRATOR_AGENT | The orchestrator type is the one that sends chat responses to the workspace |
jobOrchestrator | true | Set this to true so the agent appears as invokable in the workspace UI |
chatUILabel | Your chosen display name | This is permanent, so pick the display name you want before registering |
These fields define the agent's identity, so plan them before you register. If you do need to change one, deregister that agent first, then register the corrected one. Registering a corrected agent without removing the old one leaves two similarly labeled entries in the Create Job picker, so get the four fields right on the first pass.
Kiro stops at the deployment boundary and asks before creating any cloud resources.
Deploy
Kiro builds the container locally with Finch or Docker, pushes it to Amazon ECR , creates the Amazon Bedrock AgentCore runtime, and registers the agent with the AWS Transform Agent Registry. When it finishes, the agent shows up in the AWS Transform console's agent list.
Run it
Open a workspace in the AWS Transform console and start a job with the Hello World agent.
Create a workspace in the AWS Transform console to run the agent in.
Inside the workspace, start a job with the Hello World agent.
Start the conversation with a quick message like "hello." The agent greets you and asks for your name and city.
Send a message to start the conversation. The agent greets you and asks for your name and city.
Answer in chat, and it composes a profile card, saves it as an artifact, and confirms the save with the artifact ID. The card shows up in the Artifacts tab as a downloadable file.
The agent's chat confirmation and the saved artifact, side by side. The artifact ID in the chat matches the entry in the Artifacts tab.
Download the artifact and it holds exactly what the agent showed you.
The downloaded profile card. The file is named for its artifact ID, and its contents match what the agent reported.
Ask the agent to read your profile back, and it retrieves the artifact and displays it.
Read-back: the agent retrieves the saved card, citing the same artifact ID from the save. It reports the source truthfully rather than guessing.
What just happened
You installed a power, gave it a prompt, and ended up with a deployed agent that collects input in chat and saves a downloadable artifact, without writing a build script or wiring up any infrastructure yourself.
Clean up
This walkthrough deploys real resources, so remove them when you're done to avoid ongoing cost. Delete in this order:
- Deregister the agent from the AWS Transform Agent Registry (
deregister-agent). - Delete the Amazon Bedrock AgentCore runtime (
delete-agent-runtime). - Delete the Amazon ECR repository that holds the agent image (
delete-repository).
The toolkit can run these for you from Kiro, or you can run the CLI calls yourself.
Get started
- Configure your account for AWS Transform and install Kiro
- Install the Agent Toolkit Power in Kiro , then activate it and let it validate your setup
- Paste the Hello World prompt from this post
- Check the verification checklist before Kiro registers the agent
- Deploy and run it in a workspace
Conclusion
The prompt in this post is a working starting point. It gets you a deployed agent that saves an artifact and reads it back, and it isolates the four fields you can't change after registration.
In the next post in this series, I'll build an agent you can copy and deploy to your own AWS account to do real work, not just a Hello World.
Further reading
- AWS Transform developer tools guide - what's available beyond the Kiro power
- Building and running your custom agents on AWS Transform - Post 1 in this series, on when a skill graduates to a deployed agent
- What is AWS Transform? - the developer guide's service overview
This information is accurate as of July 2026. AWS Transform is an actively evolving service. Consult the reference documents linked above for the most current guidance.
Building agents on Transform? I'd like to hear about it. Find me on LinkedIn .
Series: Stop Being The Runtime - Custom Agents on AWS Transform (3 articles)
- 2Build and deploy your first AWS Transform agent using Kiro This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article