DEV Community: Jamal

I Built an npm Package That Scaffolds AWS AppSync, Lambda & GraphQL Services — Files, Infra, and All

Jamal — Wed, 02 Sep 2026 15:00:18 +0000

create-lambda-graphql-app: A CLI That Scaffolds Fully Wired AWS AppSync + Lambda Services

Every engineering team has that one repository everyone secretly clones just to copy-paste a folder.

For us, it was a microservice built around AWS AppSync and Lambda. Whenever someone needed to write a new API handler, the ritual was always the same: find the last service a teammate built, copy the folder, purge whatever logic wasn't needed, rename half the files, fix the broken relative imports, manually update template.yaml, forget to update the GraphQL schema, and eventually deploy something that mostly worked.

It was slow, error-prone, and propagated technical debt across projects. Every copy carried forward the hidden flaws of the template before it.

To solve this, I packaged our entire boilerplate into an open-source CLI tool: create-lambda-graphql-app.

npx create-lambda-graphql-app

That's all it takes. Answer a few interactive prompts and you get a production-ready, fully wired project structure instantly.

The Root Problem with Manual Scaffolding

Copy-pasting directories fails in subtle, compounding ways over time:

Directory drift. Service A keeps input validation in validators/, Service B moves it to validation/, and Service C inlines it inside the handler. Six months later, jumping between repositories requires a re-learning curve.
Invisible glue code. An AppSync service requires multiple pieces to stay tightly synced: the GraphQL schema, VTL mapping templates, AppSync data sources, resolvers, IAM execution roles, and Lambda code. Missing a single link leads to successful deployments that silently fail at runtime with 400 Bad Request errors.
Tribal knowledge onboarding. Relying on "just ask whoever built the last one" is not a scalable documentation strategy.
Boilerplate fatigue. Setting up .gitignore, ESLint, Prettier, debug configurations, and local invocation runners gets reinvented slightly differently every single time.

The CLI makes the ideal architecture the path of least resistance: running a single command is simply faster than manually copying and editing folders.

What's Included Out of the Box

The package unifies the whole stack — interactive CLI, directory structure, GraphQL typing, infrastructure as code, and local developer tooling.

1. The CLI tool

A lightweight, zero-bloat Node.js CLI written in modern ES Modules (Node 18+):

Layer	Dependency	Purpose
Parsing	`commander`	Command-line option management
Prompts	`inquirer`	Interactive user input
Styling	`chalk`	Colorized terminal output
File system	`fs-extra`	Directory creation and templating
Formatting	`dedent`	Clean code generation formatting

It provides two core workflows:

npx create-lambda-graphql-app — scaffolds a new service from scratch.
npx create-lambda-graphql-app add <handler-name> — safely injects a new handler into an existing project.

2. Standard project structure

Here is the folder structure generated out of the box:

my-service/
├── handlers/
│   └── create-order/
│       ├── index.mjs          # Orchestration pipeline
│       ├── validators/        # Request payload validation (Joi)
│       ├── transformers/      # Input data transformation
│       ├── helpers/           # Core business logic
│       ├── dal/               # Data Access Layer (DynamoDB, S3, etc.)
│       ├── exceptions/        # Custom error definitions
│       └── constants/
├── layers/
│   └── common-dependency/     # Shared node_modules layer
├── local-test/
│   └── create-order/          # Local invocation events & harness
├── mapping/
│   ├── request.vtl            # AppSync request template + guards
│   └── response.vtl           # AppSync response template + security headers
├── schema/
│   └── schema.graphql         # GraphQL SDL definition
├── scripts/
│   └── deploy-assets.mjs      # S3 sync script for schema & VTL
├── .vscode/
│   └── launch.json            # Auto-generated debug configs per handler
├── template.yaml               # AWS SAM infrastructure definition
├── samconfig.toml              # Default SAM deployment configuration
├── eslint.config.mjs
├── .prettierrc.json
└── README.md

Standardized Handler Architecture

Every generated handler is structured as a clean, predictable pipeline. The entry file (index.mjs) contains zero business logic — it delegates processing across distinct layers and normalizes errors into standard HTTP status codes:

Request Event → Validator → Transformer → Helper Logic → Data Access (DAL)

Each layer raises explicit domain exceptions (ValidationError, TransformError, BusinessLayerError, DataLayerError, NotFoundError). The handler catches these and maps them into a uniform envelope:

{
  "data": { ... },
  "responseDetail": {
    "status": "SUCCESS",
    "statusCode": 200,
    "message": "Operation completed successfully"
  }
}

This guarantees that every API across your architecture reports errors in the exact same format, simplifying error parsing for frontends and monitoring tools.

Pre-Wired AWS SAM Infrastructure

The auto-generated template.yaml isn't a dummy file — it provides a complete AWS SAM stack:

Runtime defaults. Node.js 20 on arm64, active AWS X-Ray tracing, shared Lambda dependency layers, and environment-aware timeouts.
Environment mapping (Mappings.StagesMap). Clean separation of deployment variables across dev, qa, ppe, and prod stages (VPC subnets, log retention, bucket names, and authentication provider ARNs).
AppSync integration. Provisioned GraphQL API with Lambda & API Key authorization, CloudWatch logs enabled, and automated S3 schema loading.
Granular IAM roles. Pre-configured permissions scoped for DynamoDB, S3, SSM, Secrets Manager, EventBridge, X-Ray, and VPC access.
Automated resolver wiring. Naming a handler get-orders configures it as a GraphQL Query; naming it anything else (e.g., create-order) automatically registers it as a Mutation, complete with generated Input and Response types in your schema.

S3 schema & VTL deployment workflow

To bypass template size limits and simplify deployment, GraphQL schemas and VTL files live inside the repository but are read directly from S3 during deployment.

The included build tool simplifies asset synchronization:

npm run deploy:assets -- --org my-org --env dev

This command automatically publishes schema.graphql, request.vtl, and response.vtl directly to s3://<org>-app-schema-bucket/<env>/<service>/.

Daily Developer Workflow

Bootstrapping a new service: run npx create-lambda-graphql-app → npm install → sam build → deploy.
Adding a handler safely: run npx create-lambda-graphql-app add cancel-order. It creates the folder hierarchy, appends SAM infrastructure blocks, and updates schema.graphql without disturbing your current codebase.
Seamless onboarding: every generated service includes an explicit README.md walking developers through local invocation, parameter customization, and deployment commands.
Out-of-the-box debugging: pre-configured VS Code launch.json files and mock event payloads let you debug handlers with breakpoints locally in seconds.

Getting Started

You don't need to install anything globally. Run it directly with npx:

# 1. Generate the service
npx create-lambda-graphql-app

# Prompt responses:
#   ? Project name: my-service
#   ? Organization name: my-org
#   ? Primary handler name: get-orders  (get-* maps to a Query)
#   ? Add another handler: create-order (maps to a Mutation)

cd my-service
npm install
npm install --prefix layers/common-dependency

# 2. Build local SAM artifacts
npm run build

# 3. Deploy GraphQL schema and VTL templates to S3
npm run deploy:assets -- --org my-org --env dev

# 4. First-time guided SAM deployment
sam deploy --guided

# 5. Start local API Gateway / AppSync emulator
npm run local

Adding another handler down the line:

npx create-lambda-graphql-app add cancel-order
npm run build
npm run deploy:assets -- --org my-org --env dev
sam deploy

Roadmap & Next Steps

While the template covers most production needs out of the box, future releases will introduce:

A non-interactive --yes flag / configuration file for CI/CD automation pipelines.
Automated unit test scaffolding (jest / vitest) per handler.
Pluggable database layer presets (DynamoDB Single-Table vs. Amazon RDS / Prisma).

If your team is still manually copying service directories to launch AppSync and Lambda APIs, give it a try:

npx create-lambda-graphql-app

GitHub repository & issues: d3vjamal/lambda-node-graphql-starter

Appendix: Generated Project `README.md`

Below is the standard README.md included inside generated repositories.

create-lambda-graphql-app

Scaffold a fully wired AWS AppSync + Lambda + SAM microservice in seconds with a single command.

Overview

create-lambda-graphql-app turns complex AWS AppSync + Lambda + SAM setup into a zero-friction CLI workflow. Stop copy-pasting old folders, broken relative imports, and out-of-sync template.yaml files.

Why use create-lambda-graphql-app?

Zero configuration setup: get a production-ready, multi-stage AWS SAM project out of the box.
Opinionated handler architecture: enforces a clean pipeline separation (Validator → Transformer → Helper → DAL) across all Lambda functions.
Fully wired GraphQL + AppSync: schema definitions, VTL request/response mapping templates, AppSync data sources, and resolvers auto-generated in sync.
Local debugging out of the box: includes VS Code launch.json configurations and event payload harnesses for instant local debugging.
Incremental scaffolding: easily add new handlers to an existing project at any time without breaking existing code or manual infrastructure configurations.

Quick start

No global installation required. Execute directly using npx:

# 1. Generate a new service
npx create-lambda-graphql-app

Interactive prompts:

? Project name: my-service
? Organization name: my-org
? Initial handler name: get-orders
? Add another handler? Yes
? Handler name: create-order
? Add another handler? No

Project setup & local build:

cd my-service

# Install dependencies for project & common layer
npm install
npm install --prefix layers/common-dependency

# Build local SAM artifacts
npm run build

# Deploy assets (GraphQL schema & VTL templates) to S3
npm run deploy:assets -- --org my-org --env dev

# Deploy to AWS via SAM CLI (first time setup)
sam deploy --guided

Directory structure

my-service/
├── handlers/
│   ├── get-orders/            # Auto-generated Query handler
│   │   ├── index.mjs          # Entrypoint & exception mapping pipeline
│   │   ├── validators/        # Request validation logic (Joi)
│   │   ├── transformers/      # Input/output mapping logic
│   │   ├── helpers/           # Business logic
│   │   ├── dal/               # Data Access Layer (DynamoDB, S3, RDS)
│   │   ├── exceptions/        # Custom domain exceptions
│   │   └── constants/
│   └── create-order/          # Auto-generated Mutation handler
├── layers/
│   └── common-dependency/     # Shared dependencies Lambda Layer
├── local-test/
│   └── get-orders/            # Local test event & execution harness
├── mapping/
│   ├── request.vtl            # AppSync request mapping template
│   └── response.vtl           # AppSync response template + security headers
├── schema/
│   └── schema.graphql         # Auto-generated GraphQL SDL
├── scripts/
│   └── deploy-assets.mjs      # Syncs schema & VTL templates to S3
├── .vscode/
│   └── launch.json            # Auto-generated VS Code debug configs
├── template.yaml               # Complete AWS SAM infrastructure template
├── samconfig.toml              # Default SAM deployment configuration
├── eslint.config.mjs           # Flat ESLint config
├── .prettierrc.json            # Prettier code formatting rules
└── README.md

CLI usage

1. Scaffold a new project

npx create-lambda-graphql-app [project-name]

2. Add a handler to an existing project

Run this command inside any project generated by create-lambda-graphql-app:

npx create-lambda-graphql-app add <handler-name>

What happens when you add a handler:

