Advanced Data Structures & Algorithms

Java Backend Modernization

Beginner's Guide to Data Structures

Agentic AI Systems

Data Engineering & Spark Mastery

Low-Level Design Interview Prep

Microservices Interview Roadmap

Design Patterns Interview Roadmap

Distributed Systems Interview Roadmap

Mastering Python Development

System Design Interview Prep

Distributed Systems Refresher

AI Engineering Launchpad

Architecture Patterns for Scalable Systems

RAG & Vector Search Mastery

Production DevOps & Reliability

Enterprise Patterns Playbook

Master Coding Interviews

Coding Techniques Interview Roadmap

Data Structures Interview Roadmap

Architecture Patterns Interview Roadmap

software-engineering-principles

Migrate your Spring Boot services from thread-pool exhaustion to JDK 21 virtual threads — the practical Spring developer guide

Adapting to Virtual Threads for Spring Developers

how-it-works-internals-explained

From WAL and MVCC to fsync and isolation levels — the internals behind every ACID guarantee in PostgreSQL, MySQL, Oracle, and SQL Server.

ACID Properties Explained: How SQL Databases Guarantee Atomicity, Consistency, Isolation, and Durability

How modern NoSQL databases achieve atomicity and isolation without a single machine

ACID Transactions in Distributed Databases: DynamoDB, Cosmos DB, and Spanner Compared

llm-engineering

Is an LLM a brain in a jar? To make it truly useful, we need to give it access to the world. This guide explains RAG and Agents.

Advanced AI: Agents, RAG, and the Future of Intelligence

Production AI needs explicit routing, memory, execution, and evaluation layers rather than one loop.

AI Architecture Patterns: Routers, Planner-Worker Loops, Memory Layers, and Evaluation Guardrails

datastructures-and-algorithms

Master shortest paths, dependency resolution, and cycle detection with robust Java solutions.

Advanced Graph Algorithms: Dijkstra, Topological Sort, and Disjoint Set Union (DSU)

An LLM can talk, but an AI Agent can *act*. We explain how Agents use the ReAct framework to brow...

AI Agents Explained: When LLMs Start Using Tools

A production-first guide to picking the right vector index for recall, latency, memory, and update patterns.

ANN Index Types Explained: When to Choose Flat, HNSW, IVF, or IVF-PQ

apache-spark-engineering

Process petabytes with Python: understand Spark's execution model, DataFrame transformations, partitioning strategy, and real-time streaming.

Apache Spark for Data Engineers: RDDs, DataFrames, and Structured Streaming

ACID guarantees consistency. BASE guarantees availability. We explain the trade-offs between SQL...

BASE Theorem Explained: How it Stands Against ACID

machine-learning-fundamentals

From the query-key-value formulation to multi-head attention — the mechanism that made transformers dominate AI

Attention Mechanism Explained: How Transformers Learn to Focus

system-design-interview-prep

They all sit in front of your servers. But do you need Nginx, HAProxy, or Kong? We clarify the roles of each component.

API Gateway vs. Load Balancer vs. Reverse Proxy: What's the Difference?

architecture-patterns-for-production-systems

Mobile apps need less data than Desktop dashboards. Why serve them the same JSON? The Backend for Frontend (BFF) pattern solves this.

Backend for Frontend (BFF): Tailoring APIs for UI

BFS explores graphs level by level using a queue — the key to shortest paths and level-order problems.

BFS — Breadth-First Search: Level-by-Level Graph Exploration

Backtracking is a brute-force algorithmic technique that solves problems by trying to build a sol...

Exploring Backtracking Techniques in Data Structures

big-data-engineering

Choose ingestion, serving, and ownership patterns deliberately when data platforms start to scale.

Big Data Architecture Patterns: Lambda, Kappa, CDC, Medallion, and Data Mesh

Why traditional databases fail at scale, what the 5 Vs really mean, and a practical map of the big data ecosystem from ingestion to insights.

Big Data 101: The 5 Vs, Ecosystem, and Why Scale Breaks Everything

Not all Binary Trees are created equal. We explain Full, Complete, Perfect, and Balanced Binary T...

Exploring Different Types of Binary Trees

Master Big O notation: measure algorithm efficiency from O(1) to O(n²) with growth diagrams, worked examples, and the interview mental model.

Big O Notation Explained: Time Complexity, Space Complexity, and Why They Matter in Interviews

Binary search has five distinct patterns — classic, leftmost, rightmost, rotated arrays, and 2D matrices.

Binary Search Patterns: Five Variants Every Senior Engineer Knows

Simple AI agents react one step at a time. Multistep agents are different: they create a full pla...

Multistep AI Agents: The Power of Planning

Tools do one action; skills orchestrate many steps. Learn why this distinction makes agents far more reliable.

LLM Skills vs Tools: The Missing Layer in Agent Design

agentic-ai-langchain-and-langgraph

Build tool-using agents with LangChain: @tool decorator, AgentExecutor, ReAct reasoning, and when to reach for LangGraph instead.

LangChain Tools and Agents: The Classic Agent Loop

## Scenario context

A standard LLM is a brain in a jar — it can reason but cannot act. An **AI Agent** connects that brain to tools (web search, code execution, APIs). Instead of just answering a question, an agent executes a loop of Thought → Action → Observation until the goal is reached.

---

An **AI agent** is a program that uses a large language model as its reasoning engine and connects it to **external tools** so it can take re…

This walkthrough focuses on **The Basics: What Is an AI Agent**.

Before making a design choice, clarify:

- An AI agent is a program that uses a large language model as its reasoning engine and connects it to external tools so it can take real actions in the world.
- Where a plain LLM is purely generative — text in, text out — an agent augments the LLM with capabilities like web search, code execution, file reading, database queries, and API calls.
- Three components make up almost every agent: 1.

