LangChain已经成为构建大语言模型应用的主流框架之一，其中Agent（智能体）能力尤其受到关注。和普通的聊天模型不同，Agent不仅会根据输入生成文本回复，还能在推理过程中自行决定调用哪些外部工具、传递什么参数、如何解读工具返回的结果，并继续迭代直到完成任务。本文的目标是通过一个完整的实例，带你从零开始搭建一个具备工具调用能力的Chat Agent。整个过程不需要复杂的配置，只需要Python环境和OpenAI API密钥即可跑通。
本教程会按照以下顺序展开：先准备Python虚拟环境和必要的依赖包，然后创建一个基本的Chat模型并测试其对话能力，接着定义几个简单工具并将它们绑定到Agent上，最后为Agent添加记忆功能以支持多轮对话。每个步骤都会给出完整的代码片段，你可以直接复制到自己的编辑器里运行。文章末尾还会整理一些新手容易踩到的坑以及对应的解决办法。
环境准备与依赖安装
在开始编写任何代码之前，需要确保本机已经安装了Python 3.9或更高版本。推荐使用虚拟环境隔离项目依赖，避免与其他项目产生冲突。打开终端或命令提示符，执行下面的命令创建并激活一个名为langchain-agent的虚拟环境。Windows用户、macOS用户以及Linux用户的激活命令略有不同，请根据实际情况选择。
# 创建虚拟环境 python -m venv langchain-agent # Windows 激活 langchain-agent\Scripts\activate # macOS / Linux 激活 source langchain-agent/bin/activate
激活虚拟环境后，使用pip安装LangChain以及OpenAI的Python SDK。本文示例基于LangChain 0.3版本编写，安装命令会自动拉取兼容的依赖。如果你使用的是Anthropic或其他模型提供商，也可以替换成对应的包，但代码中的导入路径会略有差异。
pip install langchain langchain-openai python-dotenv
python-dotenv用于从.env文件中读取环境变量，这样可以避免把API密钥硬编码在脚本里。在项目根目录下创建一个.env文件，内容如下，将your-api-key-here替换成真实的OpenAI API密钥。如果你还没有密钥，需要先到OpenAI平台注册并创建。
OPENAI_API_KEY=your-api-key-here
接下来在Python脚本的开头加载这些环境变量。通常的做法是导入dotenv并调用load_dotenv()，然后使用os.getenv()来获取密钥。LangChain内部会自动读取OPENAI_API_KEY变量，只要它在当前进程的环境中存在即可。完成这一步之后，环境准备就绪，可以开始编写实际的对话逻辑了。
使用LangChain创建基础聊天模型
LangChain提供了多种聊天模型的封装，最常用的是ChatOpenAI。它支持所有OpenAI的对话模型，例如gpt-4o、gpt-4o-mini等。下面这段代码演示了如何初始化一个ChatOpenAI实例并调用invoke方法获得回复。注意invoke方法接收的是一个消息列表，而不是简单的字符串，这是LangChain聊天模型与普通文本模型的一个重要区别。
from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage # 初始化聊天模型 llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7) # 构造一条人类消息 message = HumanMessage(content="你好，请用一句话介绍你自己。") # 调用模型并打印回复 response = llm.invoke([message]) print(response.content)
运行这段代码，你会在控制台看到模型返回的自我介绍。如果出现网络错误或认证失败，请检查.env文件中的密钥是否正确，以及网络是否能访问OpenAI的API端点。一旦基础模型能够正常响应，就可以在此基础上构建更复杂的Agent逻辑。
在实际开发中，我们很少直接手写消息列表，而是使用PromptTemplate来动态生成提示词。不过对于Agent场景来说，LangChain已经内置了提示词模板，无需手动拼接。但理解底层消息结构仍然很有帮助，因为Agent执行过程中产生的所有中间步骤（思考、动作、观察）都会以消息的形式在内部流转。
定义工具并构建Agent执行器
Agent的核心价值在于能够调用外部工具。LangChain中定义一个工具非常简单，使用@tool装饰器即可把普通Python函数包装成工具对象。工具函数需要包含类型注解和文档字符串，这些信息会告诉模型该工具的功能、参数类型以及使用场景，直接影响模型调用工具的准确性。下面定义两个简单工具：一个用于获取当前时间，另一个用于将文本转换为大写。
from langchain_core.tools import tool
from datetime import datetime
@tool
def get_current_time() -> str:
"""返回当前的日期和时间，格式为 YYYY-MM-DD HH:MM:SS。"""
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
@tool
def uppercase_text(text: str) -> str:
"""将输入的文本转换为大写形式。"""
return text.upper()
# 将工具放入列表
tools = [get_current_time, uppercase_text]
创建好工具列表后，需要使用create_openai_tools_agent函数将聊天模型和工具绑定生成一个Agent。这个函数会返回一个Runnable对象，它已经包含了系统提示词、工具调用格式等逻辑。然后将其传入AgentExecutor，由执行器负责整个Agent循环的管理，包括解析模型输出、执行工具、把观察结果反馈给模型等。
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
# 创建Agent的提示词模板
prompt = ChatPromptTemplate.from_messages(
[
("system", "你是一个乐于助人的AI助手，可以使用提供的工具来回答问题。"),
("human", "{input}"),
("placeholder", "{agent_scratchpad}"),
]
)
# 创建Agent
agent = create_openai_tools_agent(llm, tools, prompt)
# 创建执行器
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 运行Agent
result = agent_executor.invoke({"input": "现在几点了？请把回答转换成大写再输出"})
print(result["output"])
执行上述代码时，verbose=True会在控制台打印详细的执行轨迹，你可以清楚地看到Agent的思考过程：它先判断需要调用get_current_time工具，得到返回的时间字符串，然后决定再调用uppercase_text工具对时间进行大写转换，最后输出最终结果。这个循环被称为Thought-Action-Observation，理解它对调试Agent至关重要。
为Agent添加多轮对话记忆
默认情况下，AgentExecutor每次调用都是无状态的，不会记住之前的对话内容。要实现多轮对话，需要引入记忆组件。LangChain提供了多种记忆策略，其中ConversationBufferMemory最简单，它会把所有历史消息存储在一个缓冲区中，每次调用时自动附加到提示词里。不过对于Agent而言，由于内部已经管理了中间步骤的消息，直接使用RunnableWithMessageHistory往往更加灵活。
下面示例演示如何为Agent添加基于ChatMessageHistory的持久化记忆。我们使用一个简单的字典来模拟会话存储，每个会话ID对应一个历史记录对象。这样同一个会话ID的多次调用可以共享上下文。
from langchain_core.chat_history import InMemoryChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory
# 用字典存储每个会话的历史记录
store = {}
def get_session_history(session_id: str):
if session_id not in store:
store[session_id] = InMemoryChatMessageHistory()
return store[session_id]
# 包装Agent执行器
with_memory = RunnableWithMessageHistory(
agent_executor,
get_session_history,
input_messages_key="input",
history_messages_key="chat_history",
)
# 第一次调用
response1 = with_memory.invoke(
{"input": "我的名字是张三，请记住。"},
config={"configurable": {"session_id": "user-001"}}
)
print(response1["output"])
# 第二次调用，测试是否记住了名字
response2 = with_memory.invoke(
{"input": "我叫什么名字？"},
config={"configurable": {"session_id": "user-001"}}
)
print(response2["output"])
在上面的代码中，input_messages_key指定了用户输入在输入字典中的键名，history_messages_key指定了历史消息在提示词中的占位键名。包装后的with_memory对象每次调用时需要传入config参数来指定会话ID。实际项目中，你可以将会话ID存储在数据库或Redis中，实现真正的持久化。
需要注意的是，多轮对话记忆并不是越多越好。过长的历史会迅速增加Token消耗，甚至超出模型的上下文窗口。对于生产环境，建议使用摘要记忆或窗口记忆来限制历史长度。LangChain提供了ConversationSummaryBufferMemory等更高级的记忆类，可以根据需要选用。
调试与常见问题
构建第一个Agent时，你可能会遇到模型反复调用同一个工具却不收敛、工具参数解析错误、或者Agent输出格式不符合预期等问题。这些大部分可以通过调整提示词、限制最大迭代次数、或者更换更强大的模型来解决。LangChain的AgentExecutor默认设置了max_iterations=15，如果回合数超过该值会抛出异常，这在调试阶段非常有用。
另一个常见的坑是工具函数的文档字符串写得太模糊。模型依赖文档字符串来理解工具用途和参数含义，如果描述不准确，模型很可能调用错误的工具或传入错误的参数。建议在每个工具函数中明确写出参数类型、返回值格式以及使用场景的完整句子。例如上面的get_current_time工具就明确写了返回格式为YYYY-MM-DD HH:MM:SS，这能大大减少解析错误。
# 错误示例：文档字符串过于简单，模型无法准确判断用途
@tool
def do_something(x: str) -> str:
"""处理一些东西。"""
return x
# 正确示例：详细描述输入输出和用途
@tool
def format_username(name: str) -> str:
"""将用户输入的姓名格式化为首字母大写，其余字母小写。
参数 name 是包含姓名的字符串，可能包含空格。
返回格式化后的姓名字符串。
"""
return name.title()
如果Agent在执行过程中出现无限循环，可以先尝试降低temperature参数到0或接近0，让模型输出更加确定。同时确保每个工具都有明确的终止条件或返回值，不要让工具返回空字符串或None，这会让模型感到困惑。另外，打开verbose=True查看完整的中间步骤，是定位问题的最直接方式。
通过本教程，你已经完成了一个能够自主调用工具的Chat Agent。虽然示例中的工具很简单，但同样的模式可以扩展到查询数据库、发送HTTP请求、操作文件系统等真实场景。LangChain的生态还支持集成几百种现成的工具，也可以使用LangGraph构建更复杂的多Agent协作系统。建议在熟悉基础流程后，尝试为自己常用的API封装成工具，让Agent真正成为你的日常效率助手。
LangChainChat AgentAI智能体修改时间：2026-08-20 18:15:23