Creates a new directory structure under handlers/<handler-name>/.
Creates a local test payload runner under local-test/<handler-name>/.
Injects the Function, LogGroup, DataSource, and Resolver into template.yaml.
Updates schema/schema.graphql with matching Query/Mutation types and Input/Response shapes.
Adds a debugging target to .vscode/launch.json.

Handler conventions & architecture

Handlers follow a strict pipeline architecture:

GraphQL Event → Validator → Transformer → Helper → DAL

Naming conventions & schema inferences

The CLI automatically infers GraphQL operation types based on handler naming:

Handler prefix / name	Inferred operation type	Generated GraphQL SDL
`get-`, `list-`, `fetch-*`	Query	`getOrders(input: GetOrdersInput!): GetOrdersResponse!`
Any other name (e.g. `create-`, `cancel-`)	Mutation	`createOrder(input: CreateOrderInput!): CreateOrderResponse!`

Standard response envelope

All handlers format their response into a standardized JSON payload structure:

{
  "data": {
    "orderId": "ord_12345",
    "status": "PROCESSING"
  },
  "responseDetail": {
    "status": "SUCCESS",
    "statusCode": 200,
    "message": "Order created successfully"
  }
}

Available scripts

Script	Command	Description
`build`	`sam build`	Compiles SAM template and builds Lambda dependencies.
`deploy:assets`	`node scripts/deploy-assets.mjs`	Uploads `schema.graphql` and VTL templates to S3.
`local`	`sam local start-api`	Emulates API locally for testing.
`lint`	`eslint .`	Runs static code analysis.
`format`	`prettier --write .`	Auto-formats code across the codebase.

Requirements

Node.js: 18.x or higher
AWS SAM CLI: installed and configured (aws configure)
Docker: required if building dependencies natively with sam build --use-container

Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a pull request

License

Distributed under the MIT License. See LICENSE for details.

# Building a Personal Notes Assistant with RAG, Amazon Bedrock, and Pinecone

Jamal — Wed, 26 Aug 2026 05:34:19 +0000

Have you ever saved hundreds of digital notes only to spend twenty minutes hunting for one tiny detail?

That exact frustration led me to build a custom notes assistant. I wanted a private API where I could upload my personal files, ask a question in plain English, and get an answer drawn directly from my notes—not just a generic guess from a public AI model.

In this guide, I’ll break down how I built this project using Python, Flask, Amazon Bedrock, Pinecone, S3, AWS Lambda, and API Gateway. I’ll keep the explanations clear and conversational while walking through the real code and key takeaways.

Project Goal: Upload plain text (.txt) notes and receive accurate answers strictly grounded in their content.

What is RAG?

RAG stands for Retrieval-Augmented Generation.

Normally, when you ask an AI model a question, it relies entirely on its training data. If your information is private, recent, or highly specific, the model won't know it.

Standard AI Flow: Question -> Model -> Answer
RAG AI Flow: Question -> Search My Notes -> Grab Relevant Snippets -> Model -> Answer

By adding a retrieval step, we feed the model relevant passages from our own documents alongside our question. We aren't retraining the AI model; we're giving it an open-book test using documents we control.

A Real-Life Analogy

Imagine walking into a library and asking a librarian: "What do my project notes say about serverless memory limits?"

The librarian doesn't read every book on the shelves from cover to cover. Instead, they:

Identify the core topic of your question.
Check the library catalog for matching locations.
Grab the top three relevant pages.
Read those specific pages and summarize the answer for you.

Here is how that physical library maps directly to our technical setup:

Physical Library	RAG System Component
Books on shelves	Original text files stored in Amazon S3
Individual pages	Document chunks
Catalog cards	Embeddings (numerical representations of meaning)
Searching the catalog	Pinecone similarity search
Top three selected pages	Top three matching text chunks
Librarian giving the answer	Amazon Nova Lite generating the response

Understanding Embeddings

An embedding is just a snippet of text converted into a list of numbers (a vector) that represents its core meaning. Words or phrases with similar meanings end up near each other in digital space.

For instance, a traditional keyword search might miss the connection between these two sentences:

"Where did I save the uploaded document?"
"Which service stores my note files?"

Because they share few identical words, keyword search struggles. But a semantic search using embeddings recognizes that both sentences ask about file storage.

System Architecture

The application handles two main workflows: Ingestion (saving and indexing notes) and Querying (searching notes and answering questions).

How Notes Get Ingested

Upload: You send a .txt file to the Flask backend.
Validation: Flask checks the file format, size, and character encoding.
Storage: The full original file goes to a private Amazon S3 bucket.
Chunking: The document text is cut into smaller, overlapping snippets.
Embedding: Amazon Titan converts each text snippet into a 512-dimensional vector.
Indexing: Pinecone stores the vectors along with original text snippet metadata.

How Questions Get Answered

Ask: You send a question to the /ask endpoint.
Embed Question: Amazon Titan converts your question into a vector.
Search: Pinecone retrieves the top 3 closest matching note snippets.
Prompt Assembly: The question and the 3 snippets are combined into an instruction prompt.
Generate Answer: Amazon Nova Lite reads the prompt and writes a factual response.
Response: Flask returns the final answer as JSON.

Code Walkthrough

1. Step 1: Validating Incoming Uploads

Security starts at the entry point. The /ingest endpoint accepts multipart form data and runs several checks before touching the rest of our system:

# Check for file presence and secure filename
if "file" not in request.files:
    return error_response("MISSING_FILE", "No file was provided", 400)

uploaded_file = request.files["file"]
filename = secure_filename(uploaded_file.filename or "")

if not filename or os.path.splitext(filename)[1].lower() != ".txt":
    return error_response("INVALID_FILE_TYPE", "Only UTF-8 .txt files are accepted", 415)

# Validate encoding and content readability
content = uploaded_file.read()
if not content:
    return error_response("EMPTY_FILE", "Uploaded text file is empty", 400)

try:
    decoded_content = content.decode("utf-8")
except UnicodeDecodeError:
    return error_response("INVALID_TEXT_ENCODING", "Text file must use UTF-8 encoding", 400)

if not decoded_content.strip() or "\x00" in decoded_content:
    return error_response("INVALID_TEXT_CONTENT", "File must contain valid text", 400)

Catching bad requests early with specific errors like INVALID_FILE_TYPE prevents corrupted files from crashing downstream services like Pinecone or S3.

2. Step 2: Saving Raw Files to S3

Once validated, the file goes to S3. To avoid accidental overwrites when uploading multiple files with generic names like notes.txt, the application generates a unique ID (UUID) for each storage key while keeping the real filename in S3 metadata:

def upload_text_file(file_path: str, original_filename: str) -> tuple[str, str]:
    bucket = os.getenv("S3_DOCUMENT_BUCKET")
    # Create a unique path key
    key = f"uploads/{uuid4().hex}.txt"

    boto3.client("s3").upload_file(
        file_path,
        bucket,
        key,
        ExtraArgs={
            "ContentType": "text/plain; charset=utf-8",
            "Metadata": {"original-filename": Path(original_filename).name},
        },
    )
    return bucket, key

3. Step 3: Chunking Text for Precision

Sending entire long documents directly into vector search reduces precision. We split text into chunks using LangChain's RecursiveCharacterTextSplitter:

text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=100,
)
docs = text_splitter.split_documents(documents)

Why include overlap?

If a key idea gets split right at character 1,000, half of the context ends up in Chunk A and half in Chunk B. Overlapping neighboring chunks by 100 characters preserves complete sentences and context across boundaries.

4. Step 4: Vector Embedding & Indexing

Next, we convert text chunks into numbers using Amazon Titan Text Embeddings V2 and save them into Pinecone:

embedding = BedrockEmbeddings(
    model_id="amazon.titan-embed-text-v2:0",
    dimensions=512,
    normalize=True,
    region_name="ap-south-1",
)

PineconeVectorStore.from_documents(
    docs,
    index_name=index_name,
    embedding=embedding,
    namespace="default",
)

Golden Rule: Your document chunks and your incoming search questions must use the exact same embedding model, dimension count, and normalization settings. Otherwise, vector distances become meaningless.

5. Step 5 & 6: Retrieval & Answer Generation

When asking a question via /ask, Pinecone finds the three nearest chunks:

# Grab top 3 matching snippets
documents = docsearch.as_retriever(search_kwargs={"k": 3}).invoke(question.strip())
context_str = "\n\n".join(doc.page_content for doc in documents)

We pass those snippets into Amazon Nova Lite with strict prompt instructions:

PROMPT = ChatPromptTemplate.from_template(
    """Answer the question using only the context below.

Context:
{context}

Question: {question}
"""
)

llm = ChatBedrockConverse(
    model_id="amazon.nova-lite-v1:0",
    temperature=0.2, # Low temperature keeps answers factual
    max_tokens=512,
)

chain = PROMPT | llm | StrOutputParser()
answer = chain.invoke({"question": question, "context": context_str})

Serverless Deployment Highlights

For local development, Flask handles traditional HTTP calls. When deploying to AWS, we run Flask inside AWS Lambda behind an API Gateway using serverless-wsgi:

import serverless_wsgi
from server import app

def handler(event, context):
    return serverless_wsgi.handle_request(app, event, context)

The underlying infrastructure is configured in AWS CloudFormation:

API Gateway: Routes endpoint traffic (/health, /ingest, /ask).
AWS Lambda: Hosts the application logic on Python 3.12.
IAM Roles: Grants minimal execution permissions for Bedrock, S3, and CloudWatch.

Key Takeaways & Lessons Learned

RAG Is a Search System First: If retrieval yields poor or irrelevant snippets, even the best LLM will fail to give a good answer.
Consistency Is Critical: Embedding settings during ingestion must match query settings perfectly.
Standard Software Engineering Matters: Machine learning features still rely on traditional tasks like request validation, error handling, file cleanup, and IAM security.
Context Grounding Controls Hallucinations: Explicit system prompts prevent the AI model from making up facts outside your uploaded notes.

My GitHub repo : my-rag-notes-app

LangChain vs Strands SDK with Amazon Bedrock

Jamal — Wed, 05 Aug 2026 12:51:47 +0000

LangChain, LangGraph, and Strands: Concept Map

This guide compares LangChain, LangGraph, and the Strands Agents SDK using the
weather-agent examples in this repository. It is intended both for learning and
for explaining the technologies to others.

1. The short explanation

Strands Agents SDK provides a concise, model-driven way to build agents, especially when working with Amazon Bedrock and AWS services.
LangChain provides standard abstractions for models, messages, prompts, tools, retrieval, structured output, and agents.
LangGraph provides explicit control over long-running, stateful agent workflows using nodes, edges, state, and checkpoints.
Amazon Bedrock is the managed AWS service that hosts the foundation model.
AgentCore is an AWS platform for operating agents securely in production.

LangChain and Strands help construct an agent. LangGraph becomes especially
useful when the workflow needs controlled routing, persistence, human approval,
or multiple collaborating agents.

2. Technology-layer mapping