**Concepts in play:** llm-agents-and-langgraph, sorting-and-searching-algorithms, llm-prompt-engineering, database-indexing

## Stage 1 — The ReAct Loop: Thought → Action → Observation

- The dominant pattern for agents is ReAct (Reasoning + Acting).
- The model cycles through three steps until the task is complete: This loop continues until the model decides it has enough information to answer.

*Applies **llm-agents-and-langgraph** to the decision above.*

```mermaid
flowchart TD
    Start([User Goal]) --> T[Thought: What do I need?]
    T --> A[Action: Call a Tool]
    A --> O[Observation: Tool Result]
    O --> D{Goal reached?}
    D -- No --> T
    D -- Yes --> Answer([Return Final Answer])
```

```mermaid
sequenceDiagram
    participant U as User
    participant L as LLM
    participant T as Tool
    U->>L: User request
    L-->>L: Thought: what to do
    L->>T: Action: call tool
    T-->>L: Observation: result
    L-->>L: Next thought
    L-->>U: Final Answer
```

**Observable outcome:** The model cycles through three steps until the task is complete: This loop continues until the model decides it has enough information to answer.

## Stage 2 — How an Agent Processes a Request

- When a user sends a question to an agent-powered system, several layers of logic activate before any answer is returned.
- Understanding this flow helps you reason about latency, costs, and failure points.
- What happens at each node: - Inject Tool Schemas — before the first LLM call, all tool names, descriptions, and input types are serialised into the system prompt so the model knows what it can use.
- - LLM Reasoning — the model outputs a structured "Thought" explaining its next move.

*Applies **sorting-and-searching-algorithms** to the decision above.*

```mermaid
flowchart TD
    U([User Request]) --> SYS[Inject Tool Schemas into LLM Context]
    SYS --> LLM1[LLM Reasoning: Thought  What do I need?]
    LLM1 --> TC[Tool Selection: Which tool and args?]
    TC --> TE[Tool Execution: Call external function]
    TE --> OBS[Observation: Capture tool output]
    OBS --> CHK{Goal reached?}
    CHK -- No --> LLM1
    CHK -- Yes --> ANS([Return Final Answer to User])
```

**Observable outcome:** - LLM Reasoning — the model outputs a structured "Thought" explaining its next move.

## Stage 3 — Tool Definitions: How an Agent Knows What It Can Do

- A tool is a function the model can call.
- In LangChain you define tools with a name, description, and input schema: The model receives the tool descriptions in its system prompt and decides which to call (and with what arguments) based on the task.
- It never sees the implementation — only the name and docstring.

*Applies **llm-prompt-engineering** to the decision above.*

```python
from langchain.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for current information. Use this for recent events or facts."""
    return web_search_api(query)

@tool
def run_python(code: str) -> str:
    """Execute Python code and return the output. Use this for calculations."""
    return exec_sandbox(code)
```

```mermaid
flowchart TD
    I[Input from User] --> LM[LLM Reasoning]
    LM --> D{Need a tool?}
    D -- No --> R[Return Answer]
    D -- Yes --> TS[Select Tool]
    TS --> EX[Execute Tool]
    EX --> OB[Observe Output]
    OB --> LM
```

**Observable outcome:** It never sees the implementation — only the name and docstring.

## Stage 4 — Deep Dive: Building a Simple Agent with LangChain

- The verbose=True flag shows you the full Thought/Action/Observation chain — invaluable for debugging.

*Applies **database-indexing** to the decision above.*

```python



from langchain.agents import create_react_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from langchain import hub

llm = ChatOpenAI(model="gpt-4o-mini")
tools = [search_web, run_python]

prompt = hub.pull("hwchase17/react")          # standard ReAct prompt
agent = create_react_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

result = executor.invoke({"input": "Who was US president when Titanic was released?"})
print(result["output"])
```

**Observable outcome:** The verbose=True flag shows you the full Thought/Action/Observation chain — invaluable for debugging.

## Stage 5 — Real-World Applications: Real-World Agent Use Cases

- 

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** You can explain how “Real-World Applications: Real-World Agent Use Cases” changes the architecture or implementation path.

## Stage 6 — Practical: Debugging Agent Behavior

- Agents fail in opaque ways that are hard to catch without systematic debugging.
- Here is a practical workflow for diagnosing misbehaving agents.
- Step 1 — Enable verbose output.
- In LangChain, set verbose=True on the AgentExecutor .

*Applies **sorting-and-searching-algorithms** to the decision above.*

```python
executor = AgentExecutor(agent=agent, tools=tools, verbose=True, max_iterations=10)
```

**Observable outcome:** In LangChain, set verbose=True on the AgentExecutor .

## End-to-end outcome

An AI agent is a program that uses a large language model as its reasoning engine and connects it to external tools so it can take real actions in the world.

## Alternatives considered

### Brain in a Jar vs Brain with Arms

Give it "What is the weather in Tokyo today?" and it will: - Answer from training data (which is months or years old).

### Decision Guide: When to Use an AI Agent

Use an agent when the task requires multiple steps, tool use, or dynamic decision-making that can't be scripted upfront.


## Failure and degraded modes

### Trade-offs & Failure Modes: When Agents Fail: Hallucinations, Loops, and Cost Blowouts

- **Detection:** Agents introduce new failure modes beyond plain LLMs: Hallucinated tool calls — the model invents arguments or calls a non-existent tool.
- **User or operator impact:** Agents introduce new failure modes beyond plain LLMs: Hallucinated tool calls — the model invents arguments or calls a non-existent tool.



## Scenario context

A simple ReAct agent reacts one tool call at a time. A **multistep agent** plans a complete task decomposition upfront, then executes each step sequentially — handling complex goals that require 5-10 interdependent actions without re-prompting the LLM for each step.

