学完 AI Agent 基础概念,接下来最重要的一步,就是自己动手做一个 Agent。这篇文章就是带你”从零到一”——跟着走,30 分钟后你会有一个真正能干活的 Agent,会查数据库、能查天气、能记住对话、能自主决定下一步该做什么。

我们用 LangGraph。这个框架在 2026 年已经是 Agent 开发的首选——它比 LangChain Agent 更灵活,比 AutoGen 更稳定,比 CrewAI 更适合做”会干活”的 Agent。Cursor、Anthropic 内部、阿里通义、字节扣子团队都在用它做核心 Agent 框架。

跟随本文,你需要准备:

  • 基本的 Python 语法(变量、函数、import)
  • 一个 LLM API key(OpenAI、Anthropic、DeepSeek 都可以)
  • 一台能联网的电脑

不需要懂高级 AI 概念,跟着敲就行。

一、为什么选 LangGraph

先说一个直觉:既然 LangChain、AutoGen、CrewAI 这些 Agent 框架都”能用”,为什么选 LangGraph?

简单对比三种主流框架:

框架 适合场景 上手难度 控制粒度
LangGraph 生产级、复杂决策流 中 细(节点-边可控)
AutoGen 多 Agent 对话、协作 中低 中
CrewAI 角色化分工的任务 低 粗

LangGraph 的核心优势是”控制粒度”——它把 Agent 抽象成”图”(Graph),每个节点是一个动作(调 LLM、执行工具、判断分支),节点之间的边定义执行顺序。这种结构让你能精确控制 Agent 的每一步,适合做生产级 Agent。

2026 年的事实是:90% 的企业级 Agent 都是用 LangGraph 做的。从 OpenAI 内部工具到阿里百炼 Agent,从字节扣子到 Cursor 的部分功能,背后都用 LangGraph 这种”图式 Agent 框架”。

所以学 LangGraph 不会浪费——它是 2026 年最值得学的 Agent 框架。

二、环境准备:5 分钟搞定

步骤 1:装 Python(已有跳过)

确保你有 Python 3.10+。如果是 macOS/Linux 通常已经预装,Windows 用户推荐装 Anaconda 或 miniconda。

python –version # 应该输出 3.10 或更高

步骤 2:建虚拟环境

mkdir my-first-agent && cd my-first-agent
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate

步骤 3:装依赖

pip install langgraph langchain-anthropic python-dotenv tavily-python

依赖说明:

  • langgraph:Agent 图框架
  • langchain-anthropic:Claude 模型集成(也支持 OpenAI,这里以 Anthropic 为例)
  • python-dotenv:读 .env 文件(存 API key)
  • tavily-python:Web 搜索工具(后面会用到)

步骤 4:配 API key

在项目根目录新建 .env 文件:

ANTHROPIC_API_KEY=sk-ant-你的key
TAVILY_API_KEY=tvly-你的key