Layer	Strands / AWS choice	LangChain / LangGraph choice	Purpose
Foundation model	Amazon Nova, Claude, or another Bedrock model	The same model	Generates responses and decides when to call tools
Model service	Amazon Bedrock	Amazon Bedrock	Hosts and invokes the model
Model adapter	`BedrockModel`	`ChatBedrockConverse`	Connects application code to Bedrock
Agent API	`Agent`	`create_agent`	Runs the model–tool reasoning loop
Tool definition	Strands `@tool`	LangChain `@tool`	Exposes a Python function to the model
Conversation input	String or message objects	Message dictionaries or message objects	Carries user and assistant messages
Agent instructions	`system_prompt`	`system_prompt`	Defines the agent's role and behavior
Workflow orchestration	Agents, hooks, and custom application logic	LangGraph nodes and edges	Controls multi-step execution
Workflow state	Agent/application state	Typed LangGraph state	Shares data between workflow steps
Persistence	Application or runtime integration	LangGraph checkpointer/store	Saves conversation and workflow progress
Production runtime	AgentCore Runtime	AgentCore, containers, or another runtime	Hosts and operates the agent
Observability	AWS tooling and Strands integrations	LangSmith, callbacks, and AWS tooling	Traces and evaluates executions

3. Weather-agent mapping

The files strand-agent.py and
langchain-agent.py implement the same use case.

Concept	Strands example	LangChain example
Import the agent	`from strands import Agent`	`from langchain.agents import create_agent`
Import the tool decorator	`from strands import tool`	`from langchain.tools import tool`
Configure Bedrock	`BedrockModel(...)`	`ChatBedrockConverse(...)`
Declare a tool	`@tool` above `get_weather`	`@tool` above `get_weather`
Register the tool	`tools=[get_weather]`	`tools=[get_weather]`
Create the agent	`Agent(...)`	`create_agent(...)`
Invoke the agent	`agent(question)`	`agent.invoke({"messages": [...]})`
Read the answer	Returned result	Last message in `result["messages"]`

The @tool decorators look similar, but they belong to different SDKs. In both
cases, the function name, type hints, and docstring help the model understand
when and how to call the tool.

4. How the weather agent works

import json
import os
import ssl
import sys
from urllib.parse import urlencode
from urllib.request import urlopen

import certifi
from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain.tools import tool
from langchain_aws import ChatBedrockConverse


load_dotenv()

SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())


def get_json(url: str, params: dict[str, str | int]) -> dict:
    """Make a small JSON GET request using only the Python standard library."""
    request_url = f"{url}?{urlencode(params)}"
    with urlopen(request_url, timeout=10, context=SSL_CONTEXT) as response:  # noqa: S310
        return json.load(response)


@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city. Use this for weather questions."""
    try:
        places = get_json(
            "https://geocoding-api.open-meteo.com/v1/search",
            {"name": city, "count": 1, "language": "en", "format": "json"},
        ).get("results", [])

        if not places:
            return f"I could not find a location matching {city!r}."

        place = places[0]
        weather = get_json(
            "https://api.open-meteo.com/v1/forecast",
            {
                "latitude": place["latitude"],
                "longitude": place["longitude"],
                "current": "temperature_2m,apparent_temperature,weather_code,wind_speed_10m",
                "timezone": "auto",
            },
        )["current"]

        return (
            f"Current weather in {place['name']}, {place.get('country', '')}: "
            f"temperature {weather['temperature_2m']}°C, "
            f"feels like {weather['apparent_temperature']}°C, "
            f"wind speed {weather['wind_speed_10m']} km/h, "
            f"WMO weather code {weather['weather_code']}."
        )
    except Exception as error:
        return f"Weather lookup failed: {error}"


model = ChatBedrockConverse(
    model_id=os.getenv("BEDROCK_MODEL_ID", "global.amazon.nova-2-lite-v1:0"),
    region_name=os.getenv("AWS_REGION", "eu-west-2"),
    temperature=0,
)

agent = create_agent(
    model=model,
    tools=[get_weather],
    system_prompt="You are a helpful weather assistant. Use the weather tool when needed.",
)


if __name__ == "__main__":
    question = " ".join(sys.argv[1:]) or "What is the weather in Kolkata, India?"
    result = agent.invoke({"messages": [{"role": "user", "content": question}]})
    print(result["messages"][-1].content)

*Strands SDK
*

import json
import os
import ssl
import sys
from urllib.parse import urlencode
from urllib.request import urlopen

import certifi
from dotenv import load_dotenv
from strands import Agent, tool
from strands.models.bedrock import BedrockModel


load_dotenv()

SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())


def get_json(url: str, params: dict[str, str | int]) -> dict:
    """Make a small JSON GET request using only the Python standard library."""
    request_url = f"{url}?{urlencode(params)}"
    with urlopen(request_url, timeout=10, context=SSL_CONTEXT) as response:  # noqa: S310
        return json.load(response)


@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city.

    Args:
        city: City name, optionally including its state or country.
    """
    try:
        places = get_json(
            "https://geocoding-api.open-meteo.com/v1/search",
            {"name": city, "count": 1, "language": "en", "format": "json"},
        ).get("results", [])

        if not places:
            return f"I could not find a location matching {city!r}."

        place = places[0]
        weather = get_json(
            "https://api.open-meteo.com/v1/forecast",
            {
                "latitude": place["latitude"],
                "longitude": place["longitude"],
                "current": "temperature_2m,apparent_temperature,weather_code,wind_speed_10m",
                "timezone": "auto",
            },
        )["current"]

        return (
            f"Current weather in {place['name']}, {place.get('country', '')}: "
            f"temperature {weather['temperature_2m']}°C, "
            f"feels like {weather['apparent_temperature']}°C, "
            f"wind speed {weather['wind_speed_10m']} km/h, "
            f"WMO weather code {weather['weather_code']}."
        )
    except Exception as error:
        return f"Weather lookup failed: {error}"


model = BedrockModel(
    model_id=os.getenv("BEDROCK_MODEL_ID", "global.amazon.nova-2-lite-v1:0"),
    region_name=os.getenv("AWS_REGION", "eu-west-2"),
    temperature=0,
)

agent = Agent(
    model=model,
    tools=[get_weather],
    system_prompt="You are a helpful weather assistant. Use the weather tool when needed.",
    callback_handler=None,
)


if __name__ == "__main__":
    question = " ".join(sys.argv[1:]) or "What is the weather in Kolkata, India?"
    result = agent(question)
    print(result)

User question
     |
     v
Agent sends the question and tool definition to the Bedrock model
     |
     v
Model selects get_weather(city="London")
     |
     v
Tool converts the city to latitude and longitude with Open-Meteo geocoding
     |
     v
Tool requests current weather from Open-Meteo
     |
     v
Tool result is returned to the model
     |
     v
Model produces a natural-language answer

Important distinction: the model does not directly access the weather service.
It chooses a registered tool, and the application executes that Python function.

5. Core vocabulary

Model

The foundation model performs language understanding, response generation, and
tool selection. In these examples, the model is accessed through Amazon Bedrock.

Prompt

A prompt is the information sent to the model. It can include system
instructions, conversation messages, tool descriptions, and tool results.

System prompt

The system prompt defines high-level behavior, for example:

You are a helpful weather assistant. Use the weather tool when needed.

Tool

A tool is an application-controlled capability exposed to the model. Examples
include calling an API, reading a database, searching documents, or creating a
support ticket.

Tool calling

Tool calling is the process in which the model returns a structured request such
as get_weather(city="London"). The SDK validates and executes the request and
returns the result to the model.

Agent

An agent combines a model, instructions, and tools with an execution loop. The
loop continues until the model returns a final answer or reaches a configured
limit.

State

State is data retained during a workflow. It may contain messages, tool results,
user information, approval status, or intermediate calculations.

Memory

Memory is information retained across interactions. Short-term memory commonly
means conversation history; long-term memory may store facts across sessions.
Memory is not the same as a model's context window.

Checkpoint

A checkpoint is a persisted snapshot of workflow state. LangGraph checkpoints
allow a workflow to pause, resume, recover, and maintain separate conversation
threads.

Node and edge

In LangGraph, a node performs a unit of work and an edge determines which
node runs next. A conditional edge routes execution based on current state.

Human in the loop

Human-in-the-loop design pauses execution before a sensitive action so a person
can approve, reject, or edit it. LangGraph supports this through interrupts and
persisted state.

Structured output

Structured output asks the model to return data matching a schema instead of
free-form prose. It is useful when downstream code needs reliable fields.

Retrieval-augmented generation (RAG)

RAG retrieves relevant information from external sources and includes it in the
model's context. Retrieval supplies knowledge; an agent decides and acts. A
system can use both.

6. Similarities

Both LangChain and Strands:

support Amazon Bedrock models;
allow Python functions to become model-callable tools;
run a model–tool–model loop;
use system prompts to guide behavior;
support streaming and conversation messages;
can be extended with custom tools and production integrations.

The central pattern is the same:

model + instructions + tools + execution loop = agent

7. Important differences

Topic	Strands	LangChain / LangGraph
Primary style	Compact and agent-first	Broad component ecosystem plus graph orchestration
AWS alignment	Designed with strong AWS integration	Provider-neutral, with AWS integrations
Simple agent setup	Very concise	Concise with `create_agent`
Explicit workflow control	Usually application logic or SDK patterns	A core LangGraph feature
State graph	Not a direct one-to-one abstraction	Nodes, edges, reducers, and subgraphs
Ecosystem	Focused agent SDK and AWS ecosystem	Large integration and retrieval ecosystem
Production hosting	Natural fit with AgentCore	Multiple deployment choices, including AgentCore

These differences do not mean one framework is universally better. The choice
depends on the required integrations, workflow complexity, operating platform,
and the team's preferred abstractions.

8. When to introduce LangGraph

A simple weather agent does not require a custom graph. Introduce LangGraph when
the application needs one or more of the following:

deterministic stages around the agent;
conditional routing;
durable conversation state;
pause and resume;
human approval before side effects;
retry or recovery behavior;
parallel branches;
multiple specialized agents;
a workflow that must be inspected and tested step by step.

Example controlled workflow:

START -> classify request -> retrieve data -> draft answer -> approval -> END
                  |                                  |
                  +-> reject unsupported request     +-> revise

9. Bedrock and AgentCore are different layers

It is useful to avoid combining these terms:

Bedrock supplies access to foundation models and related AI services.
The SDK or framework defines agent logic and connects models to tools.
AgentCore supplies production capabilities for deploying and operating agents.

A possible production stack is:

User interface
      |
AgentCore Runtime
      |
LangChain/LangGraph or Strands application
      |
Amazon Bedrock model + application tools

10. Suggested presentation order

Start with the problem: answer a live weather question.
Explain why the model alone cannot know guaranteed current weather.
Introduce the get_weather tool.
Show the agent deciding to call that tool.
Compare the Strands and LangChain implementations line by line.
Introduce LangGraph only after showing a need for controlled workflows.
Finish by separating construction, model hosting, and production runtime.

11. Learning path

Run both weather examples and compare their output.
Add a second tool, such as a weather forecast tool.
Return structured weather data using a schema.
Add conversation history for follow-up questions like “How about tomorrow?”
Build a LangGraph that routes current-weather and forecast requests.
Add a human approval step before a tool with real-world side effects.
Add persistence, tracing, evaluation, and deployment.

