LangChain Tutorial: Building an AI Agent with Tool Calling

The Key Point: LangChain Agents Are Best for Automation Tasks with Well-Defined Tool Boundaries

The value of a LangChain Agent is not to “let the model figure things out on its own,” but to place the LLM within a controlled Reasoning-Action loop: the model can only choose its next step from tools that you have registered, validated, and made auditable. It is suitable for tasks with clear boundaries, such as weather queries, ticket routing, log retrieval, and lightweight operations; it is not suitable for directly taking over high-risk actions like processing payments, dropping databases, or deploying to production.

• Suitable scenarios: Standardized RAG applications, automated execution of operations commands, API orchestration with complex parameter constraints.
• Unsuitable scenarios: Scenarios where tool permissions cannot be constrained, external API returns are unpredictable, or a deterministic transaction/approval chain is required 100%.

What This Guide Covers: Locking Query Intent

• How to transform a “chat-only” model into an AI agent with physical action capabilities?
• How to improve the model’s selection accuracy across multiple similar tools through Description optimization?
• How to make the Agent remember the results of previous steps without re-running the full prompt?
• How to drive the Agent to automatically retry and reflect when external APIs return errors or non-standard formats?
• How to implement persistent storage for Agent session memory in a distributed environment?

Who This Guide Is For

• Full-stack developers: Those looking to introduce AI automation capabilities into existing business systems to deepen system interactions.
• AI engineers: Those who need to master the core Agent component of the LangChain framework and its underlying execution loop.
• Beginners: Those who want to quickly get started with agent development through a complete, runnable Python example.

1. Xiaobai’s Note

Recently, while tinkering with personal productivity tools at home in Guiyang, I realized that relying solely on LLM chat no longer meets my automation needs. As a full-stack beginner, I deeply understand the importance of “tools.” If a standard LLM is a knowledgeable but disembodied “brain,” then an AI Agent is like giving that brain an exoskeleton. Today, I will take you deep into the core of LangChain to build a truly practical agent step-by-step. This is not a simple demo; it contains substantial content including Pydantic validation, memory management, and industrial-grade error handling.

2. ⚙️ The Essence of AgentExecutor: A Controlled Reasoning-Action Loop

Traditional programs follow predefined paths, whereas agents perform dynamic optimization. The underlying execution logic of AgentExecutor is as follows:

1. Reasoning: Send the input along with thought traces (Scratchpad) to the LLM.
2. Decision: The LLM returns AgentAction (call a tool) or AgentFinish (answer directly).
3. Action: The Executor locates the corresponding Tool, passes parameters, and intercepts execution.
4. Observation: Store the execution result in intermediate steps and feed it back to the model until a terminal state is reached.

3. Differences Between LangChain Agents and Traditional LLMs

Feature	Traditional LLM	LangChain Agent
Knowledge Timeliness	Limited to the training cutoff date	Can retrieve up-to-date information via search tools
Computational Power	Prone to mathematical hallucinations	Can invoke physical calculators or code interpreters
Task Depth	Single-turn Q&A with fixed paths	Autonomous planning and execution of multi-step complex tasks
Interactivity	Passive text response	Proactively operates databases, file systems, and APIs
Applicable Scenarios	Creative writing, simple Q&A	Automated operations, complex data auditing, personal assistants

4. Practical Example: Strongly Typed Tool Definition Based on Pydantic

# 2026 生产级工具定义示例
from langchain.tools import tool
from pydantic import BaseModel, Field

class WeatherInput(BaseModel):
    location: str = Field(description="城市名称，例如：贵阳, 北京")
    unit: str = Field(default="celsius", description="温度单位")

@tool("get_weather", args_schema=WeatherInput)
def get_weather(location: str, unit: str = "celsius") -> str:
    """查询指定城市的实时天气。用于判断是否适合户外运动。"""
    # 物理执行逻辑...
    return f"{location} 当前气温 22 {unit}，天气晴朗。"

The key to defining these tools isn’t brevity, but clear boundaries: parameters must be validated, return values must be interpretable, and failures must inform the Agent whether to retry, switch tools, or escalate to a human.

Engineering Boundary Checklist

Boundary	Recommended Practice	Failure Consequence
Tool Description	Specify when to use and when not to use it	Multiple tools compete for tasks, leading to loops
Parameter Schema	Use Pydantic to enforce types, enums, and defaults	LLM generates plausible but unexecutable parameters
Execution Permissions	Implement tiered authorization (read, write, delete)	A single erroneous call impacts real business data
Failure Response	Return explicit error codes and recoverable suggestions	The Agent sees vague errors and continues guessing

Practical Pitfalls and Error Guide (Error Logs)

1. Error: Infinite Loop via Overlapping Descriptions
   • Symptom: Two tools (e.g., “Query Database” and “Query Logs”) have descriptions that are too similar, causing the Agent to oscillate between them.
   • Solution: Clearly distinguish applicable boundaries in description and provide concrete examples.
2. Error: ShellTool Security Risks (Destructive Commands)
   • Cause: The Agent was induced to execute dangerous commands like rm -rf /.
   • Solution: Beginners are strongly advised to run the Agent process inside an isolated Docker container and enable strict command whitelisting for ShellTool.
3. Error: Output Parsing Failure
   • Solution: Enable handle_parsing_errors=True and customize error prompts to guide the model to regenerate output compliant with JSON specifications.

7. Frequently Asked Questions

Q: Why does my Agent always get stuck in an infinite loop?

A: Check if the max_iterations parameter is set and confirm whether the tool’s return value actually advances the task. If the model deems the Observation useless, it will keep retrying.

Q: Is using an Agent much more expensive than standard Chat?

A: Yes. Each iteration of an Agent includes previous intermediate_steps, causing context to expand rapidly. It is recommended to use GPT-4o-mini for intermediate steps and only invoke Claude 3.5 Sonnet for high-value decisions.

Recommended Deep Reading

• 👉 AI Agent Full-Stack Guide: An 10-word practical manual for building industrial-grade AI agent systems
• 👉 In-depth Comparison of AI Agent Frameworks: LangChain vs AutoGen vs CrewAI
• 👉 LangGraph in Action: 3 Design Patterns for Building Robust AI Agent Workflows

I am currently researching:

• Asynchronous concurrent tool scheduling algorithms based on LangChain
• The application of persistent Checkpoints in large-scale Agent task recovery
• Prompt preloading techniques with “intent prediction” capabilities

If you encounter unresolvable JSON errors while building a LangChain Agent, feel free to leave a comment. Let’s find the answer together in the code.

(Compiled by Xiaobai, first published on XBSTACK. Publication Date: 2026-04-25)

Topic path / AI Agents

Continue from one agent pattern to the complete production system

The AI Agent hub organizes architecture, memory, tool use, evaluation, security, deployment and multi-agent coordination into a single learning path.

Open AI Agent hub → Review the architecture guide Subscribe for updates