Editing your Hello World AWS Transform agent
This post shows you the basic file structure of your Hello World agent, walks you through modifying it to gather new and very important information, then gives you a prompt to have Kiro deploy the changes to AWS Transform.
Series: Stop Being The Runtime - Custom Agents on AWS Transform (3 articles)
- 3Editing your Hello World AWS Transform agent This article
Prerequisite: you've deployed the Hello World agent from the previous post .
In this post, we're going to do two things:
- Make changes to the agent we built in the previous post.
- Deploy those changes to AWS Transform so you can see the results.
While the Hello World agent is very simple, if you don't know what files control it then it is effectively a black box. Before you can change what it does, you need to know what's inside: which file holds its behavior, which holds its code, and which you can leave alone. So we'll open it up first, then change two files and redeploy.
When you finish, you'll have a foundational understanding of editing and updating agents in AWS Transform. As you build and deploy your own agents, this is the loop you'll return to whenever your needs change.
The files you'll work with
Here is the file structure of the Hello World agent:
1
2
3
4
5
6
7
8
9
10
agent/
├── Dockerfile
├── requirements.txt
└── src/
└── orchestrator/
├── app.py
├── artifact_uploader.py
├── profile_tools.py
└── prompts/
└── system_prompt.mdSix files. Two of them, the system prompt and the tools, are all we need to change for this example, so we'll start there. Then we'll walk the other four so you know what each one does.
The system prompt
File:
src/orchestrator/prompts/system_prompt.mdThis is behavior. This is personality. Most changes start here.
Open it and you'll find a Markdown file with four sections:
- What you do tells the agent its workflow: greet, ask for name and city, save the card, read it back on request.
- Tools lists what the agent can call and what each tool does.
- Reporting rules defines how the agent talks about tool results. (More on why this matters in the next section.)
- Style sets the tone: short, warm, easygoing.
Notice what this file is: plain Markdown, no config format, no YAML, no framework DSL. It's written in natural language and read by a model. No imports, no wiring. You change what the agent does by changing what you tell it to do.
The prompt also does not duplicate tool logic. It says "use
save_profile_card and report what it returns." It does not reimplement the upload flow. Separation of concerns: the prompt owns behavior, the tool code owns capability.The tools
File:
src/orchestrator/profile_tools.pyThis is where the agent gets capabilities beyond conversation.
Each tool is a Python function decorated with
@tool from the Strands Agents SDK :1
2
3
4
5
6
7
from strands import tool
def save_profile_card(name: str, city: str) -> dict:
"""Compile a plain-text profile card and save it as a customer-visible artifact.
...
"""The model reads the function signature, the type hints, and the docstring to decide when and how to call the tool. Typed arguments in, structured dict out. The return value tells the model (and through it, the user) what happened.
The reporting contract
This file's module docstring says something worth reading twice:
Reporting contract (enforced by the tool return values, not just the prompt).
Here's the pattern:
save_profile_card returns either {"saved": True, "artifact_id": "..."} or {"saved": False, "reason": "..."}. The system prompt then instructs the agent to relay these outcomes truthfully. Neither layer works alone:- The tool controls what happened. It never lies about whether the upload succeeded.
- The prompt controls what the agent says about what happened. It can't invent an artifact ID the tool didn't return.
This two-layer contract is how you build agents that report reliably. The tool enforces ground truth; the prompt enforces honest communication of that truth. You'll see this pattern in every well-built AWS Transform agent, not just this Hello World.
The files we don't need to change for this example
The remaining four files wire the agent together and package it. The change we're about to make doesn't touch them, so we won't edit them here. Don't mistake that for unimportant, though: as your agents grow, these are where you'll configure models, add tools and MCP clients, produce real deliverables, and pull in system dependencies. For a change this small, they just happen to stay put. Here's what each one does.
The wiring: app.py
This is where the prompt, the tools, and the model come together:
1
2
3
4
5
6
7
8
9
10
11
from agent_builder_sdk.agent_factory import create_default_async_orchestrator
from agent_builder_sdk.server.agent_runtime_server import AgentRuntimeServer
def agent_factory(mcp_client=None, storage_dir=None):
return create_default_async_orchestrator(
mcp_client=mcp_client,
storage_dir=storage_dir or "/tmp/orchestrator_agent",
system_prompt=load_system_prompt(),
custom_tools=[save_profile_card, read_profile_card],
model_id=MODEL_ID,
)create_default_async_orchestrator takes a prompt, a list of tools, and a model ID, and returns a configured agent. AgentRuntimeServer wraps it in an HTTP server that speaks the protocol AWS Transform expects.The artifact layer: artifact_uploader.py
This is a foundational file that manages artifacts created by your agent, or that your agent imports. It's part of what AWS Transform brings to the table, and you'll likely never need to change it.
The container: Dockerfile + requirements.txt
These package your agent into a container image that AWS Transform can run: installing the SDK, registering the service models the platform needs, and producing a reproducible build. This is core scaffolding that does all of the complex work of actually running your agent in AWS Transform, and for a change like this you won't touch them.
Enough talk, let's have some fun
Theory without practice is a blog post you read and forget. Let's add a field to the Name and City that the agent already requests.
Goal: Make the agent ask for the user's favorite pizza topping and include it on the profile card.
Two files change, then you redeploy.
Edit 1: The system prompt
Open
src/orchestrator/prompts/system_prompt.md and update the "What you do" section:1
2
3
4
5
6
7
## What you do
-1. Greet the user warmly and ask for their **name** and **city**.
-2. When the user provides their name and city, compile a short profile card.
+1. Greet the user warmly and ask for their **name**, **city**, and **favorite pizza topping**.
+2. When the user provides all three, compile a short profile card.
3. Save the profile card as a customer-visible artifact using the `save_profile_card` tool.Update the tool description in the same file:
1
2
3
4
## Tools
-- `save_profile_card(name, city)`: Compiles the plain-text profile card and uploads it...
+- `save_profile_card(name, city, pizza_topping)`: Compiles the plain-text profile card and uploads it...Edit 2: The tool
Open
src/orchestrator/profile_tools.py and add the parameter: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
-def build_profile_card_text(name: str, city: str) -> str:
+def build_profile_card_text(name: str, city: str, pizza_topping: str) -> str:
"""Compile the plain-text profile card."""
name = (name or "").strip()
city = (city or "").strip()
+ pizza_topping = (pizza_topping or "").strip()
return (
"=== Profile Card ===\n"
f"Name: {name}\n"
f"City: {city}\n"
+ f"Favorite pizza topping: {pizza_topping}\n"
"====================\n"
)
-def save_profile_card(name: str, city: str) -> dict:
+def save_profile_card(name: str, city: str, pizza_topping: str) -> dict:
"""Compile a plain-text profile card and save it as a customer-visible artifact.
Args:
name: The user's name.
city: The user's city.
+ pizza_topping: The user's favorite pizza topping.
"""
- card_text = build_profile_card_text(name, city)
+ card_text = build_profile_card_text(name, city, pizza_topping)Edit 3: Redeploy
Run the same deploy flow from Post 2 . With both files saved (Kiro marks them modified in the file tree), tell the Agent Toolkit power what you changed and ask it to redeploy, for example: "Rebuild and redeploy the Hello World agent with these changes." It rebuilds the container image with your changes, pushes it, and updates the runtime. The agent version increments; the registration stays the same.
Tell the Agent Toolkit power what you changed and ask it to redeploy. The same flow from Post 2, now carrying your changes.
And we're done. Kiro updated your existing agent using the AWS Transform Agent Toolkit. This is rapid iteration of your agent's code and capabilities.
See it live
Open a workspace in the AWS Transform console and start a new job with your Hello World agent.
Say hello. The agent now asks for your name, city, and favorite pizza topping, the field you just added.
After redeploy, the agent asks for all three fields. The favorite pizza topping is the field you just added.
Answer all three, and the agent saves an updated card to the Artifacts tab.
The saved card lands in the Artifacts tab, and the chat shows the same card carrying the new field.
Here's what the card says:
1
2
3
4
5
=== Profile Card ===
Name: Rusty
City: Seattle
Favorite pizza topping: pepperoni and hot honey
====================Download it and it matches what the agent displayed.
What we did here was make a simple change to a basic agent. But now that you understand the file structure and how the process works, you can make bigger changes on your own. Want the agent to refuse to make a card for anyone who puts pineapple on their pizza? You already know that's a prompt change and a tool change, and which file each one lives in.
As you build more complex agents, the interplay between the non-deterministic prompt and the deterministic tools is where the real work lives. The prompt decides what to say and when to act; the tools decide what actually happens and report back the truth. Getting that division right is what separates an agent that demos well from one you can actually depend on.
Get started
- Open the Hello World agent you deployed in Post 2 using Kiro with the AWS Transform Agent Toolkit
- Add a field to the system prompt and the tool (pizza topping, favorite color, whatever you want)
- Redeploy with the AWS Transform Agent Toolkit in Kiro and verify the change
- That's the loop: prompt, code, deploy, verify
Conclusion
The Hello World agent started this post as a black box. Now you've been inside it, changed what it does, and shipped that change to AWS Transform. It's not a black box anymore, and neither is the next one you build.
Next post, we build a more capable agent, one that goes well beyond a profile card.
Further reading
- AWS Transform developer tools guide - what's available beyond the Kiro power
- Strands Agents SDK - the
@tooldecorator and agent framework used in this post - 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)
- 3Editing your Hello World AWS Transform agent 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