核心组件#

图：Agent 的完整架构——中间的智能体（Agent）连着工具（日历/计算器/代码解释器/搜索…）、记忆（短期记忆 + 长期记忆向量数据库）、行动与规划决策（反思/自我批评/思维链/子目标分解），外面还可以挂别的智能体

方式一：传模型字符串#

Agent 根据字符串自己创建模型对象：

1
from langchain.agents import create_agent
2
from dotenv import load_dotenv
3

4
load_dotenv(override=True)
5

6
agent = create_agent("deepseek-v4-flash")
7
print(type(agent))     # <class 'langgraph.graph.state.CompiledStateGraph'>

方式二：传模型对象#

先自己把模型建好（能精确控制 api_key、base_url 等参数），再交给 Agent：

1
from langchain.chat_models import init_chat_model
2
from langchain.agents import create_agent
3
from langchain_deepseek import ChatDeepSeek
4
from dotenv import load_dotenv
5
import os
6

7
load_dotenv(override=True)
8

9
# 以 ChatDeepSeek 为例
10
# model = ChatDeepSeek(model="deepseek-v4-flash")
11

12
# 以 init_chat_model 为例
13
model = init_chat_model(
14
    model="deepseek-v4-flash",
15
    model_provider="openai",
16
    api_key=os.getenv("DEEPSEEK_API_KEY"),
17
    base_url=os.getenv("DEEPSEEK_BASE_URL"),
18
)
19

20
agent = create_agent(model)
21
print(type(agent))     # 同上，也是 CompiledStateGraph

1
from IPython.display import Image, display
2
display(Image(agent.get_graph().draw_mermaid_png()))

图：draw_mermaid_png() 画出来的 agent 图结构——上面这张是没挂工具时的样子（__start__ → model → __end__），下一篇挂上工具就会多出 tools 节点

日常开发推荐方式二：只有传对象才能显式指定 base_url、api_key 等参数（第 04 篇踩过的坑）。

一次 invoke 的完整输出长什么样#

课程里用 rich 的 rprint 把返回的字典整个打印出来，结构一览无余（print 也行，但 rprint 会着色、换行更好看）：

1
from rich import print as rprint
2

3
response = agent.invoke({"messages": ["你好"]})     # 默认是 HumanMessage
4
print(type(response))     # <class 'dict'>
5
rprint(response)

输出（只保留关键字段，省略号是省略掉的部分）：

1
{
2
 'messages': [
3
   HumanMessage(
4
     content='你好',
5
     additional_kwargs={},
6
     response_metadata={},       # 用户消息没有这些元数据
7
     id='93ffcb22-179a-4cab-81a7-a3bd3a1795d4'
8
   ),
9
   AIMessage(
10
     content='你好！有什么我可以帮你的吗？',
11
     additional_kwargs={'refusal': None},
12
     response_metadata={
13
       'token_usage': {                    # ← 厂商返回的原始用量
14
         'completion_tokens': 13,
15
         'prompt_tokens': 7,
16
         'total_tokens': 20,
17
         'completion_tokens_details': {...},
18
         'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0},
19
         'latency_checkpoint': {           # ← 延迟指标（下面单独讲）
20
           'engine_tbt_ms': 3,             # 引擎侧每 token 平均耗时
21
           'engine_ttft_ms': 48,           # 引擎侧首 token 时间
22
           'engine_ttlt_ms': 90,           # 引擎侧整段输出总耗时
23
           'pre_inference_ms': 95,         # 进入推理前的排队/预处理耗时
24
           'service_tbt_ms': 4,            # 服务侧每 token 平均耗时
25
           'service_ttft_ms': 673,         # 服务侧首 token 时间
26
           'service_ttlt_ms': 712,         # 服务侧总耗时
27
           'total_duration_ms': 626,
28
           'user_visible_ttft_ms': 578,    # 用户真正看到第一个字的延迟 ← 最该看这个
29
         }
30
       },
31
       'model_provider': 'openai',
32
       'model_name': 'gpt-5.4-mini-2026-03-17',   # 实际落到哪个模型版本
33
       'system_fingerprint': None,
34
       'id': 'chatcmpl-DlUJdEGrlJtKPHQ9wgdp1KsrEjIDc',
35
       'service_tier': 'default',
36
       'finish_reason': 'stop',          # 'stop' = 说完了；'tool_calls' = 要去调工具
37
       'logprobs': None
38
     },
39
     id='lc_run--019e7ccd-c08b-7f60-8b07-32324cccf2c2-0',
40
     tool_calls=[],                      # 没调工具，所以是空列表
41
     invalid_tool_calls=[],
42
     usage_metadata={                    # ← LangChain 统一命名后的用量
43
       'input_tokens': 7,
44
       'output_tokens': 13,
45
       'total_tokens': 20,
46
       'input_token_details': {'audio': 0, 'cache_read': 0},
47
       'output_token_details': {'audio': 0, 'reasoning': 0}
48
     }
49
   )
50
 ]
51
}

