L1: Modular Architecture & The Agent SDK

In the previous lesson, we covered how to make a single, stateless request to the Claude API. While powerful, a single request is just a conversational turn. To build automated workflows, Claude needs the ability to take actions, retrieve dynamic data, and iterate until a task is complete. This is where we transition from a "chatbot" to an Agent.

1. What Defines an "Agent"?

In the context of LLM architecture, an agent is not a different AI model; it is an architectural pattern wrapped around the model.

A standard script executes step-by-step instructions. An Agent is given a high-level goal, access to tools, and the autonomy to determine the steps required to achieve it. It loops through a cycle of reasoning, acting, and observing until it determines the task is finished.

2. The Core Architecture: The Agentic Loop

To understand how an SDK powers an agent, you must first understand the fundamental loop it runs. This is often referred to as the Reason + Act (ReAct) Loop :

Input: The user provides a prompt (e.g., "What is the weather in Tokyo, and should I pack an umbrella?").
Reason & Request: Claude realizes it doesn't know real-time weather. Instead of answering directly, it responds with a specific stop_reason of tool_use and asks to trigger a function (e.g., get_weather(location="Tokyo")).
Execute (The "Act"): Your local application (or SDK) intercepts this request, pauses the API interaction, and executes the local Python or Node.js get_weather function, and retrieves the result (e.g., "Raining, 15°C").
Observe & Append: Your application appends this real-world data to the conversation history as a tool_result message.
Re-Evaluate: The entire updated history is sent back to Claude. Claude reads the new data, realizes it now has the answer, and generates a final response with a stop_reason of end_turn.

3. The Problem with Raw API Calls

Building this loop using raw HTTP requests or a basic API wrapper is extremely tedious and error-prone. As an architect, if you build this from scratch, you have to manually handle:

State Management: Continuously appending system prompts, user messages, assistant messages, and tool results into an ever-growing array.
Routing Logic: Writing while loops to constantly check if the stop_reason is tool_use or end_turn.
JSON Parsing: Extracting the tool arguments Claude generated, matching them to your local functions, and safely handling the inevitable JSON formatting errors.

4. Enter the Agent SDK

An Agent SDK (whether it's Anthropic's official tools, or frameworks like LangChain, LlamaIndex, or standard Python/TypeScript agent wrappers) is designed to abstract away the boilerplate of the Agentic Loop.

When you use an Agent SDK, the architectural flow shifts:

Function Binding: You simply define standard local functions (e.g., querying a database, searching the web, checking an API).
Schema Generation: The SDK automatically translates your function's parameters into a JSON schema that Claude understands.
Autonomous Orchestration: You call a single method like agent.run(prompt). The SDK handles the while loop, securely executes the local functions when Claude asks for them, handles the message history state in memory, and only returns control to you when the final answer is ready.

5. The Golden Rule of Tool Execution

As you begin building agents, remember this critical architectural boundary: Claude does not run code. Claude only outputs text (JSON), asking you to run code. The Agent SDK is the execution environment. This separation of concerns is vital for security; it means you retain absolute control over what APIs are called, what databases are written to, and what permissions the agent actually has on your local system or servers.