12. Commands for the examples

uv run python strand-agent.py "What is the weather in London?"
uv run python langchain-agent.py "What is the weather in London?"

Both examples use the same Bedrock defaults and accept these environment
variables:

export AWS_REGION="eu-west-2"
export BEDROCK_MODEL_ID="global.amazon.nova-2-lite-v1:0"

Normal AWS credentials must also be available through an AWS profile,
environment variables, or an assigned IAM role.

# 🤖 Lab 07: Building Multi-Agent Systems with an Orchestrator | Strands Agentic AI

Jamal — Sun, 31 May 2026 06:06:09 +0000

So far in this series, we've built agents, custom tools, MCP integrations, and MCP servers.

But real-world AI applications often require multiple specialists working together.

Instead of creating one giant agent responsible for everything, we can create multiple specialized agents and use a central orchestrator to route requests to the right expert.

In this lab, we'll build:

A Study Assistant
An Expense Assistant
An Orchestrator Agent

The orchestrator will decide which specialist should handle the user's request.

By the end of this tutorial, you'll understand one of the most important patterns in Agentic AI: Multi-Agent Architectures.

📚 Strands Agentic AI Lab Series

⬅️ Previous: Lab 07: Build Your First MCP Server

📍 Current: Lab 08: Building Multi-Agent Systems

➡️ Next: Lab 09: Agent Collaboration & Sequential Workflows

🚀 What You'll Learn

In this lab, you'll learn:

What multi-agent systems are
Why specialized agents outperform general-purpose agents
How to build reusable agents
How to create an orchestrator agent
How to route requests dynamically
How to add logging for debugging

🤖 Why Multi-Agent Systems?

Imagine building a personal assistant that can help with:

Studying
Budgeting
Fitness
Travel
Career advice

You could create one massive prompt. Or you could create specialists.

User
  ↓
Orchestrator
  ↓
 ├── Study Agent
 ├── Expense Agent
 ├── Fitness Agent
 └── Travel Agent

This approach is:

✅ Easier to maintain
✅ Easier to scale
✅ Easier to test
✅ More accurate

This architecture is commonly used in enterprise AI systems.

🛠️ Prerequisites

Before starting, make sure you have:

Python 3.10+
Strands SDK
AWS account
Amazon Bedrock access
AWS credentials configured
uv installed

🏗️ Architecture Overview

Our application looks like this:

User
  ↓
Orchestrator Agent
  ↓
 ├── study_assistant()
 │      ↓
 │   Study Agent
 │
 └── expense_assistant()
        ↓
     Expense Agent

The orchestrator never answers directly. Its job is to decide which specialist should handle the request.

📜 The Complete Script

This lab introduces:

Reusable agent creation
Specialized agents
Tool-based routing
Agent orchestration
Structured logging

Let's break it down step by step.

⚙️ Step 1: Configure Logging

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s | %(levelname)s | %(message)s",
)

Logging helps us understand:

Which agent was selected
Which tool was called
What response was generated
Any errors that occurred

Example output:

INFO | User query received
INFO | study_assistant called
DEBUG | Study response generated

This becomes incredibly useful when debugging complex multi-agent systems.

⚙️ Step 2: Configure the Bedrock Model

bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

All agents in this lab share the same Bedrock model. This keeps the architecture simple. In production, different agents may use different models.

⚙️ Step 3: Create a Reusable Agent Factory

def create_agent(
    name: str,
    system_prompt: str
) -> Agent:
    ...

This helper function creates specialized agents.

Benefits:

Less code duplication
Consistent configuration
Easier maintenance

Instead of repeating:

Agent(...)
Agent(...)
Agent(...)

we centralize the logic.

⚙️ Step 4: Create Specialized Agents

Study Agent

study_agent = create_agent(
    name="study_agent",
    system_prompt="""
    You are a study assistant.
    Help users create learning plans.
    """
)

Responsibilities:

Learning plans
Courses
Certifications
Exams
Technical concepts

Expense Agent

expense_agent = create_agent(
    name="expense_agent",
    system_prompt="""
    You are an expense assistant.
    Help users manage budgets.
    """
)

Responsibilities:

Budgeting
Savings
Spending analysis
Cost reduction
Financial planning

Each agent becomes an expert in its own domain.

⚙️ Step 5: Expose Agents as Tools

Study Tool

@tool
def study_assistant(query: str) -> str:
    ...

This wraps the Study Agent as a tool.

Tool Call
     ↓
Study Agent
     ↓
Response

Expense Tool

@tool
def expense_assistant(query: str) -> str:
    ...

This wraps the Expense Agent.

Tool Call
     ↓
Expense Agent
     ↓
Response

Now the orchestrator can invoke either specialist.

⚙️ Step 6: Create the Orchestrator Prompt

orchestrator_prompt = """
You are a router assistant.
"""

This prompt defines routing rules.

Study topics: study, learning, courses, practice, certifications, exams

Expense topics: budget, money, savings, spending, expenses, cost

The orchestrator's job is not to answer — its job is to route. Think of it as a smart receptionist.

⚙️ Step 7: Build the Orchestrator Agent

orchestrator_agent = Agent(
    system_prompt=orchestrator_prompt,
    model=bedrock_model,
    tools=[
        study_assistant,
        expense_assistant,
    ],
)

This is the brain of the system. It receives the user request and chooses the correct specialist.

User
 ↓
Orchestrator
 ↓
Correct Tool
 ↓
Specialized Agent

▶️ Run the Application

python agent.py

Or:

uv run labs/08-multi-agent-orchestrator/agent.py

📊 Example Interaction #1

User:

Help me prepare for AWS Cloud Practitioner.

Routing:

Orchestrator → study_assistant → Study Agent

Response:

Here's a 4-week AWS Cloud Practitioner study plan...

📊 Example Interaction #2

User:

How can I save ₹5000 every month?

Routing:

Orchestrator → expense_assistant → Expense Agent

Response:

Let's review your monthly expenses and identify savings opportunities...

📊 Example Interaction #3

User:

I have an exam next month and need a budget for training materials.

This query touches multiple domains. The orchestrator may:

Ask a clarification question
Choose the dominant topic
Route accordingly

This demonstrates why orchestration logic matters.

🔍 What Happened Behind the Scenes?

When a user submits a request:

User Query
     ↓
Orchestrator Agent
     ↓
Tool Selection
     ↓
Specialized Agent
     ↓
Response

The orchestrator never becomes an expert — instead, it delegates expertise. This pattern is called Agent Orchestration, and it's widely used in production AI systems.

💡 Why Developers Love This Pattern

Without multi-agent systems:

❌ Huge prompts
❌ Mixed responsibilities
❌ Difficult maintenance
❌ Poor scalability

With multi-agent systems:

✅ Specialized expertise
✅ Easier debugging
✅ Modular design
✅ Independent evolution
✅ Better scalability

Each agent focuses on one job and does it well.

🌍 Real-World Use Cases

This same architecture powers:

Customer Support — Billing Agent, Technical Agent, Escalation Agent

Healthcare — Symptoms Agent, Insurance Agent, Appointment Agent

Enterprise Operations — HR Agent, Finance Agent, IT Agent, Legal Agent

Personal Assistants — Study Agent, Budget Agent, Fitness Agent, Travel Agent

The possibilities are endless.

🎯 Key Takeaways

Multi-agent systems separate responsibilities
Specialized agents improve accuracy
Orchestrators route requests intelligently
Tools can act as wrappers around agents
Logging makes orchestration easier to debug
This pattern scales extremely well in production

📚 Source Code

GitHub Repository: d3vjamal/strands-agents-labs

🔗 Continue Learning

⬅️ Previous Lab: Lab 06: Build Your First MCP Server with Streamable HTTP | Strands Agentic AI

➡️ Next Lab: In the next tutorial, we'll move beyond simple routing and explore how multiple agents can collaborate together, passing information between each other to solve complex tasks that no single agent can handle alone.

# 🧮 Lab 06: Build Your First MCP Server with Streamable HTTP | Strands Agentic AI

Jamal — Sun, 31 May 2026 04:48:00 +0000

In the previous labs, we connected a Strands Agent to an existing MCP server and used its tools.

But what if you want to create your own MCP server?

That's exactly what we'll do in this lab.

We'll build a Calculator MCP Server that exposes arithmetic operations such as addition, subtraction, multiplication, and division. Then we'll connect a Strands Agent to that server using Streamable HTTP transport.

By the end of this tutorial, you'll understand both sides of the MCP ecosystem:

MCP Server
MCP Client
Strands Agent

📚 Strands Agentic AI Lab Series

⬅️ Previous: Lab 06: Connecting to MCP with STDIO

📍 Current: Lab 07: Build Your First MCP Server

➡️ Next: Lab 08: Advanced MCP Tools & Multi-Tool Workflows

🚀 What You'll Learn

In this lab, you'll learn:

How to create an MCP Server
How MCP tools are exposed
How Streamable HTTP transport works
How to connect a Strands Agent to a custom MCP server
How agents invoke MCP tools automatically

🤖 Why Build Your Own MCP Server?

Previously we consumed an existing MCP server.

Agent
  ↓
AWS Documentation MCP Server

Now we'll build one ourselves.

Agent
  ↓
Your MCP Server
  ↓
Your Tools

This allows you to expose:

Internal APIs
Databases
Business Logic
Enterprise Systems
Custom Applications

through a standard MCP interface.

🏗️ Architecture

Our solution looks like this:

User
  ↓
Strands Agent
  ↓
MCP Client
  ↓
Calculator MCP Server
  ↓
Calculator Tools

The agent doesn't perform calculations directly.

Instead, it delegates them to MCP tools.

🛠️ Prerequisites

Before starting, ensure you have:

Python 3.10+
Strands SDK
MCP SDK
AWS Bedrock access
uv installed

Install dependencies:

pip install strands-agents
pip install mcp

📜 The Complete Script

This example creates:

An MCP Calculator Server
Four calculator tools
A Strands Agent
An interactive chat loop

The agent automatically uses MCP tools whenever calculations are required.

⚙️ Step 1: Create the MCP Server

mcp = FastMCP("Calculator Server")

This initializes a new MCP server.

Think of it as:

Web Framework
    ↓
Routes

but for AI tools.

MCP Server
    ↓
Tools

⚙️ Step 2: Create MCP Tools

Addition Tool

@mcp.tool(description="Add two numbers together")
def add(x: int, y: int) -> int:
    return x + y

Subtraction Tool

@mcp.tool(description="Subtract one number from another")
def subtract(x: int, y: int) -> int:
    return x - y

Multiplication Tool

@mcp.tool(description="Multiply two numbers together")
def multiply(x: int, y: int) -> int:
    return x * y

Division Tool

@mcp.tool(description="Divide one number by another")
def divide(x: float, y: float) -> float:
    if y == 0:
        raise ValueError("Cannot divide by zero")

    return x / y

Every tool becomes automatically discoverable through MCP.

No additional registration is required.

⚙️ Step 3: Start the MCP Server

mcp.run(
    transport="streamable-http"
)