延迟指标分三个”视角”（引擎 → 服务 → 用户），另外还有几个配套的耗时项：

一、知识回顾（读完直接做下面的实践题）#

1. 智能体 = 以大语言模型（LLM）为推理与决策核心，结合记忆、工具调用与环境交互能力，能够进行规划决策并执行复杂任务以达成目标的软件系统
2. 智能体的四个核心组件里，必须的是行动（Action），几乎总是存在的是工具（Tool）（行动的具体手段），有条件存在的是规划决策，最容易被省略的是记忆（Memory）；最小的 Agent 就是”模型 + 一个工具”
3. 课程给的定位：通用人工智能（AGI）是 AI 的终极形态，而**构建智能体（Agent）**是 AI 工程应用当下的”终极形态”
4. v0.x 的三个问题是心智负担高、可组合性差、生态碎片化；v1.x 把 Agent 的创建统一到一个入口 create_agent()，底层靠**中间件（Middleware）**机制和标准模型接口实现全局统一
5. create_agent 的两个必需参数是 model 和 tools；系统提示词用 system_prompt 传，中间件用 middleware，Agent 名字用 name，调试图结构还有 response_format、interrupt_before / interrupt_after、debug 等可选参数
6. 模型有两种传入方式：直接传模型名字符串，或传模型对象；不管哪种方式，得到的 agent 都是 LangGraph 的 CompiledStateGraph 实例——说明 Agent 底层是一张图
7. 不挂工具时图结构的节点是 __start__ → model → __end__，挂上工具后会多出一个 tools 节点；想亲眼看可以调用 agent.get_graph().draw_mermaid_png()
8. agent.invoke() 的输入是字典、消息列表放在 messages 字段里；直接写字符串会被当成 HumanMessage 消息；返回的也是字典，它的 messages 是完整的消息列表（可能含多轮交互），最终回答通常取 response["messages"][-1]
9. 发起工具调用时 AIMessage.content 是空字符串（''）；tool_calls 为空列表说明没有要调用的工具；finish_reason 为 'stop' 表示说完了、为 'tool_calls' 表示还要去调工具；想知道”是不是被换了模型”看 response_metadata 里的 model_name
10. 用量有两个口径：response_metadata['token_usage'] 是**厂商（模型服务商）**返回的原始用量，usage_metadata 是 LangChain 归一化后的用量（input_tokens / output_tokens / total_tokens）；想写”跨平台都能跑”的代码要优先读后者，因为延迟指标（如 latency_checkpoint）换平台不一定有

二、裸写题#

• 2-1 用模型名字符串创建第一个 Agent 只给一个模型名（如 deepseek-v4-flash）就创建出 Agent，打印它的类型；然后问一句”你好”，取出最后一条消息的正文打印出来。记得先把 .env 读进来，否则密钥读不到。

  提示（先自己想，实在想不出再点开）

  一级 · 思路：字符串方式最省事——框架根据名字自己去建模型对象，但也就没法精细控制接口地址 二级 · 方法：agent = create_agent("deepseek-v4-flash") + agent.invoke({"messages": ["你好"]}) 三级 · 骨架：打印类型看是不是 CompiledStateGraph；取回答用 response["messages"][-1].content

• 2-2 传模型对象，并带上 system 消息 自己先把模型建好（要能显式指定密钥和接口地址），再交给 Agent；调用时在消息列表开头加一条 system 消息定人设（比如”你是一个小学数学老师，耐心，幽默，讲解深入浅出”），再问一个问题，观察回答风格的差别。

  提示（先自己想，实在想不出再点开）

  一级 · 思路：system 消息用来”定人设”，放在消息列表第一条；日常开发推荐传对象（能精确控制参数） 二级 · 方法：init_chat_model(model=..., model_provider="openai", api_key=..., base_url=...) + create_agent(model=model) 三级 · 骨架：{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}]}