---

A **line cook** (simple ReAct agent): receives one ticket, cooks one dish, hands it over. Then the next ticket.

A **head chef** (multistep agent)…

This walkthrough focuses on **Line Cook vs. Head Chef**.

Before making a design choice, clarify:

- A line cook (simple ReAct agent): receives one ticket, cooks one dish, hands it over.
- A head chef (multistep agent): receives the full dinner party menu, plans the entire 5-course sequence, coordinates prep timing for all dishes, anticipates which items can be done in parallel, and manages the full execu…
- The difference: planning before acting .

**Concepts in play:** llm-agents-and-langgraph, graph-traversal-algorithms, stack-and-queue-data-structures, api-security-oauth2

## Stage 1 — What Makes a Multistep Agent Different

- A simple ReAct agent operates with a single-step planning horizon : it looks at the current state, picks the next action, observes the result, and repeats.
- This works well for short, open-ended tasks where the required steps are unknown ahead of time.
- But when a task involves 5–10 interdependent actions, this approach becomes inefficient — the LLM must rediscover context at every step, decisions made in step 6 can conflict with assumptions from step 2, and there is n…
- A multistep agent solves this by introducing a distinct planning phase before any tool is called.

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** A multistep agent solves this by introducing a distinct planning phase before any tool is called.

## Stage 2 — The Plan-and-Execute Architecture

