iTranslated by AI
Building AI-Powered Websites with Strands Agents
0. What I Want to Convey in This Article
What I want to convey in this article is that AI agents are becoming something that should be built-in from the beginning, rather than a "feature added later."
When I built the same "Mahitotsu-ya" application a year and a half ago, I treated AI as an "external service."
However, this time, while designing and implementing the same theme using new technologies, I felt that the era where we assume AI agents are built-in from the start has already arrived, which led me to write this article. Using the implementation with Strands Agents as an example, I would like to share my experience regarding what the design for integrating AI agents into an application looked like.
1. Introduction
System Overview
"Mahitotsu-ya" is a fictional Japanese confectionery website. In addition to providing product information, cart management, and order processing, this site integrates an AI-driven customer service feature.
Users ask questions in natural language, and the AI agent ("Banto-san" or Shop Manager) suggests appropriate products and even adds them to the cart. This agent is not just an FAQ bot, but a practical agent deeply integrated with the store's business systems.

"Mahitotsu-ya" Screenshot
Conversation Example: Interaction with the AI Agent
Below is a summary of an actual conversation held in the system. This agent accepts questions in natural language, selects and executes the appropriate tools, and autonomously presents alternatives if an error occurs.
Customer: "What are your recommended products?"
Banto-san: (Executes list_featured_products tool)
"We recommend Dorayaki (220 yen), Matcha Daifuku (280 yen), Yokan (350 yen), and Castella (420 yen)."
Customer: "Please pick some from those under 2000 yen and add them to the cart."
Banto-san: (Executes add_to_cart → Error: Matcha Daifuku is in-store only)
(Autonomously excludes Matcha Daifuku and re-executes → Success)
"I have added 2 Dorayaki, 2 Yokan, and 1 Castella to your cart for a total of 1,560 yen."
Customer: "Please process the payment by credit card."
Banto-san: "Please handle the payment yourself. You can proceed from the cart screen."
Points to note in this conversation:
- Context Understanding: Interpreted the pronoun "from those" correctly as the recently recommended product list.
- Autonomous Error Handling: After the first cart addition failure, it autonomously executed an alternative plan without asking the user for re-instructions.
- Permission Awareness: Recognized that payment is outside the Banto's scope of authority and explained it appropriately.
The complete conversation log from the actual system is provided below:
Complete Conversation Log
Customer: "What are your recommended products?"
Banto-san: "Certainly. I would be happy to guide you through our recommended products.
Please wait a moment.
(System Internal: Executes list_featured_products tool)
Thank you for waiting. We especially recommend these four items:
[Dorayaki] 220 yen
This is a masterpiece with plenty of homemade sweet bean paste sandwiched between fluffy dough.
[Matcha Daifuku] 280 yen
A popular item made by wrapping white bean paste in mochi dough kneaded with fragrant matcha.
[Yokan] 350 yen
This is a standard bean-paste Yokan with a rich flavor, known for its elegant sweetness.
[Castella] 420 yen
Our popular Castella, beloved for its moist texture and gentle sweetness."
Customer: "Please pick some from those under 2000 yen and add them to the cart."
Banto-san: "Certainly. I will select a well-balanced assortment for under 2000 yen.
(System Internal: Executes add_to_cart tool → Error occurred)
I apologize. It appears Matcha Daifuku is not available for online purchase.
I will prepare another combination instead.
(System Internal: Re-executes add_to_cart excluding Matcha Daifuku)
I have successfully added them to your cart.
[Cart Contents]
- Dorayaki x 2 (220 yen x 2 = 440 yen)
- Yokan x 2 (350 yen x 2 = 700 yen)
- Castella x 1 (420 yen)
Total: 1,560 yen
I have selected an assortment of our popular items. You can enjoy the distinct flavors of Dorayaki, Yokan, and Castella.
Does this look correct for your cart?"
Customer: "Please process the payment by credit card."
Banto-san: "I apologize. As the shop manager for our online store, I am here to assist you with product information and adding items to your cart, but the actual payment process must be completed by you on the payment screen.
[Payment Methods]
We offer the following payment methods:
- Credit Card
- Cash on Delivery
- Bank Transfer
- Convenience Store Payment
Since you requested payment by credit card, please press the 'Proceed to Checkout' button on the cart screen and enter your credit card information on the payment screen.
If you have any questions or concerns, please do not hesitate to ask.
Thank you very much for your purchase."
Ultimately, the UI is also updated with the products in the cart.