• 2-3 把返回的消息流打印清楚 调用一次 Agent 后遍历返回的消息列表，打印每条消息的类型（HumanMessage / AIMessage / ToolMessage）和内容；再单独打印最后一条的正文和令牌用量。

  提示（先自己想，实在想不出再点开）

  一级 · 思路：Agent 的返回是”全过程记录”，先看清有几条、分别是什么类型 二级 · 方法：for msg in resp["messages"]: print(type(msg).__name__, msg.content) 三级 · 骨架：最后一条的令牌用量在 msg.usage_metadata；消息对象还有 pretty_print() 可以打印得更漂亮

• 2-4 读一次 invoke 的完整元数据 打印一次调用返回的最后一条消息上的：结束原因、实际命中的模型版本、厂商的原始令牌用量、归一化后的令牌用量、这一轮的工具调用计划；并说明”延迟指标”里最该关注哪一项、为什么它换平台可能没有。

  提示（先自己想，实在想不出再点开）

  一级 · 思路：这些元数据都在消息对象的 response_metadata 里；用量还有一个”更通用”的版本 二级 · 方法：meta = last.response_metadata → meta["finish_reason"] / meta["model_name"] / meta["token_usage"] / meta["latency_checkpoint"]；last.usage_metadata 三级 · 骨架：延迟指标看 user_visible_ttft_ms（用户真正看到第一个字的延迟）；跨平台代码优先读 usage_metadata

1
import os
2

3
from dotenv import load_dotenv
4
from langchain.agents import create_agent
5
from langchain.chat_models import init_chat_model
6

7
load_dotenv(override=True)
8

9
# ---------- 2-1 用模型名字符串创建 ----------
10
agent = create_agent("deepseek-v4-flash")
11
print(type(agent))       # <class 'langgraph.graph.state.CompiledStateGraph'>
12

13
response = agent.invoke({"messages": ["你好"]})
14
print(response["messages"][-1].content)
15

16
# ---------- 2-2 传模型对象 + 内联 system 消息 ----------
17
model = init_chat_model(
18
    model="deepseek-v4-flash",
19
    model_provider="openai",
20
    api_key=os.getenv("DEEPSEEK_API_KEY"),
21
    base_url=os.getenv("DEEPSEEK_BASE_URL"),
22
)
23

24
agent2 = create_agent(model=model)
25
resp = agent2.invoke({
26
    "messages": [
27
        {"role": "system", "content": "你是一个小学数学老师，耐心，幽默，讲解深入浅出"},
28
        {"role": "user", "content": "3 个苹果分给 2 个人怎么分？"},
29
    ]
30
})
31

32
# ---------- 2-3 把返回的消息流打印清楚 ----------
33
for msg in resp["messages"]:
34
    print(type(msg).__name__, "→", msg.content[:50])
35
# SystemMessage  → 你是一个小学数学老师，耐心，幽默，讲解深入浅出
36
# HumanMessage   → 3 个苹果分给 2 个人怎么分？
37
# AIMessage      → （最终回答）
38

39
last = resp["messages"][-1]
40
print("最终回答:", last.content)
41
print("token 用量:", last.usage_metadata)
42
# 更漂亮地打印：for msg in resp["messages"]: msg.pretty_print()
43

44
# ---------- 2-4 一次 invoke 的完整输出 ----------
45
meta = last.response_metadata
46
print("finish_reason:", meta.get("finish_reason"))      # 'stop' 说完了；'tool_calls' 还要调工具
47
print("model_name:", meta.get("model_name"))            # 实际命中的模型版本
48
print("token_usage:", meta.get("token_usage"))          # 厂商原始用量（命名不一定统一）
49
print("latency_checkpoint:", meta.get("latency_checkpoint"))   # 各家网关的延迟指标，换平台不一定有
50
print("usage_metadata:", last.usage_metadata)           # 归一化后的用量：跨平台优先读它
51
print("tool_calls:", last.tool_calls)                   # 空列表 = 没有要调的工具
52
print("图结构节点:", [n for n in agent.get_graph().nodes])
53
# ['__start__', 'model', '__end__']   ← 这就是"模型想 → 用工具 → 再想 → 再答"的循环骨架