Tavily 是 AI 专用的搜索 API,免费版每月 1000 次查询,够用。注册:[tavily.com](https://tavily.com)

到这里环境就准备好了。整个流程 5 分钟左右。

三、最简单的 Agent:10 行代码跑通

我们先写一个最最最简单的 Agent——能用 web 搜索回答问题。

新建 simple_agent.py:

from langgraph.prebuilt import create_react_agent
from langchain_anthropic import ChatAnthropic
from langchain_community.tools.tavily_search import TavilySearchResults
from dotenv import load_dotenv

load_dotenv()

# 1. 准备模型
model = ChatAnthropic(model="claude-sonnet-4-6")

# 2. 准备工具
tools = [TavilySearchResults()]

# 3. 创建 Agent
agent = create_react_agent(model, tools)

# 4. 运行 Agent
result = agent.invoke({
"messages": [("user", "2026 年最火的 AI Agent 框架有哪些?")]
})

# 5. 输出结果
print(result["messages"][-1].content)

跑一下:

python simple_agent.py

Agent 会:

  1. 思考”我需要查最新信息”
  2. 调用 Tavily 搜索工具
  3. 拿到搜索结果
  4. 整理答案
  5. 输出给你

你不需要写循环、不需要写工具调度逻辑、不需要写错误处理——LangGraph 的 create_react_agent 帮你搞定一切。

这就是你第一个能”查信息”的 Agent。

四、加工具:让 Agent 能干多件事

简单的 Agent 只会搜索。我们加几个工具,让它能做事更多。

添加工具函数

from langchain.tools import tool

@tool
def get_weather(city: str) -> str:
"""查询指定城市的实时天气"""
# 这里用真实 API,这里用 mock 数据演示
return f"{city} 当前天气晴,温度 25°C,湿度 45%"

@tool
def calculate(expression: str) -> str:
"""执行数学计算,输入格式如 '2 + 3 * 4'"""
try:
result = eval(expression)
return f"计算结果: {result}"
except Exception as e:
return f"计算错误: {e}"

@tool
def get_current_time() -> str:
"""获取当前时间"""
from datetime import datetime
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

tools = [TavilySearchResults(), get_weather, calculate, get_current_time]

把工具给 Agent

agent = create_react_agent(model, tools)

测试

questions = [
"北京天气怎么样?",
"12345 乘以 67890 等于多少?",
"现在几点了?",
"2026 年有哪些新的 AI 模型发布?",
]

for q in questions:
print(f"\n问: {q}")
result = agent.invoke({"messages": [("user", q)]})
print(f"答: {result['messages'][-1].content}")

你会看到 Agent 自动判断该用哪个工具——问天气用天气工具,问计算用计算工具,问时间用时间工具,问最新信息用搜索工具。

这就是 ReAct(Reason + Act)模式——Agent 先”思考”该用什么,然后”执行”对应动作。LangGraph 帮你处理整个循环。

五、加记忆:让 Agent 能记住对话

现在的 Agent 每次调用都是”无状态”的——它不记得上次聊了什么。如果你想让 Agent 记住对话上下文,需要加记忆机制。

短期记忆(In-Memory)

from langgraph.checkpoint.memory import MemorySaver

memory = MemorySaver()
agent = create_react_agent(model, tools, checkpointer=memory)

# 用 thread_id 标识一个对话
config = {"configurable": {"thread_id": "user-001"}}

# 第一轮
result = agent.invoke(
{"messages": [("user", "我叫张三,我在北京")]},
config=config,
)
print(result["messages"][-1].content)
# 输出: "你好张三!很高兴认识你…"

# 第二轮(同一 thread_id,Agent 记得上下文)
result = agent.invoke(
{"messages": [("user", "我所在的城市今天天气怎么样?")]},
config=config,
)
print(result["messages"][-1].content)
# 输出: (调用 get_weather tool, 查北京天气)

这就是短期记忆——同一个 thread_id 的对话,Agent 都记得。这种机制适合多轮对话场景。

长期记忆(Persistent)

短期记忆在程序重启后会丢失。如果要做”长期记忆”(跨进程、跨设备),需要把记忆存到外部:

from langgraph.checkpoint.postgres import PostgresSaver

# 需要 PostgreSQL 数据库
DB_URI = "postgresql://user:pass@localhost:5432/agent_memory"
memory = PostgresSaver.from_conn_string(DB_URI)

agent = create_react_agent(model, tools, checkpointer=memory)

这样 Agent 的记忆会持久化到数据库,即使程序重启了,也能恢复上下文。

记忆机制是 Agent 区别于”单次 LLM 调用”的关键能力。一个有记忆的 Agent 能做对话式客服、个人助理、长期陪伴等场景。

六、加决策回路:让 Agent 能自主决策

更高级的 Agent 需要自己”决策”——比如”先查 A,根据结果决定要不要查 B”,或者”如果失败了就重试”。

LangGraph 的核心优势就是”图式结构”,能精确控制这种决策流。

示例:分级判断的 Agent

from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from typing import Annotated, TypedDict
from langchain_anthropic import ChatAnthropic
from langchain.tools import tool

# 1. 定义状态
class State(TypedDict):
messages: Annotated[list, add_messages]

# 2. 定义节点函数
def agent_node(state: State):
"""Agent 思考节点"""
response = model.invoke(state["messages"])
return {"messages": [response]}

def should_continue(state: State) -> str:
"""判断是否继续"""
last_message = state["messages"][-1]
# 如果 LLM 决定调用工具,继续到工具节点
if last_message.tool_calls:
return "tools"
# 否则结束
return END

# 3. 定义工具节点
from langgraph.prebuilt import ToolNode
tools_node = ToolNode(tools)

# 4. 构建图
graph = StateGraph(State)
graph.add_node("agent", agent_node)
graph.add_node("tools", tools_node)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", should_continue)
graph.add_edge("tools", "agent")

agent = graph.compile()

这样 Agent 的执行流是:

START → agent → (判断) → tools → agent → (判断) → … → END

Agent 每次”思考”后,会判断:

  • 该调用工具 → 跳到 tools 节点执行
  • 任务完成 → 跳到 END 结束

这种”图式 Agent”的好处是:

  • 可控性强:每个节点的逻辑都可审计
  • 可加复杂分支:比如”如果工具失败,重试 N 次”或”如果超出预算,转人工”
  • 可加并行节点:某些工具可以并行执行,加速流程

这是简单 ReAct Agent 做不到的。LangGraph 的真正威力,就在这种”图式”建模上。

七、完整实战:做一个天气查询 + 旅行规划 Agent

理论够了,我们来个综合实战。做一个完整的 Agent——能查天气 + 查火车票 + 帮你规划行程。

项目结构

my-first-agent/
├── .env
├── agent.py
├── tools.py
└── main.py

tools.py:工具定义

from langchain.tools import tool
import requests

@tool
def get_weather(city: str) -> str:
"""查询指定城市的实时天气"""
# 真实 API 调用,这里用 mock
return f"{city}: 晴,25°C,适合出行"

@tool
def search_train_tickets(from_city: str, to_city: str, date: str) -> str:
"""查询火车票信息,from_city 出发城市,to_city 到达城市,date 日期 YYYY-MM-DD"""
# 真实 API:12306 等,这里用 mock
return f"{from_city} → {to_city} {date}: G101 09:00-13:30,二等座 ¥553,余票 12 张"

@tool
def search_attractions(city: str) -> str:
"""查询城市的热门景点"""
return f"{city} 热门景点:故宫(¥60)、颐和园(¥30)、长城(¥45)、天坛(¥35)"

@tool
def calculate_budget(days: int, daily_cost: int) -> str:
"""计算旅行预算,days 天数,daily_cost 每天花费"""
total = days * daily_cost
return f"总计预算: ¥{total}({days}天 × 每天¥{daily_cost})"

tools = [get_weather, search_train_tickets, search_attractions, calculate_budget]

agent.py:Agent 定义

from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver
from langchain_anthropic import ChatAnthropic
from tools import tools
from dotenv import load_dotenv

load_dotenv()

model = ChatAnthropic(model="claude-sonnet-4-6")
memory = MemorySaver()
agent = create_react_agent(model, tools, checkpointer=memory)

main.py:运行 Agent

from agent import agent

config = {"configurable": {"thread_id": "user-001"}}

def chat(question: str):
result = agent.invoke(
{"messages": [("user", question)]},
config=config,
)
return result["messages"][-1].content

if __name__ == "__main__":
# 多轮对话测试
questions = [
"我想从北京去上海玩 3 天",
"帮我查一下北京现在的天气",
"3 天旅行,每天预算 800 元,总共多少?",
"上海有什么热门景点?",
]

for q in questions:
print(f"\n👤 {q}")
print(f"🤖 {chat(q)}")

跑 python main.py,你会看到一个完整的”旅行规划 Agent”运行——它会自己组合多个工具,完成一个看似复杂的任务。

八、调试技巧:让 Agent 跑得更好

写完第一个 Agent 后,你大概率会遇到这些问题,提前知道能省很多时间:

问题 1:Agent 死循环

症状:Agent 一直调用同一个工具不停
原因:工具结果没让 Agent “满意”,或者 prompt 没明确”什么时候该停止”
修复:在工具描述里说清楚何时调用、何时停止,比如”调用 1 次就够,不要重复”

问题 2:Agent 选错工具

症状:Agent 调了不相关的工具
原因:工具描述太模糊,或者工具有重叠功能
修复:让工具描述具体、互斥,例如”get_weather:只查实时天气,不查历史”

问题 3:Agent 上下文太长

症状:Agent 跑到一半,质量明显下降,出现幻觉
原因:消息历史太长,把不相关的也塞进去了
修复:用 messages[-10:] 只保留最近 10 条,或者用 LangGraph 的 trim_messages 函数

问题 4:工具调用失败

症状:Agent 卡在 “tool error” 状态
原因:工具 API 报错、超时、限流
修复:加重试机制(用 LangGraph 的 RetryPolicy),或者加 fallback 工具

问题 5:Agent 行为不一致

症状:同样输入,有时 Agent 给的答案不一样
原因:LLM 本身的随机性 + 工具组合的可能分支太多
修复:

  • 加 temperature=0 降低随机性
  • 把 Agent 的核心指令写得更明确
  • 加评估测试,跑大量输入验证一致性

调通这些基本技巧,你的 Agent 就能稳定干活了。

九、下一步

到这里你已经能用 LangGraph 搭建”能干活”的 Agent 了。接下来的几个方向:

方向 1:接入真实工具(MCP)

把上节学的 MCP 用上,给你的 Agent 接更多工具(数据库、GitHub、Slack、浏览器)。配合使用,Agent 能力几何级增长。

方向 2:多 Agent 协作

LangGraph 也支持多 Agent 编排。你可以做一个”主 Agent + 专家 Agent”架构:

  • 主 Agent 接收任务、分发
  • 专家 Agent 各自处理特定领域
  • 主 Agent 汇总结果

这是 2026 年企业级 Agent 的标准架构。

方向 3:生产化部署

把 Agent 部署到生产环境,你需要补:

  • 错误处理 + 重试机制
  • 监控 + 日志(用 LangSmith)
  • 性能优化(缓存、并行、降级)
  • 安全 + 权限控制

方向 4:评估测试

用 LangSmith 或自建评估框架,跑 100+ 测试用例验证 Agent 行为:

  • 准确性(回答对不对)
  • 一致性(同样输入,输出是否稳定)
  • 性能(响应时间、成本)

评估过 Agent 的能力边界后,你才能放心用在生产。

推荐路径

  • 想接更多工具:看本系列《MCP 实战:给 Agent 接上 GitHub / 数据库 / 浏览器》
  • 想用好 Agent:看《Harness Engineering 深度:从 OpenAI 100 万行实践看 Agent 工业化》
  • 想理解 Agent 是什么:看《AI Agent 到底是什么?2026 年最值得搞懂的 5 个核心概念》

最后一句话:第一篇 AI Agent 代码,一定不会完美。但做出来比做完美更重要。先做出一个能跑的 Agent,再慢慢迭代优化。

30 分钟前你还是一个”Agent 入门者”,现在你已经能搭出一个有工具、有记忆、有决策流的完整 Agent。这种跃迁,只有动手做才能完成。

(综合 LangGraph 官方文档、Anthropic Claude API 文档、实战项目代码整理)

写在最后:从”能跑”到”生产”,Agent 项目的 3 个里程碑

从”能跑通 LangGraph Agent”到”能用于生产环境”,中间隔着 3 个里程碑。新手学 Agent 最容易在这个过渡中迷路,所以最后专门说一下。

里程碑 1:能跑通 demo(1-2 天)

你刚写完的 Agent,能完成单一任务就 OK。能在自己电脑上跑通、回答 5-10 个测试问题、偶尔出错没关系——这就过了第一关。掌握 LangGraph 基础语法、工具调用机制、最简单的图式结构,这是 80% 新手都达不到的水平。

里程碑 2:能稳定运行(2-4 周)

让 Agent 在 100 个真实用户对话里稳定运行,达到 95%+ 的成功率,这是第二关。这一阶段的关键不是写新代码,而是:

  • 完善错误处理和重试机制
  • 加监控和日志(LangSmith 必须用)
  • 写评估测试用例,持续回归验证
  • 优化 prompt 和工具描述,提升准确性
  • 处理边界情况(空输入、超长输入、并发请求)

这一关的核心不是”写代码”,而是”练内功”——调优 Agent 是个细心活,需要你反复看日志、反复迭代。着急冒进没用,耐心最重要。

里程碑 3:能规模化运行(2-3 个月)

让你的 Agent 每天能跑 10000+ 次对话,同时把成本控制在合理范围内,这是第三关。这一阶段要解决:

  • 性能优化(缓存、并行、批处理)
  • 成本控制(用更便宜的模型处理简单任务,贵的模型处理复杂任务)
  • 多 Agent 协作(主 Agent + 专家 Agent 架构)
  • 可观测性(指标、告警、链路追踪)
  • 安全合规(权限控制、审计日志、数据脱敏)

这一关的核心是”工程化”——把 Agent 当成一个真实的产品做,而不是 demo。这一步通常需要团队协作,而不是个人单打独斗。

三个里程碑预计耗时 1-3 个月。走完这段路,你就是 2026 年最稀缺的”Agent 工程师”——不是”会用 Agent 的人”,而是”能搭生产级 Agent 的人”。这个身份在 AI 时代,比单纯会写代码值钱得多。

小例子:用 Agent 写一份个人周报生成器

理论讲完,最后用一个完整小例子走通一遍——帮助你理解”3 个工具 + 记忆 + 决策”的组合用法。

这个项目叫”个人周报生成器”。它能问你这周做了什么、做了什么决定,自动生成一份发给老板的周报。

项目需求

  • 读取你这周提交的 git commit
  • 根据 commit 信息,辅助你填写周报内容
  • 调用 LLM 调优周报语气
  • 输出最终周报到文件

完整代码

# weekly_report_agent.py
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver
from langchain_anthropic import ChatAnthropic
from langchain.tools import tool
from datetime import datetime, timedelta
import subprocess

@tool
def get_recent_commits(days: int = 7) -> str:
"""获取最近的 git commit 记录"""
try:
result = subprocess.run(
["git", "log", f"-{days}", "–oneline"],
capture_output=True, text=True, cwd="."
)
commits = result.stdout.strip()
if not commits:
return "最近没有 commit 记录"
return f"最近 {days} 天的 commit:\n{commits}"
except Exception as e:
return f"获取 commit 失败: {e}"

@tool
def get_current_week_range() -> str:
"""获取本周的日期范围(周一到周日)"""
today = datetime.now()
monday = today – timedelta(days=today.weekday())
sunday = monday + timedelta(days=6)
return f"{monday.strftime('%Y-%m-%d')} 到 {sunday.strftime('%Y-%m-%d')}"

@tool
def save_report(content: str) -> str:
"""保存周报到文件"""
today = datetime.now()
filename = f"weekly_report_{today.strftime('%Y%m%d')}.md"
with open(filename, "w", encoding="utf-8") as f:
f.write(content)
return f"周报已保存到 {filename}"

tools = [get_recent_commits, get_current_week_range, save_report]
model = ChatAnthropic(model="claude-sonnet-4-6")
memory = MemorySaver()
agent = create_react_agent(model, tools, checkpointer=memory)

# 运行
config = {"configurable": {"thread_id": "user-001"}}
result = agent.invoke(
{"messages": [("user", "帮我生成本周周报")]},
config=config,
)
print(result["messages"][-1].content)

跑这个 Agent,会自动:

  1. 查本周 commit
  2. 查本周日期范围
  3. 调用 LLM 生成周报内容
  4. 保存到文件

你会惊讶于 Agent 能做这么多事——但这一切只是对工具的组合调用,加上 LangGraph 自带的循环调度。

这个小例子虽然简单,但包含生产 Agent 的所有关键能力:工具调用、记忆、决策。如果你能举一反三 (把 git 命令换成任何 CLI、把 commit 换成任何数据源、把周报换成任何模板),你能能搭出任何 “读数据 → 用 LLM 处理 → 输出结果”的 Agent。

这种能力在 2026 年特別值钱——很多企业内部的 “信息同步类”工作 (报告生成、数据汇总、邮件骤递)都能用这种模式重做一遍。节省下来的人力成本是指数级的。

新手学 Agent 最容易在这个过渡中迷路,所以最后专门说一下。

里程碑 1:能跑通 demo(1-2 天)

你刚写完的 Agent,能完成单一任务就 OK。能在自己电脑上跑通、回答 5-10 个测试问题、偶尔出错没关系——这就过了第一关。掌握 LangGraph 基础语法、工具调用机制、最简单的图式结构,这是 80% 新手都达不到的水平。

里程碑 2:能稳定运行(2-4 周)

让 Agent 在 100 个真实用户对话里稳定运行,达到 95%+ 的成功率,这是第二关。这一阶段的关键不是写新代码,而是:

  • 完善错误处理和重试机制
  • 加监控和日志(LangSmith 必须用)
  • 写评估测试用例,持续回归验证
  • 优化 prompt 和工具描述,提升准确性
  • 处理边界情况(空输入、超长输入、并发请求)

这一关的核心不是”写代码”,而是”练内功”——调优 Agent 是个细心活,需要你反复看日志、反复迭代。着急冒进没用,耐心最重要。

里程碑 3:能规模化运行(2-3 个月)

让你的 Agent 每天能跑 10000+ 次对话,同时把成本控制在合理范围内,这是第三关。这一阶段要解决:

  • 性能优化(缓存、并行、批处理)
  • 成本控制(用更便宜的模型处理简单任务,贵的模型处理复杂任务)
  • 多 Agent 协作(主 Agent + 专家 Agent 架构)
  • 可观测性(指标、告警、链路追踪)
  • 安全合规(权限控制、审计日志、数据脱敏)

这一关的核心是”工程化”——把 Agent 当成一个真实的产品做,而不是 demo。这一步通常需要团队协作,而不是个人单打独斗。

三个里程碑预计耗时 1-3 个月。走完这段路,你就是 2026 年最稀缺的”Agent 工程师”——不是”会用 Agent 的人”,而是”能搭生产级 Agent 的人”。这个身份在 AI 时代,比单纯会写代码值钱得多。

最后一句话:Agent 写出来不难,难的是把它用到能放心交付给别人的程度。今天写完这个 demo 是起点,接下来 3 个月你要做的是反复打磨、迭代、验证。这种重复劳动很枯燥,但它是”高手”和”新手”的分水岭。

能跑通的 Agent 千篇一律,能稳定运行的 Agent 万里挑一。希望你 3 个月后,也能成为”万里挑一”的那个人。