- Goal: "Research the top 3 AI papers from last month, summarize each, and draft a blog post." This flow highlights two key design decisions: plan validation happens before any tool call (catching hallucinated tool names…
- The re-plan path preserves completed step results — there is no need to restart from the beginning when a single step fails mid-execution.

*Applies **graph-traversal-algorithms** to the decision above.*

```mermaid
flowchart TD
    Goal[User Goal] --> Planner["LLM Planner (produce JSON step list)"]
    Planner --> Validate["Validate Plan (tool names, schema)"]
    Validate -->|Valid| Decompose[Decompose into Parallel + Sequential Steps]
    Validate -->|Invalid| Planner
    Decompose --> Parallel["Run Parallel Steps (independent actions)"]
    Decompose --> Sequential["Run Sequential Steps (dependent actions)"]
    Parallel --> Aggregate[Aggregate Intermediate Results]
    Sequential --> Aggregate
    Aggregate --> Check{All steps complete?}
    Check -->|Yes| Final[Final Result Delivered]
    Check -->|Step Failed| Replan[Re-plan Remaining Steps from Current State]
    Replan --> Decompose
```

**Observable outcome:** The re-plan path preserves completed step results — there is no need to restart from the beginning when a single step fails mid-execution.

## Stage 3 — Real-World Applications: Real-World Use Cases

- Multistep agents are not theoretical constructs — they power several categories of real production systems today.
- Automated Research Pipelines A research agent might receive a goal like "produce a competitive analysis of the top 5 CRM tools." The plan includes: search for the top 5 tools (step 1), fetch the pricing page for each to…
- No human re-prompts the system between steps — the plan drives the full execution.
- Coding Agents Agents like GitHub Copilot Workspace and Devin use multistep planning to handle tasks like "add OAuth login to this codebase." The plan might include: reading existing auth files, identifying integration p…

*Applies **stack-and-queue-data-structures** to the decision above.*

```mermaid
sequenceDiagram
    participant U as User
    participant P as LLM Planner
    participant E as Executor
    participant T as Tools

    U->>P: Submit goal
    P->>P: Decompose into step list
    P-->>E: Plan [step1, step2, step3...]
    E->>T: Execute step 1
    T-->>E: Result 1
    E->>P: Observe result 1
    P->>P: Update plan if needed
    E->>T: Execute step 2
    T-->>E: Result 2
    E->>T: Execute step 3
    T-->>E: Result 3
    E-->>U: Aggregated final answer
```

```mermaid
flowchart TD
    Goal[Receive Goal]
    Decompose[LLM: Decompose into step list]
    Queue["Queue Steps (DAG order)"]
    Execute[Execute Next Step with Tools]
    UpdateState[Update Shared State with Result]
    Done{All Steps Complete?}
    Replan{Step Failed?}
    Final[Return Final Result]
    ReplanStep[Re-plan Remaining Steps from State]

    Goal --> Decompose --> Queue --> Execute --> UpdateState
    UpdateState --> Done
    Done -->|Yes| Final
    Done -->|No| Replan
    Replan -->|Yes| ReplanStep --> Queue
    Replan -->|No| Execute
```

**Observable outcome:** Coding Agents Agents like GitHub Copilot Workspace and Devin use multistep planning to handle tasks like "add OAuth login to this codebase." The plan might include: reading existing auth files, identifying integration p…

## Stage 4 — Practical: Building a Simple Plan-and-Execute Agent

- The fastest way to understand multistep agents is to trace how the planner and executor components interact in code.
- Below is a minimal Python example using LangChain's PlanAndExecute abstraction with custom tools.
- Step 1 — Define tools and the LLM: Step 2 — Wire up planner and executor: Step 3 — Invoke with a multi-step goal: When you run this with verbose=True , you will see the planner emit a JSON step list, then the executor c…
- This trace is invaluable for debugging — if a step produces an unexpected output, you can inspect exactly where the plan diverged from reality and adjust either the planner prompt or the tool implementation accordingly.

*Applies **api-security-oauth2** to the decision above.*

```python
from langchain_openai import ChatOpenAI
from langchain.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for the given query."""
    return f"Results for: {query}"

@tool
def summarize_text(text: str) -> str:
    """Summarize the provided text."""
    return f"Summary of: {text[:50]}..."

tools = [search_web, summarize_text]
llm = ChatOpenAI(model="gpt-4o", temperature=0)
```

```python
from langchain_experimental.plan_and_execute import (
    PlanAndExecute, load_agent_executor, load_chat_planner
)

planner  = load_chat_planner(llm)                          # single LLM call that generates the JSON step list
executor = load_agent_executor(llm, tools, verbose=True)   # runs each step; verbose=True prints tool call traces
agent    = PlanAndExecute(planner=planner, executor=executor, verbose=True)
```

**Observable outcome:** This trace is invaluable for debugging — if a step produces an unexpected output, you can inspect exactly where the plan diverged from reality and adjust either the planner prompt or the tool implementation accordingly.

## Stage 5 — LangGraph and AutoGen: How OSS Frameworks Implement Multistep Agent Orchestration

- Two open-source frameworks have emerged as the leading ways to build multistep agents with explicit state management, and they take very different architectural approaches.
- LangGraph is a graph-based agent orchestration library from LangChain that models an agent's execution as a directed graph of nodes (LLM calls, tool calls, or logic) and edges (conditional transitions).
- It gives you full control over state, supports cycles (loops), and is designed for durable, resumable workflows — making it the production-ready choice for complex multistep pipelines.
- AutoGen (Microsoft) takes a conversation-centric approach — agents are modeled as participants in a multi-agent dialogue, where each agent has a role (AssistantAgent, UserProxyAgent) and can call tools or other agents a…

*Applies **llm-agents-and-langgraph** to the decision above.*

```python
from langgraph.graph import StateGraph, END
from typing import TypedDict

# Define the shared state for the agent
class AgentState(TypedDict):
    task: str
    plan: list
    results: list
    current_step: int

# Build the graph
graph = StateGraph(AgentState)

# Add nodes: each is a function that reads and writes state
graph.add_node("planner", run_planner)      # LLM call → produces plan list
graph.add_node("executor", run_executor)    # Tool call → appends to results
graph.add_node("checker", check_completion) # Logic → routes to next step or END

# Wire the execution flow
graph.set_entry_point("planner")
graph.add_edge("planner", "executor")
graph.add_conditional_edges(
    "executor",
    lambda state: "checker" if state["current_step"] < len(state["plan"]) else END,
)
graph.add_edge("checker", "executor")

agent = graph.compile()
result = agent.invoke({"task": "Research top 3 AI papers and draft a summary", "plan": [], "results": [], "current_step": 0})
```

```python
from autogen import AssistantAgent, UserProxyAgent

planner = AssistantAgent(
    name="Planner",
    system_message="You decompose goals into numbered steps and produce a JSON plan.",
    llm_config={"model": "gpt-4o"},
)

executor = UserProxyAgent(
    name="Executor",
    human_input_mode="NEVER",
    code_execution_config={"work_dir": "./workspace"},
)

# The executor drives the conversation; the planner produces the plan
executor.initiate_chat(
    planner,
    message="Research the top 3 AI papers from last month and summarize each.",
    max_turns=10,
)
```

**Observable outcome:** AutoGen (Microsoft) takes a conversation-centric approach — agents are modeled as participants in a multi-agent dialogue, where each agent has a role (AssistantAgent, UserProxyAgent) and can call tools or other agents a…

## Stage 6 — Key Lessons

- Plan validation is non-negotiable.
- Always validate the generated plan against the registered tool list and expected argument schema before execution begins.
- Catching hallucinated tool names at plan time costs one validation pass; catching them at execution time costs the tokens from all preceding steps plus a re-plan.
- Re-plan from failure state, not from scratch.

*Applies **graph-traversal-algorithms** to the decision above.*

**Observable outcome:** Re-plan from failure state, not from scratch.

## End-to-end outcome

A line cook (simple ReAct agent): receives one ticket, cooks one dish, hands it over.

## Alternatives considered

### Line Cook vs. Head Chef

A line cook (simple ReAct agent): receives one ticket, cooks one dish, hands it over.

### Simple ReAct vs. Plan-and-Execute: Core Difference

Simple ReAct vs. Plan-and-Execute: Core Difference

### Decision Guide: ReAct vs. Plan-and-Execute

Decision Guide: ReAct vs. Plan-and-Execute


## Failure and degraded modes

### Trade-offs & Failure Modes: When to Use Multistep Agents vs Simple Agents

- **Detection:** Critical failure modes for multistep agents: - Stale plan: If step 3 fails, steps 4-8 may be based on incorrect assumptions.
- **User or operator impact:** Critical failure modes for multistep agents: - Stale plan: If step 3 fails, steps 4-8 may be based on incorrect assumptions.



## Scenario context

A tool is a single callable capability (search, SQL, calculator). A skill is a reusable mini-workflow that coordinates multiple tool calls with policy, guardrails, retries, and output structure. If you model everything as "just tools," your agent usually works in demos but fails in production.

---

An AI agent built to assist financial analysts had a `calculator` tool registered in its tool list. Yet in testing, it…

This walkthrough focuses on **Why "Skill" Is Not Just a Fancy Name for "Tool"**.

Before making a design choice, clarify:

- An AI agent built to assist financial analysts had a calculator tool registered in its tool list.
- Yet in testing, it kept producing arithmetic errors — computing 12.4 8.7 and returning 107.9 instead of the correct 107.88 .
- The calculator tool itself worked perfectly when called.

**Concepts in play:** llm-agents-and-langgraph, event-driven-architecture, graph-traversal-algorithms, sorting-and-searching-algorithms

## Stage 1 — The Three-Layer Mental Model: Model, Tools, Skills

- A practical way to design modern agents is with three layers: 1.
- LLM layer : reasoning, planning, and language generation.
- Tool layer : external operations (APIs, databases, code execution, search).
- Skill layer : orchestrated routines that solve recurring goals.

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** Skill layer : orchestrated routines that solve recurring goals.

## Stage 2 — How a Skill Actually Runs Across Multiple Tools

- Suppose the user asks: "Investigate this outage alert and open a ticket with a clear summary." A tool-only design might call APIs opportunistically.
- A skill-based design follows a known contract.
- Validate input schema ( service , time range , alert id ).
- Run consistency checks (for example, severity must match evidence).

*Applies **event-driven-architecture** to the decision above.*

```mermaid
flowchart TD
    A[User goal: investigate outage and open ticket] --> B[Planner selects IncidentTriageSkill]
    B --> C[Step 1: fetch logs tool]
    C --> D[Step 2: classify severity tool]
    D --> E[Step 3: summarize findings tool]
    E --> F[Step 4: create ticket tool]
    F --> G[Return structured result: summary, severity, ticket_id]
```

**Observable outcome:** Run consistency checks (for example, severity must match evidence).

## Stage 3 — Deep Dive: What Makes a Skill Reliable in Production

- The internals: a skill is policy plus orchestration A production-grade skill usually includes these internal parts: This architecture lets you debug behavior at the skill level instead of reverse-engineering long prompt…
- Mathematical model: choosing the best skill for a goal When several skills could solve a request, use an explicit routing score: $$ Score(skill i \mid goal) = \alpha C i - \beta L i - \gamma R i + \delta F i $$ Where: -…
- This is not "academic math." It is a practical routing heuristic that prevents random skill selection.
- Performance analysis: skills add overhead but reduce incident rate Skills trade a little raw speed for much better reliability and operator confidence.

*Applies **graph-traversal-algorithms** to the decision above.*

**Observable outcome:** Performance analysis: skills add overhead but reduce incident rate Skills trade a little raw speed for much better reliability and operator confidence.

## Stage 4 — Real-World Application Patterns

- Case study 1: Support triage assistant - Input : incoming ticket text and account metadata.
- - Process : skill calls sentiment tool, policy lookup tool, and routing API.
- - Output : priority, queue assignment, and draft response.
- Case study 2: Engineering incident assistant - Input : alert payload from monitoring system.

*Applies **sorting-and-searching-algorithms** to the decision above.*

**Observable outcome:** Case study 2: Engineering incident assistant - Input : alert payload from monitoring system.

## Stage 5 — Practical Examples: Implementing a Skill Layer

- Example 1: Declare tools and a skill contract These examples build a skill layer incrementally: first by declaring individual tool functions and a typed input contract, then by wrapping them with retry logic, confidence…
- This progression was chosen to demonstrate that skill design is an architectural discipline, not a framework choice — the same pattern applies in pure Python before any orchestration library is introduced.
- When reading the code, focus on how the output shape and error handling are specified inside the skill function itself: this is what separates a skill runtime from a simple function call chain.
- This is already more robust than free-form tool hopping because the output shape is stable.

*Applies **llm-agents-and-langgraph** to the decision above.*

```python
from dataclasses import dataclass
from typing import Any, Dict

def fetch_logs(service: str, time_range: str) -> str:
    # Placeholder for real API integration.
    return f"logs(service={service}, window={time_range})"

def classify_severity(log_blob: str) -> Dict[str, Any]:
    return {"severity": "high", "confidence": 0.87}

def create_ticket(summary: str, severity: str) -> str:
    return "INC-48291"

@dataclass
class IncidentInput:
    service: str
    time_range: str
    alert_id: str

def incident_triage_skill(payload: IncidentInput) -> Dict[str, Any]:
    logs = fetch_logs(payload.service, payload.time_range)
    cls = classify_severity(logs)
    summary = f"Alert {payload.alert_id} appears {cls['severity']} severity"
    ticket_id = create_ticket(summary, cls["severity"])
    return {
        "summary": summary,
        "severity": cls["severity"],
        "confidence": cls["confidence"],
        "ticket_id": ticket_id,
    }
```

```python
import time

def run_with_retry(fn, max_attempts=3, base_delay=0.5):
    for attempt in range(1, max_attempts + 1):
        try:
            return fn()
        except Exception:
            if attempt == max_attempts:
                raise
            time.sleep(base_delay * attempt)

def safe_incident_triage(payload: IncidentInput) -> Dict[str, Any]:
    if not payload.service or not payload.time_range:
        raise ValueError("service and time_range are required")

    logs = run_with_retry(lambda: fetch_logs(payload.service, payload.time_range))
    cls = run_with_retry(lambda: classify_severity(logs))

    if cls["confidence"] < 0.60:
        return {
            "status": "needs_human_review",
            "reason": "low_classifier_confidence",
            "alert_id": payload.alert_id,
        }

    summary = f"Alert {payload.alert_id} appears {cls['severity']} severity"
    ticket_id = run_with_retry(lambda: create_ticket(summary, cls["severity"]))

    return {
        "status": "ok",
        "summary": summary,
        "severity": cls["severity"],
        "ticket_id": ticket_id,
    }
```

**Observable outcome:** This is already more robust than free-form tool hopping because the output shape is stable.

## Stage 6 — LangChain Tools API: Registering Atomic Tools and Promoting Them to Skills

- LangChain provides Tool and StructuredTool abstractions that formalize the tool layer described throughout this post.
- StructuredTool adds a Pydantic input schema, making tool calls type-safe, self-documenting, and enabling the LLM to validate inputs before execution — the exact boundary that separates reliable tool use from ad-hoc prom…
- StructuredTool wraps the entire skill — including its internal multi-step tool orchestration — behind a single schema-validated interface.
- The LLM calls one tool; internally it runs the sequence, applies the policy gate, and returns a structured result.

*Applies **event-driven-architecture** to the decision above.*

```python
# pip install langchain langchain-core pydantic
from langchain_core.tools import Tool, StructuredTool
from pydantic import BaseModel, Field
from typing import Any, Dict

# --- Layer 1: Simple Tool — one string input, minimal guardrails ---
fetch_logs_tool = Tool(
    name="fetch_logs",
    description="Fetch recent log snippets for a service name. Returns a raw log string.",
    func=lambda service: f"[ERROR] 3 timeout errors in {service} over last 15 min",
)

# --- Layer 2: StructuredTool — typed multi-field input with Pydantic validation ---
class IncidentInput(BaseModel):
    service:    str = Field(description="Service name, e.g. 'payments-svc'")
    time_range: str = Field(description="Lookback window, e.g. 'last_15m'")
    alert_id:   str = Field(description="Unique alert ID from monitoring system")

def triage_incident(service: str, time_range: str, alert_id: str) -> Dict[str, Any]:
    """
    Skill function: orchestrates sub-tools internally.
    The LLM sees one tool; internally it runs multiple steps with built-in policy.
    """
    logs     = fetch_logs_tool.run(service)
    severity = "high" if "error" in logs.lower() else "low"

    # Policy gate: only escalate confirmed high-severity alerts
    if severity == "high" and "timeout" in logs:
        ticket_id = f"INC-{abs(hash(alert_id)) % 9999:04d}"
    else:
        ticket_id = None

    return {
        "alert_id":  alert_id,
        "severity":  severity,
        "ticket_id": ticket_id,
        "summary":   f"Service {service} shows {severity} severity over {time_range}",
    }

incident_skill = StructuredTool.from_function(
    func=triage_incident,
    name="incident_triage_skill",
    description=(
        "Run full incident triage: fetch logs, classify severity, open ticket if high. "
        "Returns structured report with alert_id, severity, ticket_id, and summary."
    ),
    args_schema=IncidentInput,
)

# The LLM calls one structured tool — the skill handles all internal orchestration
print(incident_skill.invoke({
    "service": "payments-svc",
    "time_range": "last_15m",
    "alert_id": "ALT-9910",
}))
```

**Observable outcome:** The LLM calls one tool; internally it runs the sequence, applies the policy gate, and returns a structured result.

## End-to-end outcome

After working through the stages, you should be able to explain:

- - Treat tools as primitives, not products.
- Skills are where product behavior actually lives.

## Alternatives considered

### Control-Flow View: Single Tool Call vs Skill Runtime

A side-by-side sequence perspective makes the distinction obvious.

### Decision Guide: Should This Be a Tool, a Skill, or a Workflow Engine?

Use this heuristic: if your prompt keeps repeating the same sequence of tool calls, promote that sequence into a skill.


## Failure and degraded modes

### Trade-offs & Failure Modes: Trade-offs and Failure Modes You Should Plan For

- **Detection:** They add a control layer, and that layer must be designed carefully.
- **User or operator impact:** They add a control layer, and that layer must be designed carefully.



## Scenario context

Consider this prompt to a raw language model:

> *"What's the current weather in Tokyo, and how does today's high compare to yesterday's?"*

The model answers confidently. It might even produce a plausible-sounding temperature. But that answer is fabricated — the model's weights were frozen at training cutoff and it has no mechanism to observe the world at inference time. It cannot make an HTTP request. It cannot re…

This walkthrough focuses on **The Gap Between "Saying" and "Doing": Why LLMs Need Tools**.

Before making a design choice, clarify:

- Consider this prompt to a raw language model: "What's the current weather in Tokyo, and how does today's high compare to yesterday's?" The model answers confidently.
- It might even produce a plausible-sounding temperature.
- But that answer is fabricated — the model's weights were frozen at training cutoff and it has no mechanism to observe the world at inference time.

**Concepts in play:** llm-agents-and-langgraph, low-level-design-systems, llm-prompt-engineering, event-driven-architecture

## Stage 1 — What a Tool Actually Is: A Python Function the LLM Can Request

- A tool, in LangChain's model, is nothing exotic.
- It is a regular Python function that: 1.
- Has a name the LLM uses to refer to it.
- Has a description (from the docstring) that the LLM reads to decide when to call it.

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** Has a description (from the docstring) that the LLM reads to decide when to call it.

## Stage 2 — Turning Python Functions into LLM Tools with the @tool Decorator

- The Decorator Approach The @tool decorator from langchain core.tools is the simplest way to define a tool.
- Decorate a function, write a meaningful docstring, and annotate the parameters — that's it.
- The docstring is not documentation for human readers — it is the tool's entire identity to the LLM.
- The model reads it to decide whether to call the tool at all.

*Applies **low-level-design-systems** to the decision above.*

```python
# NOTE: External API calls below are mocked for local development.
# Replace the mock return values with real API calls in production.

from langchain_core.tools import tool

@tool
def get_current_weather(city: str) -> str:
    """
    Fetch the current weather for a given city.
    Returns a plain-text description including temperature and conditions.
    Use this when the user asks about current or today's weather anywhere.
    """
    # Mock: in production, call OpenWeatherMap or similar
    mock_data = {
        "tokyo": "Tokyo: 18°C, partly cloudy, humidity 65%",
        "london": "London: 12°C, overcast, humidity 80%",
        "new york": "New York: 22°C, sunny, humidity 45%",
    }
    return mock_data.get(city.lower(), f"Weather data unavailable for {city}")

@tool
def get_yesterday_weather(city: str) -> str:
    """
    Fetch yesterday's high temperature for a given city.
    Returns a plain-text description of yesterday's weather summary.
    Use this when the user wants to compare today's weather to yesterday's.
    """
    # Mock: in production, query a historical weather API
    mock_data = {
        "tokyo": "Tokyo yesterday: high of 15°C, light rain",
        "london": "London yesterday: high of 10°C, cloudy",
        "new york": "New York yesterday: high of 20°C, partly cloudy",
    }
    return mock_data.get(city.lower(), f"Historical weather unavailable for {city}")
```

```python
from pydantic import BaseModel, Field
from langchain_core.tools import tool

class StockLookupInput(BaseModel):
    ticker: str = Field(description="Stock ticker symbol, e.g. AAPL, TSLA, NVDA")
    currency: str = Field(default="USD", description="Currency for the price output (USD or EUR)")

@tool("get_stock_price", args_schema=StockLookupInput)
def get_stock_price(ticker: str, currency: str = "USD") -> str:
    """
    Return the current stock price for a given ticker symbol.
    Use this when the user asks about stock prices or market data.
    Do NOT use this for cryptocurrency prices.
    """
    # Mock: in production, call Yahoo Finance, Alpha Vantage, or Polygon.io
    mock_prices = {"AAPL": 213.07, "TSLA": 172.30, "NVDA": 118.42, "MSFT": 415.20}
    price = mock_prices.get(ticker.upper())
    if price is None:
        return f"No price data found for {ticker}"
    if currency == "EUR":
        price = round(price * 0.92, 2)
    return f"{ticker.upper()} is trading at {currency} {price:.2f}"
```

**Observable outcome:** The model reads it to decide whether to call the tool at all.

## Stage 3 — Deep Dive: How AgentExecutor Orchestrates the ReAct Loop

- The Internals: AgentExecutor as a Configurable Runnable Loop AgentExecutor is LangChain's agent runner.
- Internally, it is a while-loop wrapped around a runnable chain: on each iteration, it calls the LLM, inspects the output, decides whether to invoke a tool, runs the tool if needed, appends the observation to the message…
- It exits when the LLM produces a final answer (no more tool calls) or when a configured maximum step count is reached.
- The loop follows the ReAct (Reasoning + Acting) pattern, published by Yao et al.

*Applies **llm-prompt-engineering** to the decision above.*

```python
from langchain import hub
from langchain.agents import AgentExecutor, create_react_agent
from langchain_openai import ChatOpenAI

# Pull the standard ReAct prompt from LangChain Hub
# It instructs the LLM to emit Thought/Action/Observation cycles
react_prompt = hub.pull("hwchase17/react")

llm = ChatOpenAI(model="gpt-4o", temperature=0)
tools = [get_current_weather, get_yesterday_weather, get_stock_price]

agent = create_react_agent(llm=llm, tools=tools, prompt=react_prompt)

executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,          # print the full reasoning trace
    max_iterations=6,      # hard stop to prevent runaway loops
    handle_parsing_errors=True,  # recover from malformed tool calls
)

result = executor.invoke({"input": "What's the current weather in Tokyo and how does it compare to yesterday?"})
print(result["output"])
```

```
> Entering new AgentExecutor chain...
Thought: I need to fetch the current weather in Tokyo and yesterday's weather to compare them.
Action: get_current_weather
Action Input: {"city": "tokyo"}
Observation: Tokyo: 18°C, partly cloudy, humidity 65%

Thought: Now I need yesterday's weather to compare.
Action: get_yesterday_weather
Action Input: {"city": "tokyo"}
Observation: Tokyo yesterday: high of 15°C, light rain

Thought: I have both data points. Today is 18°C and partly cloudy; yesterday peaked at 15°C with rain.
Final Answer: Tokyo is currently 18°C and partly cloudy — 3 degrees warmer than yesterday's high of 15°C, and the rain has cleared.
```

**Observable outcome:** The loop follows the ReAct (Reasoning + Acting) pattern, published by Yao et al.

## Stage 4 — Visualizing the ReAct Loop: Thought → Action → Observation → Answer

- The flowchart below shows the complete execution path for a single agent invocation: Each loop back from Observation to Agent is one complete ReAct cycle.
- The LLM decides at every step whether to call another tool or produce a final answer.
- The sequence below zooms into the message-passing protocol between components during one tool call cycle: Two tool calls, three LLM calls, one final answer.
- Every message is appended to the conversation before the next LLM call — this is what "context grows with each step" means in practice.

*Applies **event-driven-architecture** to the decision above.*

```mermaid
flowchart TD
    A([User Query]) --> B[Agent: LLM + Prompt]
    B --> C{Tool call in response?}
    C -- Yes --> D[AgentExecutor: Dispatch Tool]
    D --> E[Tool Function Executes]
    E --> F[Observation appended to history]
    F --> G{Max iterations reached?}
    G -- No --> B
    G -- Yes --> H([Force-stop: return partial answer])
    C -- No --> I([Final Answer returned to user])
```

```mermaid
sequenceDiagram
    participant U as User
    participant AE as AgentExecutor
    participant LLM as LLM (gpt-4o)
    participant T as Tool Function

    U->>AE: invoke({"input": "Weather in Tokyo vs yesterday?"})
    AE->>LLM: [SystemPrompt + UserMessage]
    LLM-->>AE: AIMessage(tool_calls=[get_current_weather])
    AE->>T: get_current_weather(city="tokyo")
    T-->>AE: "Tokyo: 18C, partly cloudy"
    AE->>LLM: ["History + ToolMessage(observation)"]
    LLM-->>AE: AIMessage(tool_calls=[get_yesterday_weather])
    AE->>T: get_yesterday_weather(city="tokyo")
    T-->>AE: "Tokyo yesterday: high of 15C, light rain"
    AE->>LLM: ["History + ToolMessage(observation)"]
    LLM-->>AE: AIMessage(content="Tokyo is 3C warmer today...")
    AE-->>U: {"output": "Tokyo is 3C warmer today..."}
```

**Observable outcome:** Every message is appended to the conversation before the next LLM call — this is what "context grows with each step" means in practice.

## Stage 5 — Real-World Applications of Built-in LangChain Tools

- LangChain ships several ready-to-use tools that cover the most common "reach the internet" use cases.
- Knowing when to use each one saves you from writing boilerplate integrations.
- DuckDuckGo Search is the no-API-key option for web search.
- It returns a handful of snippets and URLs.

*Applies **llm-agents-and-langgraph** to the decision above.*

```python
from langchain_community.tools import DuckDuckGoSearchRun

search = DuckDuckGoSearchRun()
print(search.run("LangChain AgentExecutor latest release"))
```

```python
from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

wikipedia = WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000))
print(wikipedia.run("ReAct prompting technique"))
```

**Observable outcome:** It returns a handful of snippets and URLs.

## Stage 6 — Worked Example: A Research Assistant with Web Search, Calculator, and Stock Price

- This example wires three tools into a single AgentExecutor — a DuckDuckGo search, a custom calculator, and a custom stock price lookup.
- The goal is a "Research Assistant" agent that can answer compound questions.
- Execution trace (abbreviated): The agent correctly sequences three distinct tool types — a mock API, a calculation, and a live web search — and synthesizes them into a coherent answer.
- No user code controlled the sequencing; the LLM decided the order based on its reasoning.

*Applies **low-level-design-systems** to the decision above.*

```python
# NOTE: Install dependencies:
# pip install langchain langchain-openai langchain-community duckduckgo-search

from langchain_core.tools import tool
from langchain_community.tools import DuckDuckGoSearchRun
from langchain_openai import ChatOpenAI
from langchain import hub
from langchain.agents import AgentExecutor, create_react_agent

# --- Tool 1: Web search (built-in, no API key) ---
web_search = DuckDuckGoSearchRun(name="web_search")

# --- Tool 2: Calculator ---
@tool
def calculator(expression: str) -> str:
    """
    Evaluate a mathematical expression and return the numeric result.
    Input must be a valid Python arithmetic expression, e.g. "1500 * 1.07 ** 10".
    Use this for any calculation that requires precise arithmetic.
    """
    try:
        result = eval(expression, {"__builtins__": {}}, {})  # restricted eval
        return f"Result: {result}"
    except Exception as exc:
        return f"Error evaluating expression: {exc}"

# --- Tool 3: Stock price lookup ---
@tool
def get_stock_price(ticker: str) -> str:
    """
    Return the current stock price for a given ticker symbol (e.g. AAPL, MSFT, NVDA).
    Use this when the user asks about stock prices or market valuations.
    NOTE: Returns mock data — replace with a real market data API in production.
    """
    mock_prices = {
        "AAPL": 213.07, "TSLA": 172.30, "NVDA": 118.42,
        "MSFT": 415.20, "GOOGL": 175.50, "AMZN": 198.90,
    }
    price = mock_prices.get(ticker.upper())
    if price is None:
        return f"No price data found for ticker: {ticker}"
    return f"{ticker.upper()} current price: ${price:.2f} USD"

# --- Assemble the agent ---
tools = [web_search, calculator, get_stock_price]
llm = ChatOpenAI(model="gpt-4o", temperature=0)
react_prompt = hub.pull("hwchase17/react")

agent = create_react_agent(llm=llm, tools=tools, prompt=react_prompt)
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    max_iterations=8,
    handle_parsing_errors=True,
)

# --- Run a compound research query ---
response = executor.invoke({
    "input": (
        "What is NVIDIA's current stock price? "
        "If I invested $5,000 at that price, how many shares would I own? "
        "Also search for the latest news about NVIDIA's AI chips."
    )
})
print("\n=== FINAL ANSWER ===")
print(response["output"])
```

```
> Entering new AgentExecutor chain...
Thought: I need three pieces of information: NVIDIA stock price, share count calculation, and news.
Action: get_stock_price
Action Input: {"ticker": "NVDA"}
Observation: NVDA current price: $118.42 USD

Thought: Now I'll calculate shares.
Action: calculator
Action Input: {"expression": "5000 / 118.42"}
Observation: Result: 42.22...

Thought: Now I'll search for NVIDIA AI chip news.
Action: web_search
Action Input: NVIDIA AI chips latest news 2026
Observation: [DuckDuckGo snippets about Blackwell GPU architecture, data center demand...]

Thought: I have all three pieces of data. I can compose the final answer.
Final Answer: NVIDIA is currently trading at $118.42. With $5,000 you would own approximately
42.2 shares. Recent news highlights strong demand for Blackwell GPUs in AI data centers...
```

**Observable outcome:** No user code controlled the sequencing; the LLM decided the order based on its reasoning.

## End-to-end outcome

After working through the stages, you should be able to explain:

- Write docstrings for the model, not for humans.
- Every word in a tool docstring is LLM prompt text.
- - LLMs only predict tokens — they cannot fetch data, run calculations, or execute code.
- Tools are the mechanism that bridges language to action.

## Alternatives considered

### AgentExecutor Under the Hood: Runnable Sequences and the Tool-Calling vs. ReAct Distinction

AgentExecutor is built on LangChain's LCEL (LangChain Expression Language) runnable interface.

### Decision Guide: Classic AgentExecutor or LangGraph?

The right tool depends on the complexity of the agent's decision-making surface.


## Failure and degraded modes

### AgentExecutor Trade-offs and Failure Modes

- **Detection:** AgentExecutor is a pragmatic tool with well-understood limitations.
- **User or operator impact:** AgentExecutor is a pragmatic tool with well-understood limitations.



Step 1

Design stateful agents, planning paradigms, and autonomous tool-using loops.

Autonomous AI Agents