swap chapters

Author: geemi725

_toc.yml

@@ -17,8 +17,8 @@ parts:
   - caption: "3. LLM Agents"
     chapters:
       - file: chapter_3/agents
-      - file: chapter_3/agent_implementation
       - file: chapter_3/aviary_agent_implementation
+      - file: chapter_3/agent_implementation
       - file: chapter_3/agent_mcp_example
 
   - caption: "4. Resources"

chapter_3/agent_implementation.ipynb

@@ -5,17 +5,21 @@
    "id": "267ac72b",
    "metadata": {},
    "source": [
-    "# 3.2 Deploy agents with Anthropic's native tool use\n",
+    "# 3.3 Deploy agents with Anthropic's native tool use\n",
     "\n",
-    "Now let's see how we can enhance the capabilities of LLMs with added tools.  \n",
+    "In chapter 3.2 we learned how to implement an agent from scratch using python libraries. In this chapter we'll learn how implement an agent using Anthropic's native tool use. \n",
     "\n",
-    "## 3.2.1 Problem setup\n",
+    "Compared to chapter 3.2, the imports here are minimal — since we're using Anthropic's native tool \n",
+    "use, we don't need `ldp` or any agent framework. The only library we need is the `anthropic` Python \n",
+    "package, which provides a straightforward client for interacting with Claude. But cost and flexibility are downsides here. \n",
     "\n",
-    "The goal of this section is to build an AI agent that can analyze protein data and generate hypotheses for drug discovery.\n",
+    "We'll use the same problem setup and tools as in chapter 3.2. The agent is built to analyze protein data and generate hypothesis for drug discovery. \n",
     "\n",
-    "When you understand the basic workflow, you will be able to design and build your own agents.\n",
+    "Tools:\n",
+    "- `analyze_protein_sequence` — computes basic biophysical properties\n",
+    "- `summarize_protein_role` — asks the AI to summarize biological context\n",
     "\n",
-    "Let's start with installing dependencies and loading API keys below. We will be using the Anthropic native tool use in this example, so make sure you have an Anthropic API key."
+    "Let's start with installing dependencies and loading API keys below. As we're using the Anthropic native tool use in this example, make sure you have an Anthropic API key."
    ]
   },
   {
@@ -62,7 +66,11 @@
    "id": "08721371",
    "metadata": {},
    "source": [
-    "## 3.2.2 Import libraries and set up the LLM client\n"
+    "## 3.3.1 Import libraries and set up the LLM client\n",
+    "\n",
+    "We instantiate the client using our API key, which will be used for all subsequent calls to the \n",
+    "model. Think of the client as a messenger between your Python code and Anthropic's servers. When you want Claude to do something, you don't communicate with it directly over the internet yourself. Instead, you hand your request to the client object, which handles the networking, authentication, and formatting behind the scenes, and brings the response back to you. All \n",
+    "subsequent interactions with Claude in this chapter will go through this client."
    ]
   },
   {
@@ -76,8 +84,7 @@
     "from Bio.SeqUtils.ProtParam import ProteinAnalysis \n",
     "\n",
     "# Connect to the Claude AI model.\n",
-    "# Make sure you have set your API key as an environment variable:\n",
-    "# export ANTHROPIC_API_KEY=\"sk-ant-...\"\n",
+    "# Make sure you have set your API key as an environment variable\n",
     "client = anthropic.Anthropic(api_key=get_api_key())\n",
     "\n",
     "print(\"Libraries loaded and client ready.\")"
@@ -88,13 +95,17 @@
    "id": "73f7e483",
    "metadata": {},
    "source": [
-    "## 3.2.3 Define the tools\n",
-    "As we discussed previously, tools are Python functions our agent can choose to call. \n",
+    "## 3.3.2 Define the tools\n",
+    "As we discussed previously, tools are Python functions our agent can choose to call. Before deploying the agent, we need to tell Claude what tools it has access to and how to use them. \n",
     "\n",
-    "We give each tool a name, a description (so the AI understands what it does), and a list of inputs it expects.\n",
-    "In this example we'll build **two tools**:\n",
-    "- `analyze_protein_sequence` — computes basic biophysical properties\n",
-    "- `summarize_protein_role`   — asks the AI to summarize biological context\n"
+    "With Anthropic's native tool use, tools are defined as JSON schemas and passed directly to the API and \n",
+    "no external libraries are required. Each tool definition includes a `name`, a `description` that helps \n",
+    "Claude decide when to use it, and an `input_schema` that specifies what parameters the tool expects. \n",
+    "\n",
+    "Below we define our two tools:\n",
+    "- `analyze_protein_sequence`: takes an amino acid sequence and  returns biophysical properties like molecular weight and isoelectric point.\n",
+    " \n",
+    "- `summarize_protein_role`: takes a protein name and returns a plain-language summary of its biological function."
    ]
   },
   {
@@ -105,7 +116,6 @@
    "outputs": [],
    "source": [
     "# ── TOOL 1: Analyze a protein sequence ──────────────────────────────────────\n",
-    "\n",
     "def analyze_protein_sequence(sequence: str) -> dict:\n",
     "    \"\"\"\n",
     "    Takes a protein sequence (one-letter amino acid codes, e.g. 'MKTIIALSYIFCLVFA...')\n",
@@ -162,7 +172,7 @@
    "id": "9c082794",
    "metadata": {},
    "source": [
-    "Now let's package these as **tool definitions**. This is a structured description the AI model can read to understand what tools are available."
+    "After writing the python functions for the two tools, we have to format the tool definition using JSON schemas and pass directly to the API. "
    ]
   },
   {
@@ -222,23 +232,27 @@
    "id": "cbeb2794",
    "metadata": {},
    "source": [
-    "## 3.2.4 Build the agent loop\n",
+    "## 3.3.3 Build the agent loop\n",
     "\n",
-    "Here is the heart of the agent. The logic is simple:\n",
+    "At the heart of the agent is a back-and-forth conversation between your code and Claude. This loop continues until Claude has enough information to answer the question. \n",
     "\n",
+    "Unlike a standard API call where you send a prompt and get a response, tool use is inherently iterative: Claude may need to call `analyze_protein_sequence`, inspect the result, and then decide to also call `summarize_protein_role` before it can draw a conclusion. Each tool result gets added back into the conversation so Claude always has full context of what it has already looked up. The logic follows a straightforward cycle as shown below.\n",
+    "\n",
+    "```{figure} ../figures/agent_loop.png\n",
+    ":alt: agent_loop\n",
+    ":align: center\n",
+    ":figclass: caption-centered\n",
+    "\n",
+    "Figure 3.3.1: In an agent loop the LLM decides if it requires a tool, our code executes the tool, receives the result from the execution. This cycle will continue until the LLM decides to terminate the cycle. \n",
     "```\n",
-    "User sends a question\n",
-    "    ↓\n",
-    "Claude decides if it needs a tool\n",
-    "    ↓ (if yes)\n",
-    "We run that tool and send the result back to Claude\n",
-    "    ↓\n",
-    "Claude decides if it needs another tool (or is done)\n",
-    "    ↓ (when done)\n",
-    "Claude writes its final answer\n",
-    "```\n",
     "\n",
-    "This loop continues until Claude stops calling tools."
+    "\n",
+    ":::{admonition}\n",
+    ":class: note\n",
+    "\n",
+    "The LLM doesn't run the tools itself. It simply tells you *which* tool it wants to call and *what arguments* to pass. Your code is responsible for actually executing the \n",
+    "tool and returning the result.\n",
+    ":::\n"
    ]
   },
   {
@@ -348,9 +362,9 @@
    "id": "b23b22f3",
    "metadata": {},
    "source": [
-    "## 3.2.5 Complete agent workflow\n",
+    "## 3.3.4 Test the agent\n",
     "\n",
-    "Let's try it on a classic drug target: **EGFR** (Epidermal Growth Factor Receptor), a key protein in many cancers.\n",
+    "Now tet's try our agent on a classic drug target: **EGFR** (Epidermal Growth Factor Receptor), a key protein in many cancers.\n",
     "\n",
     "We'll provide a short fragment of its sequence so the notebook runs quickly. In a real workflow, you'd paste the full sequence from UniProt.\n",
     "\n",
@@ -388,7 +402,7 @@
    "id": "e2e87036",
    "metadata": {},
    "source": [
-    "## 3.2.6 Recap of agent set up\n",
+    "## 3.3.5 Recap of agent set up\n",
     "\n",
     "| Step | Agent Actions |\n",
     "|------|--------------------|\n",
@@ -397,9 +411,7 @@
     "| 3️  | Decided to call `summarize_protein_role` → got biological context |\n",
     "| 4️  | Combined both results → generated drug hypotheses |\n",
     "\n",
-    "You can test this agent with a protein of your choice by re-running the agent with a new protein sequence. You can also add more tools such as literature searching or plotting tools to analyze your data.\n",
-    "\n",
-    "Note that you can use the RAG pipeline we learned in section 2.2 as a tool here to extract literature data."
+    "Test this agent with a protein of your choice by re-running the agent with a new protein sequence. You can also add more tools such as literature searching or plotting tools to analyze your data. For example that you can use the RAG pipeline we learned in section 2.2 as a tool here to extract literature data."
    ]
   }
  ],