This launches the MCP server using Streamable HTTP transport.

Server endpoint:

http://localhost:8000

Now other MCP clients can connect.

⚙️ Step 4: Run the Server in a Background Thread

server_thread = threading.Thread(
    target=start_calculator_server,
    daemon=True
)

Why?

Because we need:

Calculator Server
      +
Strands Agent

running simultaneously.

The background thread keeps the server alive while the agent runs.

⚙️ Step 5: Connect the MCP Client

def create_streamable_http_transport():
    return streamablehttp_client(
        "http://localhost:8000/mcp/"
    )

This creates an MCP Client connection.

Architecture:

Agent
   ↓
MCP Client
   ↓
HTTP Transport
   ↓
Calculator Server

⚙️ Step 6: Discover Available Tools

tools = streamable_http_mcp_client.list_tools_sync()

This is one of MCP's biggest advantages.

Instead of manually registering tools:

tools=[add, subtract]

the client automatically discovers them.

Example:

Available MCP tools:

add
subtract
multiply
divide

⚙️ Step 7: Create the Agent

agent = Agent(
    model=bedrock_model,
    system_prompt=system_prompt,
    tools=tools
)

Notice:

tools=tools

Those tools came directly from the MCP Server.

No custom integration required.

⚙️ Step 8: Interactive Calculator Assistant

while True:
    user_input = input("Question: ")

    response = agent(user_input)

    print(response)

This creates a conversational calculator.

Example:

Question:
What is 125 * 42?

Agent:

Behind the scenes:

Agent
 ↓
multiply()
 ↓
5250

▶️ Run the Application

Execute:

python agent.py

Or:

uv run labs/07-mcp-calculator-server/agent.py

📊 Example Interaction

User

What is 25 + 17?

Agent Workflow

Question
   ↓
Agent Reasoning
   ↓
add Tool
   ↓
42
   ↓
Response

Response

25 + 17 = 42

🔍 What Happened Behind the Scenes?

When you asked:

What is 25 + 17?

the agent:

Understood the request.
Found an MCP tool capable of addition.
Invoked the tool.
Received the result.
Generated a response.

The actual calculation happened in the MCP Server.

Not in the LLM.

💡 Why This Matters

This simple calculator demonstrates a powerful concept.

Today:

add()
subtract()
multiply()
divide()

Tomorrow:

Create Customer
Generate Invoice
Query Database
Deploy Lambda
Update CRM

The exact same MCP architecture scales to enterprise applications.

🎯 Key Takeaways

MCP Servers expose tools to AI agents
FastMCP makes building servers simple
Streamable HTTP enables remote communication
Agents automatically discover tools
MCP separates tool implementation from agent logic
This pattern scales from calculators to enterprise systems

📚 Source Code

Lab Source Code:
Your GitHub Repository

🔗 Continue Learning

⬅️ Previous Lab

Lab 05: Connecting to an MCP Server with STDIO Transport | Strands Agentic AI

➡️ Next Lab

Lab 07: Building Multi-Agent Systems with an Orchestrator | Strands Agentic AI

🚀 Next Lab

In the next tutorial, we'll build more sophisticated MCP tools, explore tool schemas, and learn how agents can choose between multiple MCP capabilities to solve complex tasks.

# 🚀 Lab 05: Connecting to an MCP Server with STDIO Transport | Strands Agentic AI

Jamal — Sun, 31 May 2026 04:14:05 +0000

In the previous lab, we learned what Model Context Protocol (MCP) is and why it is becoming the standard way for AI agents to access tools and external systems.

Now it's time to build a real MCP-powered agent.

In this lab, you'll connect a Strands Agent to the AWS Documentation MCP Server using STDIO transport and allow the agent to retrieve information directly from AWS documentation.

By the end of this tutorial, you'll have an AWS Documentation Assistant capable of answering AWS questions using MCP-provided tools.

📚 Strands Agentic AI Lab Series

⬅️ Previous: Lab 05: Introduction to MCP

📍 Current: Lab 06: Connecting to an MCP Server with STDIO Transport

➡️ Next: Lab 07: Exploring MCP Tools and Capabilities

🚀 What You'll Learn

In this lab, you'll learn:

What STDIO transport is
How MCP clients communicate with MCP servers
How to connect to an AWS Documentation MCP Server
How to discover available tools dynamically
How to build an AI assistant powered by MCP tools

🤖 Why STDIO Transport?

MCP supports multiple communication methods.

The simplest is STDIO.

Agent
  ↓
STDIO
  ↓
MCP Server

Instead of communicating over a network, the agent and MCP server communicate through standard input and output streams.

Benefits:

Simple setup
Fast local development
No network configuration
Great for experimentation

Think of STDIO as two applications having a direct private conversation.

🛠️ Prerequisites

Before starting, make sure you have:

Python 3.10+
AWS credentials configured
Amazon Bedrock access
uv installed
Strands SDK installed
MCP SDK installed

Install dependencies:

pip install strands-agents
pip install mcp

📜 The Script

Let's start with the complete example.

from strands import Agent, tool
from strands.models.bedrock import BedrockModel

from strands.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

# Bedrock
bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

# Connect to an MCP server using stdio transport
stdio_mcp_client = MCPClient(lambda: stdio_client(
    StdioServerParameters(
        command="uvx",
        args=["awslabs.aws-documentation-mcp-server@latest"]
    )
))

with stdio_mcp_client:
    tools = stdio_mcp_client.list_tools_sync()

    agent = Agent(
        system_prompt="""
        You are an AWS Documentation expert.
        Use the tools that are available to provide factual information.
        """,
        model=bedrock_model,
        tools=tools
    )

    agent("What is AWS Lambda?")

Now let's break it down.

⚙️ Step 1: Import MCP Components

from strands.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

These imports provide the building blocks for MCP communication.

MCPClient

Creates a bridge between Strands and the MCP server.

stdio_client

Handles communication over standard input and output.

StdioServerParameters

Defines how the MCP server should start.

⚙️ Step 2: Configure the Bedrock Model

bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

This model performs:

Reasoning
Tool selection
Response generation

The MCP server provides tools.

The LLM decides how to use them.

⚙️ Step 3: Configure the MCP Server

stdio_mcp_client = MCPClient(
    lambda: stdio_client(
        StdioServerParameters(
            command="uvx",
            args=[
                "awslabs.aws-documentation-mcp-server@latest"
            ]
        )
    )
)

This launches the AWS Documentation MCP Server.

Architecture:

Strands Agent
       ↓
MCP Client
       ↓
AWS Documentation MCP Server
       ↓
AWS Documentation Tools

The MCP server automatically exposes tools to the agent.

⚙️ Step 4: Platform Differences

macOS/Linux

command="uvx"
args=[
    "awslabs.aws-documentation-mcp-server@latest"
]

Windows

command="uvx"
args=[
    "--from",
    "awslabs.aws-documentation-mcp-server@latest",
    "awslabs.aws-documentation-mcp-server.exe"
]

The server package is the same.

Only the launch syntax changes.

⚙️ Step 5: Start the MCP Session

with stdio_mcp_client:

This starts the MCP server session.

Once inside the context:

Server launches
Connection is established
Tools become available

When execution completes, resources are cleaned up automatically.

⚙️ Step 6: Discover Available Tools

tools = stdio_mcp_client.list_tools_sync()

This is where MCP becomes powerful.

Instead of manually creating tools:

@tool
def search_docs():
    ...

You can simply discover tools provided by the server.

Connect
    ↓
Discover
    ↓
Use

No custom tool implementation required.

⚙️ Step 7: Create the Agent

agent = Agent(
    system_prompt="""
    You are an AWS Documentation expert.
    Use the tools that are available to provide factual information.
    """,
    model=bedrock_model,
    tools=tools
)

Notice:

tools=tools

These tools come directly from the MCP server.

The agent now has access to AWS documentation capabilities without any additional coding.

⚙️ Step 8: Ask a Question

agent("What is AWS Lambda?")

Workflow:

User Question
       ↓
Agent Analysis
       ↓
MCP Tool Selection
       ↓
AWS Documentation Search
       ↓
Information Retrieved
       ↓
Final Response

The agent uses official AWS documentation instead of relying only on model memory.

▶️ Run the Agent

Execute:

python agent.py

Or:

uv run labs/06-mcp-stdio-client/agent.py

📊 Example Interaction

User

What is AWS Lambda?

Agent Workflow

Question Received
       ↓
Discover Documentation Tool
       ↓
Query AWS Documentation
       ↓
Retrieve Results
       ↓
Generate Answer

Response

AWS Lambda is a serverless compute service that allows you to run code without provisioning or managing servers.

Lambda automatically scales your application and charges only for the compute time used.

🔍 What Happened Behind the Scenes?

When the question was asked:

The LLM analyzed the request.
It discovered documentation tools.
It selected the most relevant tool.
The MCP server retrieved AWS documentation.
Results were returned to the model.
The model generated the final answer.

The agent never needed a custom Python function.

The MCP server supplied everything.

💡 Why Developers Love MCP

Without MCP:

❌ Build custom integrations

❌ Maintain tools manually

❌ Write wrappers for every service

With MCP:

✅ Connect once

✅ Discover tools automatically

✅ Reuse existing integrations

✅ Build agents faster

MCP turns integrations into plug-and-play components.

🎯 Key Takeaways

STDIO is the simplest MCP transport
MCP servers expose tools dynamically
Agents can discover tools automatically
AWS Documentation MCP Server provides factual AWS information
MCP dramatically reduces integration effort
Strands Agents integrate seamlessly with MCP

📚 Source Code

GitHub Repository:

https://github.com/d3vjamal/strands-agents-labs

🔗 Continue Learning

⬅️ Previous Lab

Lab 05: Introduction to MCP

➡️ Next Lab

Lab 07: Exploring MCP Tools and Capabilities

🚀 Next Lab

In the next tutorial, we'll inspect the tools exposed by an MCP server, understand their schemas, and learn how agents choose the right tool for a given task.

# 🔌 Lab 05: Using MCP (Model Context Protocol) with Strands Agents | Strands Agentic AI

Jamal — Sun, 31 May 2026 04:05:33 +0000

So far in this series, we've built custom tools and taught agents how to interact with the outside world.

But what if someone else has already built the tools you need?

Instead of writing every integration yourself, you can connect your AI agent to an MCP Server.

Model Context Protocol (MCP) is an open standard that allows AI agents to discover and use tools provided by external systems.

In this lab, you'll connect a Strands Agent to the AWS Documentation MCP Server and allow the agent to retrieve factual AWS documentation directly from official sources.

By the end of this lab, you'll have an AWS Documentation Assistant powered by MCP.

🚀 What You'll Learn

In this lab, you'll learn:

What MCP (Model Context Protocol) is
Why MCP is becoming important in Agentic AI
How to connect to an MCP server
How to use STDIO transport
How agents automatically discover MCP tools
How to build an AWS Documentation Assistant

🤖 What is MCP?

Model Context Protocol (MCP) is an open protocol that allows AI models and agents to connect to external tools and data sources.

Think of MCP as:

USB for AI Agents

Just as USB allows computers to connect to keyboards, printers, and storage devices, MCP allows AI agents to connect to:

Documentation systems
Databases
APIs
Search engines
Internal tools
Enterprise applications

Without MCP:

Agent
  ↓
Custom Tool
  ↓
External System

With MCP:

Agent
  ↓
MCP Server
  ↓
Many Tools

One connection can expose dozens of tools instantly.

🛠️ Prerequisites

Before starting, make sure you have:

Python 3.10+
AWS Account
Amazon Bedrock access
AWS credentials configured
uv installed
MCP SDK installed
Strands SDK installed

Install dependencies:

pip install strands-agents
pip install mcp

🌟 Why MCP Matters

Imagine you're building an AWS assistant.

Without MCP:

Build Tool #1
Build Tool #2
Build Tool #3
Build Tool #4
...

You must create and maintain every integration yourself.

With MCP:

Connect MCP Server
Discover Tools
Start Using Them

The MCP server handles the heavy lifting.

Your agent simply consumes the available tools.

This dramatically reduces development effort.

📜 The Script

Let's start by looking at the complete example.

from strands import Agent, tool
from strands.models.bedrock import BedrockModel

from strands.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

# Bedrock
bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

# Connect to an MCP server using stdio transport
stdio_mcp_client = MCPClient(
    lambda: stdio_client(
        StdioServerParameters(
            command="uvx",
            args=["awslabs.aws-documentation-mcp-server@latest"]
        )
    )
)

with stdio_mcp_client:
    tools = stdio_mcp_client.list_tools_sync()

    agent = Agent(
        system_prompt="""
        You are an AWS Documentation expert.
        Use the tools that are available to provide factual information.
        """,
        model=bedrock_model,
        tools=tools
    )

    agent("What is AWS Lambda?")

Now let's break it down.

⚙️ Step 1: Import MCP Components

from strands.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

These imports provide everything required to communicate with an MCP server.

Components

Component	Purpose
MCPClient	Connects Strands to MCP
stdio_client	Uses standard input/output transport
StdioServerParameters	Configures the MCP server

⚙️ Step 2: Configure Amazon Bedrock

bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

This is the reasoning engine behind our agent.

The model decides:

Which tool to use
What information to retrieve
How to respond

⚙️ Step 3: Create the MCP Connection

stdio_mcp_client = MCPClient(
    lambda: stdio_client(
        StdioServerParameters(
            command="uvx",
            args=[
                "awslabs.aws-documentation-mcp-server@latest"
            ]
        )
    )
)

This establishes a connection to the AWS Documentation MCP Server.

Think of it as:

Agent
  ↓
MCP Client
  ↓
AWS Documentation MCP Server

The server exposes AWS documentation tools automatically.

⚙️ Step 4: Understanding STDIO Transport

This lab uses STDIO transport.

Agent Process
      ⇅
Standard Input/Output
      ⇅
MCP Server Process

STDIO is ideal for:

Local development
Local testing
Lightweight integrations

Because communication happens through process streams, no network setup is required.

⚙️ Step 5: Start the MCP Session

with stdio_mcp_client:

This opens a connection to the MCP server.

Once inside the context manager:

Server starts
Tools become available
Agent can access them

When execution finishes, the connection closes automatically.

⚙️ Step 6: Discover Available Tools

tools = stdio_mcp_client.list_tools_sync()

This is one of the most powerful MCP features.

Instead of manually creating tools:

tools = stdio_mcp_client.list_tools_sync()

The agent automatically discovers everything exposed by the MCP server.

Think of it like:

Connect
    ↓
Discover Tools
    ↓
Use Tools

No additional coding required.

⚙️ Step 7: Create the Agent

agent = Agent(
    system_prompt="""
    You are an AWS Documentation expert.
    Use the tools that are available to provide factual information.
    """,
    model=bedrock_model,
    tools=tools
)

Notice something interesting.

We aren't manually registering tools.

Instead:

tools=tools

contains every tool discovered from the MCP server.

The agent now has access to AWS documentation capabilities.

⚙️ Step 8: Ask a Question

agent("What is AWS Lambda?")

The workflow becomes:

User Question
       ↓
Agent Analysis
       ↓
MCP Tool Selection
       ↓
AWS Documentation Search
       ↓
Documentation Retrieved
       ↓
Final Response

The answer comes from official AWS documentation rather than relying solely on model memory.

▶️ Run the Agent

Execute the script:

python agent.py

Or:

uv run labs/05-mcp-introduction/agent.py

📊 Example Interaction

User

What is AWS Lambda?

Agent Workflow

Question Received
       ↓
Discover Documentation Tool
       ↓
Query AWS Documentation
       ↓
Retrieve Information
       ↓
Generate Response

Agent Response

AWS Lambda is a serverless compute service that lets you run code without provisioning or managing servers.

You pay only for the compute time consumed and can automatically scale applications in response to demand.

The exact response may vary depending on the documentation version and model.

🔍 What Makes MCP Different?

Traditional Tool Approach:

Build Tool
Register Tool
Maintain Tool
Update Tool

MCP Approach:

Connect Server
Discover Tools
Use Tools

The MCP server owns the implementation.

Your agent simply consumes capabilities.

This dramatically improves scalability.

💡 Real-World MCP Use Cases

MCP is useful for connecting agents to:

Documentation Systems

AWS Documentation
Azure Documentation
Internal Knowledge Bases

Databases

PostgreSQL
MySQL
MongoDB

Development Tools

GitHub
GitLab
Jira

Cloud Services

AWS
Azure
Google Cloud

Enterprise Systems

CRM
ERP
HR Systems

The possibilities are nearly endless.

🧠 Why Developers Love MCP

Without MCP:

❌ Build every integration yourself

❌ Maintain tool definitions

❌ Handle protocol changes

❌ Create custom wrappers

With MCP:

✅ Discover tools automatically

✅ Reuse existing integrations

✅ Standardized communication

✅ Faster development

✅ Easier maintenance

MCP shifts focus from integration work to solving business problems.

🎯 Key Takeaways

MCP stands for Model Context Protocol
MCP allows agents to connect to external tool providers
STDIO transport is perfect for local development
Agents can automatically discover available tools
MCP significantly reduces integration effort
The AWS Documentation MCP Server provides direct access to official AWS information

📚 Source Code

GitHub Repository:

https://github.com/d3vjamal/strands-agents-labs

🚀 Next Lab

In the next lab, we'll explore remote MCP servers and learn how agents can connect to tools running on different machines and services across the network.

🔗 Continue Learning

⬅️ Previous Lab

Lab 04B: Building a Web Search Tool for AI Agents

➡️ Next Lab

Lab 06: Remote MCP Servers

# 🌐 Lab 04B: Building a Web Search Tool for AI Agents | Strands Agentic AI

Jamal — Sun, 31 May 2026 03:52:57 +0000

Large Language Models are powerful, but they have one major limitation:

They only know what they were trained on.

What if you want your AI agent to access the latest information from the web?

That's where custom tools become incredibly useful.

In this lab, you'll build a custom web search tool using DuckDuckGo Search (DDGS) and connect it to a Strands Agent. This allows the agent to retrieve up-to-date information and provide responses based on real-time search results.

By the end of this lab, you'll have a Recipe Assistant that can search the web for recipes and cooking information.

🚀 What You'll Learn

In this lab, you'll learn:

How to create a custom web search tool
How to integrate third-party Python libraries into Strands tools
How agents use tools to access live information
How to handle API errors gracefully
How to build a specialized AI assistant

🤖 Why Web Search Matters

LLMs have knowledge cutoffs.

For example, an LLM may know:

✅ How recipes work

✅ Common cooking techniques

✅ Popular dishes

But it may not know:

❌ Latest recipes

❌ Current food trends

❌ Newly published cooking content

❌ Real-time information

A web search tool solves this problem.

User Question
      ↓
Agent Analysis
      ↓
Web Search Tool
      ↓
Search Results
      ↓
Agent Response

Instead of relying only on training data, the agent can retrieve fresh information from the web.

🛠️ Prerequisites

Before starting, make sure you have:

Python 3.10+
AWS Account
Amazon Bedrock access
AWS credentials configured
uv installed
DDGS package installed

Install DDGS:

pip install ddgs

📜 The Script

Let's start by looking at the complete example.

from strands import Agent, tool
from ddgs import DDGS
from ddgs.exceptions import RatelimitException
import logging
from strands.models.bedrock import BedrockModel

# Configure logging
logging.getLogger("strands").setLevel(logging.INFO)

# Define a websearch tool
@tool
def websearch(
    keywords: str,
    region: str = "us-en",
    max_results: int | None = None
) -> str:
    """Search the web to get updated information."""

    try:
        results = DDGS().text(
            keywords,
            region=region,
            max_results=max_results
        )

        return results if results else "No results found."

    except RatelimitException:
        return "RatelimitException: Please try again after a short delay."

    except Exception as e:
        return f"Exception: {e}"


# Bedrock
bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

# Create a recipe assistant agent
recipe_agent = Agent(
    model=bedrock_model,
    system_prompt="""
    You are RecipeBot, a helpful cooking assistant.
    Help users find recipes based on ingredients and answer cooking questions.
    Use the websearch tool to find recipes when users mention ingredients or to look up cooking information.
    """,
    tools=[websearch],
)

response = recipe_agent(
    "Suggest a recipe with chicken and capsicum."
)

print(f"Metrics : {response.metrics}")

Now let's break it down step by step.

⚙️ Step 1: Import Dependencies

from strands import Agent, tool
from ddgs import DDGS
from ddgs.exceptions import RatelimitException
import logging
from strands.models.bedrock import BedrockModel

We're importing:

Import	Purpose
Agent	Creates the AI agent
tool	Converts a Python function into a Strands tool
DDGS	Performs DuckDuckGo searches
RatelimitException	Handles search rate limits
logging	Displays runtime information
BedrockModel	Connects to Amazon Bedrock

⚙️ Step 2: Configure Logging

logging.getLogger("strands").setLevel(logging.INFO)

Logging helps us understand what the agent is doing during execution.

Example output:

INFO | strands.agent | Processing user request
INFO | strands.tools | Executing websearch tool

During development, logs provide valuable visibility into agent behavior.

⚙️ Step 3: Create the Web Search Tool

@tool
def websearch(
    keywords: str,
    region: str = "us-en",
    max_results: int | None = None
) -> str:

This function becomes a Strands tool through the @tool decorator.

The agent can now call this function whenever it needs information from the web.

Parameters

Parameter	Description
keywords	Search query
region	Search region
max_results	Maximum number of results

Example:

websearch(
    "chicken capsicum recipe"
)

⚙️ Step 4: Search Using DDGS

results = DDGS().text(
    keywords,
    region=region,
    max_results=max_results
)

DDGS performs a DuckDuckGo search and returns matching results.

These results are then sent back to the agent.

The agent uses them to generate an informed response.

⚙️ Step 5: Handle Errors Gracefully

Production-ready tools should always handle failures.

Rate Limit Handling

except RatelimitException:

If too many requests are made, DDGS may temporarily block searches.

Instead of crashing, the tool returns a helpful message.

General Error Handling

except Exception as e:

Unexpected failures are captured and returned safely.

This improves reliability and user experience.

🧠 Why the Docstring Matters

"""Search the web to get updated information."""

The docstring helps the LLM understand:

What the tool does
When it should use it
What kind of information it can retrieve

Think of the docstring as instructions for the AI.

A clear description leads to better tool selection.

⚙️ Step 6: Configure Amazon Bedrock

bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

This model powers the reasoning and decision-making process.

The agent determines:

Whether web search is needed
What search query to generate
How to interpret results
How to respond to users

⚙️ Step 7: Create a Specialized Recipe Agent

recipe_agent = Agent(
    model=bedrock_model,
    system_prompt="""
    You are RecipeBot...
    """,
    tools=[websearch],
)

This agent has a clear responsibility:

Find recipes
Answer cooking questions
Search the web when necessary

The system prompt defines the agent's personality and capabilities.

⚙️ Step 8: Ask the Agent a Question

response = recipe_agent(
    "Suggest a recipe with chicken and capsicum."
)

The agent receives the request and reasons about how to solve it.

Because recipe information may require fresh data, it can choose to invoke the web search tool.

▶️ Run the Agent

Execute the script:

python agent.py

Or:

uv run labs/04b-websearch-tool/agent.py

📊 Example Interaction

User

Suggest a recipe with chicken and capsicum.

Agent Workflow

User Request
      ↓
Agent Analysis
      ↓
Web Search Tool
      ↓
Recipe Search Results
      ↓
Response Generation

Agent Response

You can make a Chicken Capsicum Stir Fry.

Ingredients:
- Chicken breast
- Capsicum
- Onion
- Garlic
- Soy sauce

Instructions:
1. Sauté garlic and onion.
2. Add chicken and cook thoroughly.
3. Add sliced capsicum.
4. Stir in soy sauce.
5. Serve hot with rice.

Actual responses may vary depending on model and search results.

📈 Understanding Agent Metrics

At the end of the script:

print(f"Metrics : {response.metrics}")

Metrics help monitor agent performance.

You may see information such as:

Input Tokens
Output Tokens
Latency
Tool Calls

These metrics become extremely useful when optimizing production agents.

🔍 How Tool Calling Works

When a user asks a question:

User Prompt
      ↓
Agent Reasoning
      ↓
Tool Selection
      ↓
Web Search
      ↓
Results Returned
      ↓
Final Response

The agent automatically decides whether the tool should be used.

You don't need to manually call the function.

This is what makes agentic systems powerful.

💡 Real-World Use Cases

The same approach can be used for:

News Assistant

Search latest headlines

Research Assistant

Search technical documentation

Travel Assistant

Search destinations and hotels

Shopping Assistant

Search products and reviews

Support Assistant

Search knowledge bases

A web search tool unlocks countless possibilities.

🎯 Key Takeaways

Custom tools allow agents to access live information
DDGS provides a simple web search capability
Error handling improves reliability
Docstrings help the LLM understand tool functionality
Agents automatically decide when to invoke tools
Tool-based architectures make AI assistants far more useful

📚 Source Code

GitHub Repository:

https://github.com/d3vjamal/strands-agents-labs

🚀 Previous Lab

Lab 04A: Creating Your First Custom Tool | Strands Agentic AI

# 🛠️ Lab 04A: Creating Your First Custom Tool | Strands Agentic AI

Jamal — Sun, 31 May 2026 03:48:47 +0000

AI agents become truly powerful when they can perform actions beyond generating text.

While large language models are great at reasoning, tools allow them to interact with the real world, process data, and execute custom logic.

In this lab, you'll learn how to create your first custom tool using the @tool decorator in Strands and expose it to an AI agent.

By the end, your agent will be able to count words using your own Python function.

🚀 What You'll Learn

In this lab, you'll learn:

What tools are in Strands Agents
How the @tool decorator works
How to create your own custom tool
How agents automatically discover and use tools
How tool docstrings help the LLM understand capabilities

🤖 Why Custom Tools Matter

Without tools, an AI agent can only generate responses based on its training and reasoning.

With tools, agents can:

Query databases
Call APIs
Read files
Write files
Perform calculations
Execute business logic

Think of a language model as a brain.

Tools are its hands.

The brain can think about counting words, but a tool can perform the counting accurately and consistently.

🛠️ Prerequisites

Before starting, make sure you have:

Python 3.10+
AWS Account
Amazon Bedrock access
Access to a model such as amazon.nova-2-lite-v1
AWS credentials configured
uv installed
Completed Lab 01 and Lab 02

📜 The Script

Let's start by looking at the complete example.

# Just an example of using creating your custom tool

from strands import Agent, tool
from strands.models.bedrock import BedrockModel

# Bedrock
bedrock_model = BedrockModel(
    # Set your preferred model ID here
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)


@tool
def word_count(text: str) -> int:
    """Count words in text.

    This docstring is used by the LLM to understand the tool's purpose.
    """
    return len(text.split())


agent = Agent(model=bedrock_model, tools=[word_count])

response = agent("How many words are in this sentence?")

Now let's break it down step by step.

⚙️ Step 1: Import Required Modules

from strands import Agent, tool
from strands.models.bedrock import BedrockModel

We're importing:

Import	Purpose
Agent	Creates the AI agent
tool	Converts a Python function into a Strands tool
BedrockModel	Connects the agent to Amazon Bedrock

The tool decorator is the star of this lab.

It allows Strands to expose a Python function to the language model.

⚙️ Step 2: Configure Amazon Bedrock

bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

This creates the model that powers the agent.

Parameters

Parameter	Description
model_id	Bedrock model identifier
region_name	AWS region
temperature	Controls creativity and randomness

For utility tools, lower temperatures often produce more predictable results.

⚙️ Step 3: Create a Custom Tool

@tool
def word_count(text: str) -> int:
    """Count words in text."""
    return len(text.split())

This is where the magic happens.

The @tool decorator transforms a normal Python function into a tool that the agent can invoke.

Function Breakdown

def word_count(text: str) -> int:

Input:

text: str

Output:

int

The function simply splits text into words and returns the total count.

Example:

word_count("hello world")

Returns:

🧠 Why the Docstring Matters

One of the most important parts of a custom tool is the docstring.

"""Count words in text."""

The LLM reads this description to understand:

What the tool does
When it should use it
What inputs it expects

Think of the docstring as instructions for the AI.

A clear docstring helps the model choose the correct tool at the correct time.

⚙️ Step 4: Register the Tool

agent = Agent(
    model=bedrock_model,
    tools=[word_count]
)

Here we provide the tool to the agent.

tools=[word_count]

The agent now knows:

The tool exists
What it does
How to call it

From this point forward, the model can decide when to use it.

⚙️ Step 5: Ask the Agent a Question

response = agent(
    "How many words are in this sentence?"
)

When the agent receives this request, it reasons about the task.

The model recognizes that counting words is exactly what the word_count tool is designed to do.

Instead of guessing, it invokes the tool and uses the result.

▶️ Run the Agent

Execute the script:

uv run labs/04a-custom-tool/agent.py

Or:

python agent.py

📊 Example Interaction

User

How many words are in this sentence?

Agent Reasoning

This task requires counting words.
A tool named word_count is available.
I'll use the tool.

Tool Execution

word_count(
    "How many words are in this sentence?"
)

Result:

Agent Response

There are 7 words in the sentence.

🔍 How Tool Calling Works

When a user sends a request:

User Prompt
     ↓
Agent Analysis
     ↓
Tool Selection
     ↓
Tool Execution
     ↓
Result Returned
     ↓
Final Response

The agent automatically decides whether a tool should be used.

You don't explicitly call the function yourself.

The LLM handles that decision-making process.

💡 Real-World Tool Examples

The same pattern can be used to build more powerful tools:

Calculator Tool

@tool
def add(a: int, b: int) -> int:
    return a + b

Date Tool

@tool
def current_date() -> str:
    ...

Database Tool

@tool
def get_customer(customer_id: str):
    ...

AWS Tool

@tool
def list_s3_buckets():
    ...

This is the foundation of building production-ready AI agents.

🎯 Key Takeaways

Tools extend the capabilities of AI agents
The @tool decorator converts Python functions into agent tools
Docstrings help the LLM understand tool functionality
Agents automatically decide when to use tools
Custom tools are the foundation of real-world agent workflows

📚 Source Code

Lab Source:

https://github.com/d3vjamal/strands-agents-labs/tree/master/labs/04a-custom-tool

🚀 Next Lab

In the next lab, we'll create more advanced tools with parameters and learn how agents can chain multiple tool calls together to solve complex tasks.

# 🔍 Lab 03: Logging and Debugging | Strands Agentic AI

Jamal — Fri, 29 May 2026 19:32:16 +0000

AI agents can perform complex tasks, call tools, and interact with external services. But what happens when something goes wrong?

Without logging, debugging an AI agent can feel like trying to solve a puzzle with half the pieces missing.

In this lab, you'll learn how to enable logging in Strands Agents so you can observe what's happening behind the scenes, understand agent behavior, and troubleshoot issues more effectively.

🚀 What You'll Learn

By the end of this lab, you'll understand:

How logging works in Strands Agents
How to enable DEBUG logs
How to inspect agent execution flow
How to monitor tool invocations
How logging helps troubleshoot agent issues

🤖 Why Logging Matters in Agentic AI

Traditional applications usually follow a predictable flow.

AI agents are different.

A single prompt can trigger multiple reasoning steps, tool calls, and external API requests.

User Prompt
     ↓
Agent Reasoning
     ↓
Tool Selection
     ↓
HTTP Request
     ↓
Response Processing
     ↓
Final Answer

If something fails during this process, logs help us understand:

Which tool was selected
What requests were sent
What responses were received
Where failures occurred
How the agent reached its final answer

Think of logging as the flight recorder for your AI agent.

🛠️ Prerequisites

Before starting, make sure you have:

Python 3.10+
AWS Account
Amazon Bedrock access
Access to a model such as amazon.nova-2-lite-v1
AWS credentials configured
uv installed

📜 The Script

Let's start by looking at the complete example.

# This lab is to teach you about logging

from strands import Agent
from strands.models.bedrock import BedrockModel
from strands_tools import file_read, file_write, http_request
import logging

# Configure the root strands logger
logging.getLogger("strands").setLevel(logging.DEBUG)

# Add a handler to display logs in the terminal
logging.basicConfig(
    format="%(levelname)s | %(name)s | %(message)s",
    handlers=[logging.StreamHandler()]
)

# Configure the Bedrock model
bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

system_prompt = """
Weather Information
    - You can also make HTTP requests to the National Weather Service API.
    - Process and display weather forecast data for locations in the United States.
"""

# Create the agent with tools
local_agent = Agent(
    system_prompt=system_prompt,
    model=bedrock_model,
    tools=[http_request],
)

# Ask the agent a question
local_agent("what is the weather in new york?")

Now let's break it down.

⚙️ Step 1: Configure Logging

import logging

logging.getLogger("strands").setLevel(logging.DEBUG)

logging.basicConfig(
    format="%(levelname)s | %(name)s | %(message)s",
    handlers=[logging.StreamHandler()]
)

