amazon-bedrock-agentcore-samples/01-tutorials/07-AgentCore-E2E/lab-01-create-an-agent.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lab 1: Creating a simple customer support agent prototype\n",
    "\n",
    "### Overview\n",
    "\n",
    "[Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) helps you deploying and operating AI agents securely at scale - using any framework and model. It provides you with the capability to move from prototype to production faster. \n",
    "\n",
    "In this 5-labs tutorial, we will demonstrate the end-to-end journey from prototype to production using a **Customer Support Agent**. For this example we will use [Strands Agents](https://strandsagents.com/latest/), a simple-to-use, code-first framework for building agents and the Anthropic Claude Sonnet 3.7 model from Amazon Bedrock. For your application you can use the framework and model of your choice. It's important to note that the concepts covered here can be applied using other frameworks and models as well.\n",
    "\n",
    "**Workshop Journey:**\n",
    "- **Lab 1 (Current)**: Create Agent Prototype - Build a functional customer support agent\n",
    "- **Lab 2**: Enhance with Memory - Add conversation context and personalization\n",
    "- **Lab 3**: Scale with Gateway & Identity - Share tools across agents securely\n",
    "- **Lab 4**: Deploy to Production - Use AgentCore Runtime with observability\n",
    "- **Lab 5**: Build User Interface - Create a customer-facing application\n",
    "\n",
    "In this first lab, we'll build a Customer Support Agent prototype that will evolve throughout the workshop into a production-ready system serving multiple customers with persistent memory, shared tools, and full observability. Our agent will have the following local tools available:\n",
    "- **get_return_policy()** - Get return policy for specific products\n",
    "- **get_product_info()** - Get product information\n",
    "- **web_search()** - Search the web for troubleshooting help\n",
    "\n",
    "\n",
    "### Architecture for Lab 1\n",
    "<div style=\"text-align:left\">\n",
    "    <img src=\"images/architecture_lab1_strands.png\" width=\"75%\"/>\n",
    "</div>\n",
    "\n",
    "*Simple prototype running locally. In subsequent labs, we'll migrate this to AgentCore services with shared tools, persistent memory, and production-grade observability.*\n",
    "\n",
    "### Prerequisites\n",
    "\n",
    "* **AWS Account** with appropriate permissions\n",
    "* **Python 3.10+** installed locally\n",
    "* **AWS CLI configured** with credentials\n",
    "* **Anthropic Claude 3.7** enabled on [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)\n",
    "* **Strands Agents** and other libraries installed in the next cells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 1: Install Dependencies and Import Libraries\n",
    "Before we start, let's install the pre-requisites for this lab"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install required packages\n",
    "%pip install -U -r requirements.txt -q"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now import the required libraries and initialize our boto3 session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import libraries\n",
    "import boto3\n",
    "from boto3.session import Session\n",
    "\n",
    "from ddgs.exceptions import DDGSException, RatelimitException\n",
    "from ddgs import DDGS\n",
    "\n",
    "from strands.tools import tool\n",
    "from scripts.utils import put_ssm_parameter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get boto session\n",
    "boto_session = Session()\n",
    "region = boto_session.region_name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2: Implementing custom tools\n",
    "\n",
    "Next, we will implement the 3 tools which will be provided to the Customer Support Agent.\n",
    "\n",
    "Defining tools in Strands Agent is extremely simple, just add a `@tool` decorator to your function, and provide a description of the tool in the function's docstring. Strands Agents will use the function documentation, typing and arguments to provide context on this tool to your agent. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Tool 1: Get Return Policy\n",
    "\n",
    "**Purpose:** This tool helps customers understand return policies for different product categories. It provides detailed information about return windows, conditions, processes, and refund timelines so customers know exactly what to expect when returning items."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@tool\n",
    "def get_return_policy(product_category: str) -> str:\n",
    "    \"\"\"\n",
    "    Get return policy information for a specific product category.\n",
    "\n",
    "    Args:\n",
    "        product_category: Electronics category (e.g., 'smartphones', 'laptops', 'accessories')\n",
    "\n",
    "    Returns:\n",
    "        Formatted return policy details including timeframes and conditions\n",
    "    \"\"\"\n",
    "    # Mock return policy database - in real implementation, this would query policy database\n",
    "    return_policies = {\n",
    "        \"smartphones\": {\n",
    "            \"window\": \"30 days\",\n",
    "            \"condition\": \"Original packaging, no physical damage, factory reset required\",\n",
    "            \"process\": \"Online RMA portal or technical support\",\n",
    "            \"refund_time\": \"5-7 business days after inspection\",\n",
    "            \"shipping\": \"Free return shipping, prepaid label provided\",\n",
    "            \"warranty\": \"1-year manufacturer warranty included\"\n",
    "        },\n",
    "         \"laptops\": {\n",
    "            \"window\": \"30 days\", \n",
    "            \"condition\": \"Original packaging, all accessories, no software modifications\",\n",
    "            \"process\": \"Technical support verification required before return\",\n",
    "            \"refund_time\": \"7-10 business days after inspection\",\n",
    "            \"shipping\": \"Free return shipping with original packaging\",\n",
    "            \"warranty\": \"1-year manufacturer warranty, extended options available\"\n",
    "        },\n",
    "        \"accessories\": {\n",
    "            \"window\": \"30 days\",\n",
    "            \"condition\": \"Unopened packaging preferred, all components included\",\n",
    "            \"process\": \"Online return portal\",\n",
    "            \"refund_time\": \"3-5 business days after receipt\",\n",
    "            \"shipping\": \"Customer pays return shipping under $50\",\n",
    "            \"warranty\": \"90-day manufacturer warranty\"\n",
    "        }\n",
    "    }\n",
    "\n",
    "    # Default policy for unlisted categories\n",
    "    default_policy = {\n",
    "        \"window\": \"30 days\",\n",
    "        \"condition\": \"Original condition with all included components\",\n",
    "        \"process\": \"Contact technical support\",\n",
    "        \"refund_time\": \"5-7 business days after inspection\", \n",
    "        \"shipping\": \"Return shipping policies vary\",\n",
    "        \"warranty\": \"Standard manufacturer warranty applies\"\n",
    "    }\n",
    "\n",
    "    policy = return_policies.get(product_category.lower(), default_policy)\n",
    "    return f\"Return Policy - {product_category.title()}:\\n\\n\" \\\n",
    "           f\"• Return window: {policy['window']} from delivery\\n\" \\\n",
    "           f\"• Condition: {policy['condition']}\\n\" \\\n",
    "           f\"• Process: {policy['process']}\\n\" \\\n",
    "           f\"• Refund timeline: {policy['refund_time']}\\n\" \\\n",
    "           f\"• Shipping: {policy['shipping']}\\n\" \\\n",
    "           f\"• Warranty: {policy['warranty']}\"\n",
    "print(\"✅ Return policy tool ready\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Tool 2: Get Product Information\n",
    "\n",
    "**Purpose:** This tool provides customers with comprehensive product details including warranties, available models, key features, shipping policies, and return information. It helps customers make informed purchasing decisions and understand what they're buying."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@tool\n",
    "def get_product_info(product_type: str) -> str:\n",
    "    \"\"\"\n",
    "    Get detailed technical specifications and information for electronics products.\n",
    "\n",
    "    Args:\n",
    "        product_type: Electronics product type (e.g., 'laptops', 'smartphones', 'headphones', 'monitors')\n",
    "    Returns:\n",
    "        Formatted product information including warranty, features, and policies\n",
    "    \"\"\"\n",
    "    # Mock product catalog - in real implementation, this would query a product database\n",
    "    products = {\n",
    "        \"laptops\": {\n",
    "            \"warranty\": \"1-year manufacturer warranty + optional extended coverage\",\n",
    "            \"specs\": \"Intel/AMD processors, 8-32GB RAM, SSD storage, various display sizes\",\n",
    "            \"features\": \"Backlit keyboards, USB-C/Thunderbolt, Wi-Fi 6, Bluetooth 5.0\",\n",
    "            \"compatibility\": \"Windows 11, macOS, Linux support varies by model\",\n",
    "            \"support\": \"Technical support and driver updates included\"\n",
    "        },\n",
    "        \"smartphones\": {\n",
    "            \"warranty\": \"1-year manufacturer warranty\",\n",
    "            \"specs\": \"5G/4G connectivity, 128GB-1TB storage, multiple camera systems\",\n",
    "            \"features\": \"Wireless charging, water resistance, biometric security\",\n",
    "            \"compatibility\": \"iOS/Android, carrier unlocked options available\",\n",
    "            \"support\": \"Software updates and technical support included\"\n",
    "        },\n",
    "        \"headphones\": {\n",
    "            \"warranty\": \"1-year manufacturer warranty\",\n",
    "            \"specs\": \"Wired/wireless options, noise cancellation, 20Hz-20kHz frequency\",\n",
    "            \"features\": \"Active noise cancellation, touch controls, voice assistant\",\n",
    "            \"compatibility\": \"Bluetooth 5.0+, 3.5mm jack, USB-C charging\",\n",
    "            \"support\": \"Firmware updates via companion app\"\n",
    "        },\n",
    "        \"monitors\": {\n",
    "            \"warranty\": \"3-year manufacturer warranty\",\n",
    "            \"specs\": \"4K/1440p/1080p resolutions, IPS/OLED panels, various sizes\",\n",
    "            \"features\": \"HDR support, high refresh rates, adjustable stands\",\n",
    "            \"compatibility\": \"HDMI, DisplayPort, USB-C inputs\",\n",
    "            \"support\": \"Color calibration and technical support\"\n",
    "        }\n",
    "    }\n",
    "    product = products.get(product_type.lower())\n",
    "    if not product:\n",
    "        return f\"Technical specifications for {product_type} not available. Please contact our technical support team for detailed product information and compatibility requirements.\"\n",
    "\n",
    "    return f\"Technical Information - {product_type.title()}:\\n\\n\" \\\n",
    "           f\"• Warranty: {product['warranty']}\\n\" \\\n",
    "           f\"• Specifications: {product['specs']}\\n\" \\\n",
    "           f\"• Key Features: {product['features']}\\n\" \\\n",
    "           f\"• Compatibility: {product['compatibility']}\\n\" \\\n",
    "           f\"• Support: {product['support']}\"\n",
    "\n",
    "print(\"✅ get_product_info tool ready\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Tool 3: Web-search\n",
    "\n",
    "**Purpose:** This tool allows customers to get troubleshooting support or suggestions on product recommendations etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@tool\n",
    "def web_search(keywords: str, region: str = \"us-en\", max_results: int = 5) -> str:\n",
    "    \"\"\"Search the web for updated information.\n",
    "    \n",
    "    Args:\n",
    "        keywords (str): The search query keywords.\n",
    "        region (str): The search region: wt-wt, us-en, uk-en, ru-ru, etc..\n",
    "        max_results (int | None): The maximum number of results to return.\n",
    "    Returns:\n",
    "        List of dictionaries with search results.\n",
    "    \n",
    "    \"\"\"\n",
    "    try:\n",
    "        results = DDGS().text(keywords, region=region, max_results=max_results)\n",
    "        return results if results else \"No results found.\"\n",
    "    except RatelimitException:\n",
    "        return \"Rate limit reached. Please try again later.\"\n",
    "    except DDGSException as e:\n",
    "        return f\"Search error: {e}\"\n",
    "    except Exception as e:\n",
    "        return f\"Search error: {str(e)}\"\n",
    "\n",
    "print(\"✅ Web search tool ready\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4: Create and Configure the Customer Support Agent\n",
    "\n",
    "Next, we will create the Customer Support Agent providing a model, the list of tools implemented in the previous step, and with a system prompt."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from strands import Agent\n",
    "from strands.models import BedrockModel\n",
    "\n",
    "SYSTEM_PROMPT = \"\"\"You are a helpful and professional customer support assistant for an electronics e-commerce company.\n",
    "Your role is to:\n",
    "- Provide accurate information using the tools available to you\n",
    "- Support the customer with technical information and product specifications.\n",
    "- Be friendly, patient, and understanding with customers\n",
    "- Always offer additional help after answering questions\n",
    "- If you can't help with something, direct customers to the appropriate contact\n",
    "\n",
    "You have access to the following tools:\n",
    "1. get_return_policy() - For warranty and return policy questions\n",
    "2. get_product_info() - To get information about a specific product\n",
    "3. web_search() - To access current technical documentation, or for updated information. \n",
    "Always use the appropriate tool to get accurate, up-to-date information rather than making assumptions about electronic products or specifications.\"\"\"\n",
    "\n",
    "# Initialize the Bedrock model (Anthropic Claude 3.7 Sonnet)\n",
    "model = BedrockModel(\n",
    "    model_id=\"us.anthropic.claude-3-7-sonnet-20250219-v1:0\",\n",
    "    temperature=0.3,\n",
    "    region_name=region\n",
    ")\n",
    "\n",
    "# Create the customer support agent with all tools\n",
    "agent = Agent(\n",
    "    model=model,\n",
    "    tools=[\n",
    "        get_product_info,  # Tool 1: Simple product information lookup\n",
    "        get_return_policy,  # Tool 2: Simple return policy lookup\n",
    "        web_search # Tool 3: Access the web for updated information\n",
    "    ],\n",
    "    system_prompt=SYSTEM_PROMPT,\n",
    ")\n",
    "\n",
    "print(\"Customer Support Agent created successfully!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 5: Test the Customer Support Agent\n",
    "\n",
    "Let's test our agent with sample queries to ensure all tools work correctly.\n",
    "\n",
    "#### Test Return check"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "response = agent(\"What's the return policy for my thinkpad X1 Carbon?\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Test Troubleshooting"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "response = agent(\"I bought an iphone 14 last month. I don't like it because it heats up. How do I solve it?\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 🎉 Lab 1 Complete!\n",
    "\n",
    "You've successfully created a functional Customer Support Agent prototype! Here's what you accomplished:\n",
    "\n",
    "- Built an agent with 3 custom tools (return policy, product info, web search)  \n",
    "- Tested multi-tool interactions and web search capabilities  \n",
    "- Established the foundation for our production journey  \n",
    "\n",
    "### Current Limitations (We'll fix these!)\n",
    "- **Single user conversation memory** - local conversation session, multiple customers need multiple sessions.\n",
    "- **Conversation history limited to session** - no long term memory or cross session information is available in the conversation.\n",
    "- **Tools reusability** - tools aren't reusable across different agents  \n",
    "- **Running locally only** - not scalable\n",
    "- **Identity** - No user and/or agent identity or access control\n",
    "- **Observability** - Limited observability into agent behavior\n",
    "- **Existing APIs** - No access to existing enterprise APIs for customer data\n",
    "\n",
    "##### Next Up [Lab 2: Personalize our agent by adding memory →](lab-02-agentcore-memory.ipynb)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}