The cart is updated as requested in the chat
What is happening behind the scenes?
Flow of the conversation:
-
Initial request (08:18:22)
- Prompt: "What are your recommended products?"
- Tool execution:
list_featured_products - Sends SigV4-signed request to Backend API
- Retrieves and suggests information for 4 products
-
Cart addition request (08:19:28)
- Prompt: "Please pick some from those under 2000 yen and add them to the cart."
- Tool execution:
add_to_cart(including Matcha Daifuku) → Error - Backend response:
ProductNotAvailableOnlineerror - LLM understands the error and presents an alternative
- Tool re-execution:
add_to_cart(Dorayaki, Yokan, Castella) - Final cart: 2 Dorayaki, 2 Yokan, 1 Castella (Total: 1,560 yen)
-
Payment request (08:21:58)
- Prompt: "Please process the payment by credit card."
- Retrieves current cart contents:
get_cart_contents - Explains that payment is outside of authority
Final cart state:
{
"items": [
{ "productId": "prod_002", "quantity": 2, "addedAt": "2025-12-30T08:19:32.301Z" },
{ "productId": "prod_009", "quantity": 2, "addedAt": "2025-12-30T08:19:32.500Z" },
{ "productId": "prod_010", "quantity": 1, "addedAt": "2025-12-30T08:19:32.601Z" }
]
}
Conversation history storage:
- Total 6 turns (3 by user + 3 by assistant) recorded in DynamoDB
- Ready to be used as context for the next request
Points:
- Session Management: Conversation history and cart are saved in DynamoDB, maintaining context per client.
-
Tool Calling: The LLM autonomously selects and executes tools like
list_featured_products. - IAM Authentication: Calls from the agent to the backend API are protected by SigV4 signatures.
- Streaming: Responses are delivered in real-time via Server-Sent Events (SSE).
Actual AI Agent CloudWatch Logs
[agent][handleChat] sessionId=c2b21899-7fa6-4fd0-a97d-bf0b9a923e00 prompt=What are your recommended products?...
[sigv4] start { method: 'GET', path: '/prod/api/v1/sessions/c2b21899-7fa6-4fd0-a97d-bf0b9a923e00' }
[sigv4] done { elapsedMs: 3850 }
[sigv4] start { method: 'GET', path: '/prod/api/v1/featured-products' }
[sigv4] done { elapsedMs: 4200 }
[sigv4] start { method: 'GET', path: '/prod/api/v1/products/prod_002' }
[sigv4] done { elapsedMs: 4100 }
[sigv4] start { method: 'GET', path: '/prod/api/v1/products/prod_009' }
[sigv4] done { elapsedMs: 3800 }
[sigv4] start { method: 'GET', path: '/prod/api/v1/products/prod_010' }
[sigv4] done { elapsedMs: 4200 }
[agent][summary] sessionId=c2b21899-7fa6-4fd0-a97d-bf0b9a923e00 events=312 totalChars=490
[updateConversationHistory] Successfully updated conversation history
[agent][handleChat] sessionId=c2b21899-7fa6-4fd0-a97d-bf0b9a923e00 prompt=pick some from those under 2000 yen...
[agent][handleChat] Loaded 2 messages from history
[sigv4] start { method: 'PATCH', path: '/prod/api/v1/sessions/.../cart' }
[sigv4] done { elapsedMs: 7300 }
[addToCartTool] Error: The following products are not available for online purchase
[sigv4] start { method: 'PATCH', path: '/prod/api/v1/sessions/.../cart' }
[sigv4] done { elapsedMs: 4300 }
[agent][summary] sessionId=c2b21899-7fa6-4fd0-a97d-bf0b9a923e00 events=296 totalChars=387
[agent][handleChat] sessionId=c2b21899-7fa6-4fd0-a97d-bf0b9a923e00 prompt=Please process the payment by credit card...
[agent][handleChat] Loaded 4 messages from history
[sigv4] start { method: 'GET', path: '/prod/api/v1/sessions/.../cart' }
[sigv4] done { elapsedMs: 1380 }
[agent][summary] sessionId=c2b21899-7fa6-4fd0-a97d-bf0b9a923e00 events=233 totalChars=420
Operations readable from the logs:
- SigV4 Signature: 1–8 ms signature processing time for each API call.
- Loading conversation history: Accumulates as "Loaded 2 messages" → "Loaded 4 messages".
-
Error Handling: Autonomously executes alternative plan after error occurs in
addToCartTool. - Asynchronous Storage: Can confirm that saving conversation history is "Successfully updated."
- Event Count: 233–312 events per response (number of streaming chunks).
-
Reference via pronouns:
"Please pick some from those... and add them to the cart."
→ Understanding what "from those" refers to is only possible because it remembers the list of 4 recommended products (Dorayaki, Matcha Daifuku, Yokan, Castella) suggested by the shop manager just before. -
Implicit context understanding:
"Please process the payment by credit card."
→ Even though it is not specified "what" to pay, the agent understands:- That items were added to the cart in the previous interaction.
- The current cart contents (2 Dorayaki, 2 Yokan, 1 Castella, total 1,560 yen).
- The customer's intention to proceed with the purchase procedure.
This interaction would not be possible without conversation history, as there would be no way to know "what payment it is" or "what is in the cart."
-
Inheriting context from errors and autonomous problem solving:
When an error occurred during the first cart addition saying "Matcha Daifuku is in-store only," the agent remembered that error information and, within the same request, automatically selected an alternative (Dorayaki, Yokan, Castella) excluding Matcha Daifuku and retried. It solved the problem autonomously without asking the customer for further instructions.
Strands Agent manages conversation history in the conversationHistory array and passes past interactions to the LLM with each request (the "Loaded 2 messages" → "Loaded 4 messages" in the logs is this behavior). This enables natural conversation that maintains context just like a human.
2. Overall Architecture
I will first talk about the characteristics of the system I built. This architecture rests on five pillars:
- Fully Serverless: CloudFront + Lambda + API Gateway + DynamoDB + API Gateway
- Zero-Trust Authentication: Using IAM authentication for all API calls (no API keys needed)
- Structured Data-Driven: Accurate information provision via JSON + DynamoDB, not RAG/Vector DB
- Separation of Concerns: Design where Frontend, Backend, and Agent are strictly separated
- Type-Safe Implementation: Tool definition and schema validation using TypeScript + Zod
Let's see how these are realized.
4-Layer Serverless Architecture
This system is composed of four layers: Frontend (Nuxt.js) → Backend (Hono) → Agent (Strands + Bedrock) → Data (DynamoDB).
Responsibilities of Each Layer
| Layer | Technology Stack | Responsibility | Disclosure Method |
|---|---|---|---|
| Frontend | Nuxt.js 3 (SSR) on Lambda | UI/UX, API aggregation via BFF pattern, session management | CloudFront + Function URL (OAC) |
| Backend | Hono on Lambda | Business logic, data validation, CRUD operations | API Gateway (IAM Authentication) |
| Agent | Strands Agents + Bedrock on Lambda | Natural language processing, tool selection/execution, conversation control | Function URL (IAM Authentication) |
| Data | DynamoDB + S3 | Data persistence, static asset delivery | Protected by IAM policy |
Why I chose serverless
The reason I chose serverless architecture is the balance between cost efficiency and operational burden.
Cost perspective
- Pay-as-you-go: Since it's a verification project, it was attractive that costs would be zero if there is no access.
- ARM64: Using ARM64 for all Lambda functions should reduce costs by up to 34% compared to x86.
- DynamoDB On-Demand: It helped that traffic prediction wasn't needed and it auto-scaled.
Operational perspective
- No server management required: I could focus on application code without worrying about patching or OS updates.
- Automatic log collection: Logs are automatically aggregated in CloudWatch Logs, so building a log infrastructure wasn't necessary.
- Infrastructure as Code: Everything is code-managed via CDK, ensuring reproducibility.
Security perspective
- Zero Trust: Used IAM authentication for all API calls, avoiding the risk of API key leakage.
-
Data Sovereignty: Placed all resources in
ap-northeast-1(Tokyo region). - HTTPS Support: CloudFront, API Gateway, and Lambda Function URLs all support HTTPS by default.
Infrastructure management via CDK
All AWS resources are defined in CDK.
// (Excerpt)
export class MahitotsuYaStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Pre-build (run bun build before Docker image creation)
preBuildBackend();
preBuildFrontend();
preBuildAgent();
// Create DynamoDB tables
const tables = createDynamoDBTables(this);
// Backend Lambda + API Gateway
const { api } = createBackendResources(this, tables, staticAssetsBucket);
// Agent Lambda + Function URL
const { agentFunctionUrl } = createAgentResources(this, api, this.region, this.account);
// Frontend Lambda + CloudFront
const { distribution } = createCloudFrontDistribution(/* ... */);
}
}
This provides the following benefits:
-
Reproducibility: Environment can be built any number of times with
cdk deploy. - Change tracking: Managed in Git, differences are code-reviewable.
- Rollback: Automatic rollback on deployment failure.
- Explicit dependencies: Dependencies between resources are clear in the code.
3. Implementation with Strands Agent
3-1. Why I Chose Strands Agents
This time, I chose Strands Agents because of the balance between controllability and simplicity.
As cited in my previous article, I have experience using "Agents for Amazon Bedrock," but controlling the agent's behavior only through prompts and Action Group descriptions was difficult. Debugging was limited to inferring from CloudWatch Logs, and local testing was also difficult.
On the other hand, with Strands Agents, everything is TypeScript code. It was appealing that I could develop everything from tool definitions to implementation as a normal Node.js application. Above all, the fact that it can be subject to AI coding assistance and automatic generation is very significant.
Ease of introduction: You can start with just npm install
One of the biggest attractions of Strands Agent is its ease of introduction. Complex setup or configuration in the AWS console is unnecessary, and you can start development as a normal Node.js project.
Required dependencies (excerpt from package.json):
The packages required for Strands Agent are no different from a normal Node.js project.
{
"dependencies": {
"@strands-agents/sdk": "^0.1.3",
"@aws-sdk/client-bedrock-runtime": "^3.958.0",
"hono": "^4.11.1", // Used to accept requests via HTTP
"zod": "^4.2.1"
}
}
That is all. If you run npm install (or bun install), you can start agent development immediately.
3 steps for introduction:
Step 1: Install dependencies (added as regular npm packages)
# 1. Install dependencies
npm install @strands-agents/sdk @aws-sdk/client-bedrock-runtime zod
Step 2: Create an Agent instance (minimum configuration is just 10 lines)
// 2. Minimum agent creation (works in 10 lines)
import { Agent } from "@strands-agents/sdk";
const agent = new Agent({
model: { provider: "bedrock", modelId: "anthropic.claude-3-5-sonnet-20241022-v2:0" },
systemPrompt: "You are a helpful assistant",
tools: [],
});
// 3. Execute conversation
const result = await agent.executeConversation({
userMessage: "Hello",
conversationHistory: [],
});
console.log(result.response); // → "Hello! How can I help you?"
No additional settings required:
- ✅ No AWS Console: Can be deployed directly to Lambda functions
- ✅ No dedicated infrastructure: Works in existing Node.js environments
- ✅ No agent definition files: Everything is completed in TypeScript code
- ✅ Local development possible: Immediate operation check with
bun run dev
3-2. Implementation details
Practical implementation example: Agent with multiple tools
Taking a step further from the minimum agent, let's look at the implementation for the actual project ("Mahitotsu-ya"). Here, I have built an agent with 9 tools.
Agent initialization code (executed only once when Lambda starts):
// (Excerpt)
import { Agent } from "@strands-agents/sdk";
import { model, SYSTEM_PROMPT } from "./config";
import { requestContext } from "./context";
import {
getShopInfoTool,
listProductsTool,
listFeaturedProductsTool,
listAnnouncementsTool,
getProductDetailTool,
} from "./tools/shopInfo";
import {
getCartContentsTool,
addToCartTool,
removeFromCartTool,
clearCartTool,
} from "./tools/cart";
// Initialize only once when the Lambda container starts
const agent = new Agent({
model, // Bedrock Claude Model
systemPrompt: SYSTEM_PROMPT, // Definition of behavior as a Banto (Shop Manager)
tools: [
getShopInfoTool,
listProductsTool,
listFeaturedProductsTool,
listAnnouncementsTool,
getProductDetailTool,
getCartContentsTool,
addToCartTool,
removeFromCartTool,
clearCartTool,
],
});
Points:
- Stateless design: Implemented so that the Agent instance itself holds no state.
- Instance reuse: Therefore, the Agent instance can be safely reused within the Lambda function lifecycle.
- Session context: Injected per request using AsyncLocalStorage (described later).
Implementation of tools
Strands Agents tools are defined with Zod schema + callback function. Below is an example of a tool for retrieving a product list:
import { tool } from "@strands-agents/sdk";
import { z } from "zod";
import { fetchProducts } from "../api/backendClient";
export const listProductsTool = tool({
name: "list_products",
description: "Get a list of all products available in the shop.",
inputSchema: z.object({}), // No parameters
callback: async () => {
// Automatically retrieve sessionId from AsyncLocalStorage
// backendClient internally calls the Backend API with SigV4 signature
const products = await fetchProducts(50); // Up to 50 items
return { products };
},
});
This is an example of a tool that retrieves information about a specific client's cart based on the sessionId stored in AsyncLocalStorage:
export const addToCartTool = tool({
name: "add_to_cart",
description: "Add a product to the cart. You must use the exact 'id' field from list_products results.",
inputSchema: z.object({
productId: z.string().describe("Product ID (e.g., prod_002). Must be exact match."),
quantity: z.number().int().positive().default(1).describe("Quantity to add"),
}),
callback: async (input) => {
try {
// Retrieve sessionId from AsyncLocalStorage
const sessionId = getSessionId();
// Call Backend API (internal: get cart → update → send PATCH)
const result = await updateCart(sessionId, input.productId, input.quantity);
return {
success: true,
itemCount: result.cart.items.reduce((sum, item) => sum + item.quantity, 0),
addedProduct: input.productId,
addedQuantity: input.quantity,
};
} catch (err) {
// Return Backend error as is (LLM translates to natural language)
const error = err as Error & { recoveryHintForAgent?: string };
return {
success: false,
error: error.recoveryHintForAgent || error.message,
};
}
},
});
Implementation Points:
- The tool has no business logic and only calls the Backend API.
- Product presence confirmation, stock checks, and validation are performed by the Backend.
- A
recoveryHintForAgentis attached to the Backend's systemic error message to help the Agent's behavior.
Context injection via AsyncLocalStorage
Although the Agent instance is stateless, each tool needs to access the "session ID of the current request." I solved this challenge with AsyncLocalStorage.
Definition of the context store:
import { AsyncLocalStorage } from 'node:async_hooks';
type RequestContext = {
sessionId: string;
};
export const requestContext = new AsyncLocalStorage<RequestContext>();
export function getSessionId(): string {
const context = requestContext.getStore();
if (!context?.sessionId) {
throw new Error('Session ID not found in request context');
}
return context.sessionId;
}
Setting the context in the request handler via AsyncLocalStorage:
// Request handler
const handleChat = async (c: Context) => {
const { prompt, sessionId } = await c.req.json();
// Set context in AsyncLocalStorage
return requestContext.run({ sessionId }, async () => {
// If agent.stream() is called within this block, all tools can access sessionId
for await (const event of agent.stream(prompt)) {
// Streaming processing
}
});
};
Usage of context:
Why this design?:
It is because I feel it is dangerous to leave information retrieval based on appropriate context entirely to the LLM. It allows passing only information that has been appropriately filtered based on the sessionId outside the LLM to the LLM.
Role of the system prompt
I specialized the system prompt for behavior and tool usage. Business knowledge is not included, and it is delegated to the data retrieved from the tools.
// (Excerpt)
export const SYSTEM_PROMPT = `You are a Banto (Shop Manager) at an established Japanese confectionery shop called "Mahitotsu-ya".
Please respond to customer questions in a polite and friendly tone.
【Scope of Response Constraints】
Respond only to the following content:
- Our shop's products (Japanese sweets)
- Our shop's hours, access, and store information
- Our shop's history, motto, and philosophy
...
【Tone Features】
- Base form: "~desu", "~masu", "~itashimasu"
- Polite endings: "~de gozaimasu", "~gozaimasu"
...
【Important】For questions about product information, announcements, store information, and cart operations,
always use the provided tools to retrieve and manipulate the latest information.
Do not use speculation or general knowledge; respond based on actual data retrieved from the tools.
【Tool Usage Guidelines】
Store information (get_shop_info tool):
- Hours, closed days, location → sections: ["basic"]
- Store introduction, shop features → sections: ["about"]
- Shop history, origins of founding → sections: ["history"]
...
【Important】Steps for adding items to the cart:
1. Always call list_products or list_featured_products to retrieve the product list.
2. Accurately copy the "id" field (e.g., prod_002) of the retrieved product.
3. Specify that exact ID in the productId parameter of the add_to_cart tool.
4. Do not use IDs inferred from product names.
...`;
What to write / what not to write in the system prompt:
| What to write | What NOT to write |
|---|---|
| Tone, response style | Specific product prices or stock |
| Tool usage, timing | Store information such as hours |
| Response scope constraints | Business rules (e.g., "Nama-gashi is not available for online sale") |
| Behavior during errors | List of product categories |
Reason: Business knowledge and business processes change. If you hardcode them in the system prompt, the Agent must be redeployed every time a change is made. Instead, by delegating to structured data retrieved from tools, you can respond just by updating the data.
Implementation of streaming responses
The Agent's response is streamed via Server-Sent Events (SSE). This allows the user to check the first token of the response immediately, improving the perceived performance.
// (Excerpt)
import { streamSSE } from "hono/streaming";
const handleChat = async (c: Context) => {
const { prompt, sessionId } = await c.req.json();
return requestContext.run({ sessionId }, async () => {
const chunks: string[] = [];
return streamSSE(c, async (stream) => {
for await (const ev of agent.stream(prompt)) {
const text = ev.text ?? ev.delta ?? ev.response;
if (typeof text === "string" && text.length > 0) {
chunks.push(text);
await stream.writeSSE({ data: JSON.stringify({ event: text }) });
}
}
// Stream end marker
await stream.writeSSE({ data: JSON.stringify({ done: true }) });
// Asynchronously save conversation history (without delaying response)
updateConversationHistory(sessionId, prompt, chunks.join('')).catch(console.error);
});
});
};
Benefits of streaming:
- Improved perceived performance: Users can verify the response immediately with the first few tokens.
- Real-time feel: Provides a "thinking" sensation to the user.
- Delivery via Function URL: The Agent is exposed via a Function URL, and response streaming is enabled, so even long responses can be delivered without worrying about timeouts.
Management of conversation history
Conversation history per session is saved in DynamoDB and retrieved in the next request. This enables conversation while maintaining context.
Persistence of conversation history: By saving the interaction content of each turn in the Backend session API, the context of the conversation can be maintained even if the Lambda function is discarded. The following client functions are used to retrieve/update session data. Actual persistence is performed by the called Backend API.
// (Excerpt)
export async function getSessionData(sessionId: string) {
const response = await callBackendAPI(`/api/v1/sessions/${sessionId}`, 'GET');
return response.data; // { sessionId, cart, conversationHistory }
}
export async function updateConversationHistory(
sessionId: string,
userMessage: string,
assistantMessage: string
) {
await callBackendAPI(`/api/v1/sessions/${sessionId}/conversation`, 'POST', {
userMessage,
assistantMessage,
});
}
Usage of conversation history in the request handler:
// (Excerpt)
const handleChat = async (c: Context) => {
const { prompt, sessionId } = await c.req.json();
// Retrieve conversation history from session
const sessionData = await getSessionData(sessionId);
const conversationHistory = sessionData?.conversationHistory || [];
// Inject conversation history into the prompt
let enrichedPrompt = prompt;
if (conversationHistory.length > 0) {
const historyText = conversationHistory
.map((msg) => `${msg.role === 'user' ? 'Customer' : 'Banto'}: ${msg.content}`)
// Pass to Agent.stream()
for await (const ev of agent.stream(enrichedPrompt)) {
// ...
}
};
Design Points:
- Conversation history is managed by the Backend: The Agent only retrieves it.
- Prompt enrichment: Inject past conversations directly into the prompt (simple and effective).
- Asynchronous storage: Save history after response streaming (prioritizing user experience).
4. Why Structured Data Brings Accuracy
Why I chose structured data instead of RAG
RAG (Retrieval-Augmented Generation) is attracting attention as a method for providing information to AI agents, but I ultimately chose structured data (JSON or DynamoDB).
This decision is the result of considering data accuracy, response speed, and operational costs comprehensively.
Reasons I avoided RAG
Even for qualitative information, I judged that the use of structured data was more appropriate than RAG for the following reasons:
-
Lack of demand for accuracy
- Product prices, hours, and history must be 100% accurate.
- RAG search results might contain "similar information."
- In vector search scoring, "probably correct" is not good enough.
-
Occurrence of dual maintenance
- After updating the source information, synchronization by embedding and loading into a vector DB is required.
- Determining whether the source information and vector DB are synchronized is not easy.
Benefits of structured data
On the other hand, the method of querying structured data (DynamoDB + JSON) via the Backend API had the following benefits:
- Accuracy: Structured by information category, and the scope that the Agent needs to read is clear.
- Single source of information: The Backend API can be used by both the Agent and the Frontend, and it is always possible to synchronize.
- Cost efficiency: Embedding processing and Vector DB running costs are unnecessary.
Structured data (Excerpt of "Mahitotsu-ya" data)
{
"basic": {
"name": "Mahitotsu-ya",
"tagline": "Putting the change of seasons and the heart of the craftsman into every single Japanese sweet",
"hours": "9:00 - 18:00",
"closedOn": "Wednesday",
"phone": "03-0000-0000",
"address": "1-2-3, XX-ku, Tokyo",
"founded": "Meiji 15",
"foundedYear": 1882,
"currentGeneration": 5
},
"about": {
"features": [
{
"icon": "🌾",
"title": "Carefully selected ingredients",
"description": "Hokkaido adzuki beans, domestic glutinous rice, Tanba chestnuts, etc..."
},
{
"icon": "👨🍳",
"title": "Craftsman skills",
"description": "Protecting traditional techniques inherited through generations..."
}
]
},
"history": {
"timeline": [
{
"year": "Meiji 15",
"era": "1882",
"title": "Founded",
"description": "Founder Mosaburo Matsudaira in Asakusa, Tokyo...",
"highlight": true
},
{
"year": "Showa 57",
"era": "1982",
"title": "100th anniversary of founding",
"description": "Celebrating 100 years of operation...",
"highlight": true
}
],
"craftsmen": [
{
"generation": 5,
"name": "Kentaro Matsudaira",
"period": "Reiwa 3 -",
"description": "Current shop owner. Inheriting techniques and heart from the previous generation...",
"current": true
}
]
},
"payment": {
"methods": [
{
"id": "credit",
"name": "Credit Card",
"icon": "💳",
"fee": 0,
"details": {
"brands": ["Visa", "Mastercard", "JCB", "American Express"]
}
},
{
"id": "cod",
"name": "Cash on Delivery",
"icon": "📦",
"fee": 330,
"notes": ["Payment is cash only"]
}
]
}
}
Hybrid strategy of structured data and RAG
However, it is not that RAG is completely unnecessary. I am thinking of using them separately as follows in the future:
Information to be managed with structured data:
- Product master (ID, name, price, category, online availability)
- Business hours, closed days, access information
- Order history, cart state
Information to be handled with RAG:
- Detailed descriptions of the history and manufacturing methods of Japanese sweets
- Seasonal recommended product columns
- Frequently asked questions (FAQ) from customers
In other words, the strategy is to structure business data that requires strictness, and use RAG for exploratory information provision.
5. Separation of Concerns and Architecture Design
Next, I will write about the maintainability of the overall architecture. I will talk about how I separated the Frontend, Backend, and Agent so that each could evolve independently.
API contract I valued
In my design, I made each layer depend only on the API contract.
Backend API Contract (e.g., Product List Retrieval)
API response format guaranteed by the Backend:
{
"success": true,
"data": [
{
"id": "prod_001",
"name": "Matcha Daifuku",
"category": "Daifuku",
"price": 250,
"availableOnline": true,
"stock": 50
},
// ...
],
"timestamp": "2025-12-29T12:00:00Z"
}
Perspective of the Frontend
The Frontend does not know the internal implementation of the Backend and depends only on the API contract:
export default defineEventHandler(async (event) => {
const response = await callBackendAPI('/api/v1/products');
// Does not know the Backend's internal implementation (DynamoDB or RDS, how it is validated)
// Only trusts the response format defined by the API contract
return response;
});
Perspective of the Agent
The Agent similarly depends only on the API contract:
export const listProductsTool = tool({
// ...
callback: async () => {
const products = await callBackendAPI('/api/v1/products');
// Does not know the inside of the Backend (where products are stored, how they are retrieved)
// Returns the data returned from the API as is
return products;
},
});
Result of this design:
- Even if you change the Backend's internal implementation (e.g., DynamoDB to RDS), the Frontend and Agent are not affected.
- As long as the API contract is maintained, each layer can evolve independently.
Separation Concrete Example 1: Implementation location of data and logic
Bad example: Agent infringes on Backend responsibilities
By having the Agent hold business logic, dual management with the Backend occurs:
// Product existence confirmation and validation on the Agent side
export const addToCartTool = tool({
// ...
callback: async (input) => {
// Agent holds product master data
const validProducts = ['prod_001', 'prod_002', 'prod_003'];
if (!validProducts.includes(input.productId)) {
return { success: false, error: 'Product not found' };
}
// Agent judges online sales availability
if (input.productId === 'prod_005') {
return { success: false, error: 'This product cannot be purchased online' };
}
// Call Backend API (already verified)
await callBackendAPI('/api/v1/sessions/cart', sessionId, { /* ... */ });
},
});
Problems:
- The Agent has knowledge of the product master (dual management with Backend).
- When adding a product, validation code must be modified in both the Agent and the Backend.
- Consistency breaks when the Backend's business rules change.
Good example: Complete delegation to Backend
As a thin client, the Agent delegates all judgments to the Backend:
// Agent does not judge anything, throws everything to the Backend
export const addToCartTool = tool({
// ...
callback: async (input) => {
const sessionId = getSessionId();
// Call Backend API only (verification performed by Backend)
// Note: Actually implementation retrieves entire cart → updates → sends PATCH
const result = await updateCart(sessionId, input.productId, input.quantity);
// Return result from Backend as is
return result;
},
});
Comprehensive validation is performed on the Backend side:
// (Excerpt)
app.patch('/api/v1/sessions/:id/cart', async (c) => {
const sessionId = c.req.param('id');
const body = await c.req.json();
// Cart structure validation
const cartSchema = z.object({
items: z.array(
z.object({
productId: z.string(),
quantity: z.number().int().positive(),
addedAt: z.string().optional(),
})
),
});
const parsed = cartSchema.safeParse(body);
if (!parsed.success) {
return c.json(errorResponse('BadRequest', 'Invalid cart data'), 400);
}
// ① Existence confirmation of all products and online sales availability check
const missingProductIds: string[] = [];
const offlineProducts: Array<{ id: string; name: string }> = [];
for (const item of parsed.data.items) {
const product = await getProductById(item.productId);
if (!product) {
missingProductIds.push(item.productId);
} else if (!product.availableOnline) {
offlineProducts.push({ id: product.id, name: product.name });
}
}
// ② Error check
if (missingProductIds.length > 0) {
return c.json(
errorResponse(
'InvalidProductId',
`The following productIds do not exist: ${missingProductIds.join(', ')}`,
{ missingProductIds }
),
400
);
}
if (offlineProducts.length > 0) {
const productList = offlineProducts.map(p => `${p.name} (${p.id})`).join(', ');
return c.json(
errorResponse(
'ProductNotAvailableOnline',
`The following products are not available for online purchase: ${productList}`,
{ offlineProducts }
),
400
);
}
// ③ Cart update (complete replacement)
const updatedSession = await updateSessionCart(sessionId, parsed.data);
return c.json(successResponse(updatedSession));
});
Benefits:
- Single Source of Truth: Product master and business rules are managed only by the Backend.
- Localization of changes: When business rules change, you only need to modify the Backend.
- Consistency: Guarantees that the Agent and Frontend always operate under the same rules.
Separation Concrete Example 2: Error message design
Backend returns system-oriented errors
Backend returns fact-based error messages:
if (offlineProducts.length > 0) {
const productList = offlineProducts.map(p => `${p.name} (${p.id})`).join(', ');
return c.json(
errorResponse(
'ProductNotAvailableOnline',
`The following products are not available for online purchase: ${productList}`,
{ offlineProducts }
),
400
);
}
Agent relays errors, LLM translates
Agent returns Backend errors as is, and leaves natural language conversion to the LLM:
export const addToCartTool = tool({
// ...
callback: async (input) => {
try {
const result = await callBackendAPI(/* ... */);
return result;
} catch (err) {
// Return Backend error as is (interpreted by LLM)
const error = err as Error & { recoveryHintForAgent?: string };
return {
success: false,
// recoveryHintForAgent is not provided by Backend, but attached by Tool
error: error.recoveryHintForAgent || error.message,
};
}
},
});
The recoveryHintForAgent attribute sets hints on how the Agent should behave next for each error type from the Backend.
if (res.statusCode >= 400) {
const errorBody = res.json as { success: false; error: string; message: string; details?: Record<string, unknown> } | undefined;
let recoveryHintForAgent = 'An error occurred while updating the cart.';
if (errorBody?.error === 'InvalidProductId') {
const invalidIds = (errorBody.details?.invalidProductIds as string[]) || [];
recoveryHintForAgent = `The following product IDs do not exist in the system: ${invalidIds.join(', ')}. Please call list_products to get valid product IDs.`;
} else if (errorBody?.error === 'ProductNotAvailableOnline') {
const notAvailableProducts = (errorBody.details?.notAvailableProducts as Array<{ id: string; name: string }>) || [];
const productNames = notAvailableProducts.map(p => `${p.name} (${p.id})`).join(', ');
recoveryHintForAgent = `The following products are not available for online purchase: ${productNames}. These products can only be purchased in-store.`;
} else if (errorBody?.error === 'SessionExpired') {
recoveryHintForAgent = 'The session has expired. Please ask the user to refresh the page and try again.';
} else if (errorBody?.error === 'SessionNotFound') {
recoveryHintForAgent = 'Session not found. Please ask the user to refresh the page and try again.';
}
const error = new Error(errorBody?.message || 'Cart update failed');
(error as Error & { recoveryHintForAgent?: string }).recoveryHintForAgent = recoveryHintForAgent;
throw error;
}
LLM converts to customer-oriented messages
Ultimately, the LLM generates messages for customers.
Response of LLM (Claude):
"I apologize. This product is sold only in stores and is
not available online. We look forward to seeing you at the store."
Why I chose this design:
- Backend reports facts only: If the Backend only returns the fact that "this product is not available online," it does not need to be aware of customer interaction.
- Agent concentrates on translation: Delegates the work that the LLM excels at, which is converting technical errors into customer-friendly words.
- Tool provides hints: For errors from the Backend, the Tool, which is the bridge between the Backend and the Agent, is best suited for providing hints on how the Agent should behave.
- Flexibility of error messages: You can adjust the tone of the response in the system prompt without changing the Backend API.
By thoroughly implementing this separation, the following benefits are obtained:
- Independent evolution: For example, even if you change the Frontend technology stack to Next.js, the Backend and Agent are not affected.
- Parallel development: I developed this alone, but with a team, you could proceed with the Frontend, Backend, and Agent independently.
- Clarification of responsibilities: When a bug occurs, it became easier to identify which layer has the problem.
- Testability: Because each layer can be tested independently, isolation of problems was easy.
6. Lessons Learned from Failures: Detours I Took
Behind "the design I adopted" that I explained so far, there are experiences of failure caused by not adopting those designs. I'd like to share some of them.
Failure 1: Giving the Agent business logic
What I did first:
// ❌ First implementation (failure example)
export const addToCartTool = tool({
callback: async (input) => {
// Agent judges online sales availability of products
const product = await getProduct(input.productId);
if (!product.availableOnline) {
return { success: false, error: "This product is not available for online sale" };
}
// ...
},
});
What was the problem:
- Same judgment implemented on the Backend side → Logic was duplicated.
- When the
availableOnlinerule changes, both the Agent and Backend must be changed. - Tests are required twice (testing the same case in both the Agent and Backend).
After correction (current design):
// ✅ After correction: Delegating to Backend
export const addToCartTool = tool({
callback: async (input) => {
try {
// Call Backend API only (judgment is performed by Backend)
const result = await callBackendAPI('/api/v1/cart/add', 'POST', input);
return result;
} catch (err) {
// Return Backend error as is
return { success: false, error: err.message };
}
},
});
Lesson: The Agent should focus on being a client for the Backend API. Leave the judgment to the Backend.
Failure 2: Writing business knowledge in the system prompt
What I did first:
const SYSTEM_PROMPT = `
You are a service staff member at a Japanese confectionery shop "Mahitotsu-ya".
【Products handled】
- Dorayaki: 220 yen (Available for online sale)
- Matcha Daifuku: 280 yen (Store only)
- Yokan: 350 yen (Available for online sale)
...
【Business hours】
Weekdays: 9:00-18:00
Weekends: 10:00-17:00
`;
What was the problem:
- Redeployment of the Agent was required every time product prices changed.
- Editing the system prompt for every new product addition → Lambda redeployment.
- Even changing business hours required deployment → Emergency response was not possible.
After correction (current design):
const SYSTEM_PROMPT = `
You are a service staff member at a Japanese confectionery shop "Mahitotsu-ya".
【Available tools】
- get_shop_info: Retrieve business hours and store information
- list_products: Retrieve product list and prices
...
【Response style】
- Polite language
- Convey the appeal of Japanese sweets
`;
Lesson: Write only "behavior" in the system prompt. Retrieve all business knowledge via tools.
Failure 3: Postponing session design
What I did first:
- Because I postponed the implementation of session management, I adopted a provisional implementation where conversation history and cart status are maintained on the browser side. The Frontend constantly sent conversation history and cart status to the agent.
- After that, I introduced the concept of sessions to migrate the management of conversation history and cart status to the Backend, which should have been responsible for it.
What was the problem:
- I was reusing the Agent instance across multiple requests, but it became necessary to handle different
sessionIds for each request received, so the same Agent instance could no longer process requests.
After correction (current design):
- The lifecycle of the Agent instance remained unchanged, and information unique to the request is injected via AsyncLocalStorage.
- It was resolved safely this time, but there was a risk that it could lead to significant architectural changes depending on the implementation content.
Lesson: As a management method for information that should be separated for each user or client, consider session management from the beginning.
Things I realized while implementing
Through these failures, I realized the importance of deciding policies in the design phase. How to separate responsibilities between the Agent and the Backend, where to hold business knowledge, how to design session management—these can be decided while implementing, but knowing cases and best practices should surely reduce the time spent being lost.
This feeling was the motivation for writing this article.
7. Conclusion
In this article, taking the implementation of "Mahitotsu-ya" as an example, I wrote about what design decisions are necessary when treating AI agents as part of an application. I have begun to feel that AI agents are no longer "beings to be added later," but things that should be considered on the assumption of their existence at the initial design stage.
I would be happy if this article became an opportunity for you to start thinking about design policies for incorporating AI agents into applications.
Discussion