What is happening here?

First, we configure Python's built-in logging module.

logging.getLogger("strands").setLevel(logging.DEBUG)

This tells Strands to emit detailed debugging information.

The DEBUG level provides maximum visibility into agent execution.

We then configure how logs appear in the terminal:

logging.basicConfig(
    format="%(levelname)s | %(name)s | %(message)s"
)

Example:

DEBUG | strands.agent | Processing user request
INFO | strands.tools | Executing HTTP request

This makes logs easy to read and troubleshoot.

⚙️ Step 2: Configure the Bedrock Model

bedrock_model = BedrockModel(
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

Here we create the LLM that powers our agent.

Parameters

Parameter	Description
model_id	Bedrock model identifier
region_name	AWS Region
temperature	Controls response randomness

A lower temperature produces more consistent and predictable responses.

⚙️ Step 3: Define the Agent's Role

system_prompt = """
Weather Information
    - You can also make HTTP requests to the National Weather Service API.
    - Process and display weather forecast data for locations in the United States.
"""

The system prompt acts as the agent's instructions.

It tells the model:

What task it should perform
Which information sources are available
How it should behave

In this case, the agent is focused on retrieving weather information.

⚙️ Step 4: Add the HTTP Tool

tools=[http_request]

The http_request tool gives the agent the ability to access external APIs.

Without tools, the agent can only rely on its training data.

With tools, it can fetch live information from the internet.

For weather data, the agent can query APIs and process real-time forecasts.

⚙️ Step 5: Create the Agent

local_agent = Agent(
    system_prompt=system_prompt,
    model=bedrock_model,
    tools=[http_request],
)

This combines:

The model
The instructions
The available tools

into a working AI agent.

▶️ Run the Agent

Invoke the agent using:

local_agent("what is the weather in new york?")

The agent will:

Analyze the request
Decide whether a tool is needed
Call the HTTP tool
Retrieve weather information
Generate a final response

📊 Example Debug Output

When running the script, you'll see logs similar to:

DEBUG | strands.agent | Processing user request
DEBUG | strands.agent | Selecting tool
INFO  | strands.tools | Executing HTTP request
INFO  | strands.tools | Response received
DEBUG | strands.agent | Generating final answer

The exact output may vary depending on the model and SDK version.

🔍 Understanding the Log Levels

DEBUG

Most detailed level.

Useful during development.

DEBUG | Agent selecting tool

INFO

General execution information.

INFO | HTTP request executed

WARNING

Something unexpected happened, but execution continues.

WARNING | Missing optional parameter

ERROR

Execution failed.

ERROR | Failed to call external API

💡 Why Developers Love Logs

Imagine your agent gives an incorrect answer.

Without logs:

❌ No idea what happened.

With logs:

✅ See which tool was selected

✅ Inspect API requests

✅ Inspect responses

✅ Find failures quickly

✅ Improve prompts and tools

Logs dramatically reduce debugging time.

🎯 Key Takeaways

Logging provides visibility into agent execution
DEBUG logs help trace reasoning and tool usage
Python's built-in logging module works seamlessly with Strands
Logs make troubleshooting faster and easier
Observability is essential for production-ready AI agents

📚 Source Code

GitHub Repository:

https://github.com/d3vjamal/strands-agents-labs

🚀 Next Lab

In the next lab, we'll explore custom tools and learn how to extend Strands Agents with capabilities tailored to your own applications.

Lab 02 — HTTP Tools Integration; Strands Agentic AI

Jamal — Fri, 29 May 2026 19:21:09 +0000

Building My First AI Agent with Strands Agents: Part 1 link

🎯 Objective

Give your agent the ability to fetch live data from the internet using the http_request tool. In this lab the agent calls the US National Weather Service API to answer a weather question.

📖 Background

Most useful agents need to reach out to external services. The http_request tool lets an agent make GET/POST/PUT/DELETE requests to any URL. The agent decides which URL to call, parses the response, and presents it in natural language.

🔑 Key Concepts

Concept	Description
`http_request`	Built-in Strands tool for making HTTP calls
System Prompt	Guides the agent on which APIs to use and how to interpret responses
API chaining	The agent may make multiple HTTP calls (e.g. get coordinates → get forecast)

⚙️ Prerequisites

AWS credentials configured
Internet connectivity (the agent calls api.weather.gov)
Dependencies installed (uv sync)

Lab 02 : Agentic ai with http_request tool

# This lab is to teach you about http_request tool

from strands import Agent
from strands.models.bedrock import BedrockModel
from strands_tools import file_read, file_write, http_request

# Configure the Bedrock model
bedrock_model = BedrockModel(
    # Set your preferred model ID here (e.g., "global.amazon.nova-2-lite-v1:0")
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)


system_prompt = """
Weather Information
    - You can also make HTTP requests to the National Weather Service API.
    - Process and display weather forecast data for locations in the United States.
"""

# - When retrieving weather information, first get coordinates using https://api.weather.gov/points/{latitude},{longitude},  or
#         https://api.weather.gov/points/{zipcode}, then use the returned forecast URL. You can make additional http requests as well.

# Create the agent with tools
local_agent = Agent(
    system_prompt=system_prompt, # Define a system Prompt
    model=bedrock_model,
    tools=[http_request],  # Add your custom tools here
)


local_agent("what is the weather in new york?")

▶️ How to Run

uv run labs/02-http-tools/agent.py

🧪 Exercises

Try a different city — Change "new york" to another US city and see if the agent resolves the correct API endpoint.
Combine tools — Add file_write so the agent saves the weather report to a file.
Non-US weather — The NWS API only covers the US. Modify the system prompt to use a global weather API like OpenWeatherMap instead.
Error handling — Disconnect from the internet and observe how the agent reacts.

ALL LAB EXCERSIZE GitHub Notes

📚 Further Reading

Building My First AI Agent with Strands Agents

Jamal — Fri, 29 May 2026 19:06:35 +0000

An agent is a program that uses a large-language model (LLM) to decide which actions to take based on a user's request. Strands Agents wraps this loop into a simple Python API.

If you've been trying to build Agentic AI applications recently, you've probably noticed a major problem: boilerplate overload. Frameworks like LangChain or LangGraph are incredibly powerful, but sometimes you just want a clean, fast, lightweight, and model-agnostic way to build production-ready agents.

Enter Strands Agents—a lean, modern open-source SDK designed to let developers build robust AI agents without the architectural bloat.

In this 4-part series, we are going to explore how to take Strands from a blank screen to a production-grade multi-agent system. Let's get our hands dirty with Part 1!

🚀 Quick Start

1. 🛠️ Prerequisites

Before we write code, let's set up a clean playground.

Make sure you have:

Python 3.10+
AWS account with access credentials (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) and access granted to the amazon.nova-2-lite-v1 (or another Bedrock model) on Amazon Bedrock
uv package manager

2. 🤖 What Is Agentic AI?

Agentic AI refers to autonomous software systems powered by artificial intelligence that can perceive their environment, make decisions, and take actions independently to achieve specific goals.

3. 📦 Installation

Step 1: Clone the Repository

git clone https://github.com/d3vjamal/strands-agents-labs.git
cd strands-agents-labs

*Lab 1: Run your first agent
*

from strands import Agent
from strands_tools import file_read, file_write
from dotenv import load_dotenv
from strands.models.bedrock import BedrockModel
import os

load_dotenv()


bedrock_model = BedrockModel(
    # Set your preferred model ID here (e.g., "global.amazon.nova-2-lite-v1:0")
    model_id="<YOUR_MODEL_ID>",
    region_name="eu-west-2",
    temperature=0.3,
)

system_prompt = "You are a an agent which can read and write files to current directory"

# Create the agent with tools
local_agent = Agent(
    system_prompt=system_prompt, # Define a system Prompt
    model=bedrock_model,
    tools=[file_read, file_write],  # Add your custom tools here
)


local_agent("can you create a weather.md file, with the content about current temperature in kolkata India right now?, if not able find weather put reason of it")

Run your first lab :

uv run labs/01-your-first-agent/agent.py

📖 Background

In this lab the agent is asked to create a markdown file with weather information. Because the agent does not have internet access, it must reason about what it can do (write a file) and what it cannot do (fetch live data) — a great first lesson in tool-aware reasoning.

🔑 Key Concepts

Concept	Description
`Agent`	The core class that ties together a model, tools, and a system prompt
`system_prompt`	Instructions that shape the agent's personality and capabilities
`BedrockModel`	Model provider connecting to Amazon Bedrock
`file_read` / `file_write`	Built-in Strands tools for local file operations
`load_dotenv()`	Loads AWS credentials from a `.env` file

Part 2 : HTTP tool integration

DEV Community: Jamal

I Built an npm Package That Scaffolds AWS AppSync, Lambda & GraphQL Services — Files, Infra, and All

create-lambda-graphql-app: A CLI That Scaffolds Fully Wired AWS AppSync + Lambda Services

The Root Problem with Manual Scaffolding

What's Included Out of the Box

1. The CLI tool

2. Standard project structure

Standardized Handler Architecture

Pre-Wired AWS SAM Infrastructure

S3 schema & VTL deployment workflow

Daily Developer Workflow

Getting Started

Roadmap & Next Steps

Appendix: Generated Project README.md

create-lambda-graphql-app

Overview

Quick start

Directory structure

CLI usage

Handler conventions & architecture

Available scripts

Requirements

Contributing

License

# Building a Personal Notes Assistant with RAG, Amazon Bedrock, and Pinecone

What is RAG?

A Real-Life Analogy

Understanding Embeddings

System Architecture

How Notes Get Ingested

How Questions Get Answered

Code Walkthrough

1. Step 1: Validating Incoming Uploads

2. Step 2: Saving Raw Files to S3

3. Step 3: Chunking Text for Precision

4. Step 4: Vector Embedding & Indexing

5. Step 5 & 6: Retrieval & Answer Generation

Serverless Deployment Highlights

Key Takeaways & Lessons Learned

LangChain vs Strands SDK with Amazon Bedrock

1. The short explanation

2. Technology-layer mapping

3. Weather-agent mapping

4. How the weather agent works

5. Core vocabulary

Model

Prompt

System prompt

Tool

Tool calling

Agent

State

Memory

Checkpoint

Node and edge

Human in the loop

Structured output

Retrieval-augmented generation (RAG)

6. Similarities

7. Important differences

8. When to introduce LangGraph

9. Bedrock and AgentCore are different layers

10. Suggested presentation order

11. Learning path

12. Commands for the examples

# 🤖 Lab 07: Building Multi-Agent Systems with an Orchestrator | Strands Agentic AI

📚 Strands Agentic AI Lab Series

🚀 What You'll Learn

🤖 Why Multi-Agent Systems?

🛠️ Prerequisites

🏗️ Architecture Overview

📜 The Complete Script

⚙️ Step 1: Configure Logging

⚙️ Step 2: Configure the Bedrock Model

⚙️ Step 3: Create a Reusable Agent Factory

⚙️ Step 4: Create Specialized Agents

Study Agent

Expense Agent

⚙️ Step 5: Expose Agents as Tools

Study Tool

Appendix: Generated Project `README.md`