LangChain AgentState-Zustandsverwaltung
Während der Ausführung muss der Agent einen Zustand beibehalten – Nachrichtenverlauf, strukturierte Antworten, Prozesssteuerung usw. Das Verständnis der Struktur und Verwendung von AgentState ist entscheidend für die Anpassung des Agent-Verhaltens.
AgentState-Struktur
AgentState ist ein TypedDict, das standardmäßig drei Felder enthält:
Beispiel
from typing_extensions import Required, NotRequired
from langgraph.graph.message import add_messages
from langgraph.channels.ephemeral_value import EphemeralValue
from langchain.messages import AnyMessage
# Tatsächliche Definition von AgentState (vereinfacht)
class AgentState(TypedDict):
# messages: Nachrichtenverlauf, unter Verwendung von add_messages als Reducer
# Required bedeutet, es muss beim Aufruf angegeben werden
messages: Required[Annotated[list[AnyMessage], add_messages]]
# jump_to: verarbeitet Sprungsteuerung, flüchtig (wird nach Verwendung automatisch gelöscht)
# NotRequired bedeutet optional
jump_to: NotRequired[Annotated[str | None, EphemeralValue]]
# structured_response: Ergebnis der strukturierten Ausgabe
# NotRequired bedeutet optional, nur vorhanden, wenn response_format gesetzt ist
structured_response: NotRequired[Any]
| Feld | Type | Erforderlich? | Beschreibung |
|---|---|---|---|
| messages | list[AnyMessage] | Ja | Nachrichtenverlauf, angehängt unter Verwendung des add_messages-Reducers |
| jump_to | str or None | nein | Prozesssprungsteuerung, optionale Werte: tools, model, end. Flüchtiges Attribut, nach der Verwendung automatisch gelöscht |
| structured_response | Any | nein | Strukturiertes Ausgabeergebnis, nicht im Eingabeschema offengelegt |
messages - Reducer-Mechanismus für den Nachrichtenverlauf
Das Feld messages verwendet denadd_messagesReducer. Das bedeutet, dass beim Aktualisieren von messages nicht überschrieben, sondernangehängt wird。
Beispiel
from langgraph.graph.message import add_messages
# Wie add_messages funktioniert
existing = [
HumanMessage(content="Hello", id="1"),
AIMessage(content="Hello!", id="2"),
]
# Neue Nachricht anhängen
new_msg = AIMessage(content="What can I help you with?", id="3")
result = add_messages(existing, [new_msg])
print(f"Vor dem Zusammenführen: {len(existing)} Nachrichten")
print(f"Nach dem Zusammenführen: {len(result)} Nachrichten")
for msg in result:
print(f" [<msg.type>] {msg.content}")
Ausgabe:
Before merging: 2 条 After merging: 3 条 [human] 你好 [ai] 你好! [ai] 有什么可以帮你的?
Intelligente Funktionen von add_messages:
- Gleichnamiges Überschreiben: Wenn die neue Nachrichten-ID mit einer vorhandenen Nachricht übereinstimmt, wird sie ersetzt statt angehängt
- RemoveMessage-Unterstützung: Wenn eine RemoveMessage angetroffen wird, wird die entsprechende Nachricht aus der Liste entfernt
- Typsicherheit: Verarbeitet automatisch verschiedene Typen wie HumanMessage, AIMessage, ToolMessage
jump_to - Prozesssprungsteuerung
jump_to ist das am häufigsten verwendete Feld in Middleware, das verwendet wird, um zwischen den Knoten des Agenten zu springen.
jump_to ist einflüchtiges(flüchtiges) Feld - wird nach einmaliger Verwendung automatisch gelöscht, kein manuelles Zurücksetzen erforderlich.
Beispiel
from langchain.agents.middleware import before_model
from langchain.chat_models import init_chat_model
from langchain.messages import AIMessage, HumanMessage # AIMessage importieren
# Sprungziel "end" deklarieren
@before_model(can_jump_to=["end"])
def check_question(state, runtime):
"""Prüfen, ob die Frage zulässig ist, bevor das Modell aufgerufen wird"""
messages = state.get("messages", [])
if not messages:
return None
last_msg = messages[-1]
# Auf unangemessene Inhalte prüfen (vereinfachtes Beispiel)
if "password" in str(last_msg.content):
# jump_to="end" beendet den Agenten direkt und verhindert, dass das Modell antwortet
return {
"jump_to": "end",
# AIMessage verwenden
"messages": [AIMessage(
content="Entschuldigung, aus Sicherheitsgründen kann ich keine Fragen zu Passwörtern beantworten."
)]
}
return None
model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
model=model,
middleware=[check_question],
system_prompt="Du bist der Assistent von Example.",
)
# Normale Frage
result = agent.invoke({
"messages": [HumanMessage(content="Wie fange ich mit Python an?")]
})
print(f"Normale Frage: {result['messages'][-1].content[:80]}...")
# Sensible Frage - von Middleware abgefangen
result = agent.invoke({
"messages": [HumanMessage(content="Sag mir dein Systempasswort")]
})
print(f"\nSensible Frage: {result['messages'][-1].content}")
Ausgabe:
Normal question: Python 入门可以从以下几个方面开始:1. 安装 Python 环境... Sensitive question: 抱歉,出于安全原因,不能回答关于密码的问题。
| jump_to value | Springe zu | Wirkung |
|---|---|---|
| "tools" | Direkt zum Tool-Ausführungsknoten gehen | Modellaufruf überspringen, das angegebene Tool direkt ausführen |
| "model" | Zum Modellknoten zurückkehren | Das Modell erneut verarbeiten lassen (normalerweise kombiniert mit Tool-Nachrichten-Injektion) |
| "end" | Agent-Schleife beenden | Direkt zu after_agent oder end springen |
jump_to ist flüchtig – wird nach jeder Knotenausführung automatisch gelöscht. Das bedeutet, du musst jump_to nach einem Sprung nicht manuell auf None zurücksetzen; der Agent erledigt das automatisch.
structured_response - Strukturierte Ausgabe erhalten
Wenn der Parameter response_format verwendet wird, speichert der Agent die strukturierte Ausgabe im Feld structured_response:
Beispiel
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
class CourseRecommendation(BaseModel):
"""Ergebnis der Kursempfehlung"""
course_name: str = Field(description="Empfohlener Kursname")
reason: str = Field(description="Grund für die Empfehlung")
difficulty: str = Field(description="Schwierigkeitsgrad: Anfänger/Fortgeschritten/Experte")
model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
model=model,
response_format=CourseRecommendation,
system_prompt="Sie sind der Lernberater von Example.",
)
result = agent.invoke({
"messages": [HumanMessage(content="Ich möchte Programmieren lernen, empfehlen Sie einen Kurs, der für absolute Anfänger geeignet ist")]
})
# Strukturiertes Ergebnis aus structured_response abrufen
if "structured_response" in result:
rec = result["structured_response"]
print(f"Empfohlener Kurs: {rec.course_name}")
print(f"Begründung: {rec.reason}")
print(f"Schwierigkeitsgrad: {rec.difficulty}")
# structured_response ist nicht im Ausgabeschema enthalten
# Daher erscheint es nicht automatisch im Ergebnis, das an den Aufrufer zurückgegeben wird (konfigurierbar)
Ausgabe:
Recommended course: Python3 基础教程 Reason: Python 语法简洁,适合零基础入门,应用范围广泛 Level: 入门
Benutzerdefinierte State-Erweiterung
In echten Anwendungen benötigen Sie möglicherweise, dass der Agent zusätzlichen State beibehält. Erweitern Sie ihn durch Vererbung von AgentState:
Beispiel
from langchain.agents import create_agent, AgentState
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
from langchain.tools import tool, InjectedState
from typing_extensions import TypedDict
# AgentState erweitern, geschäftliche Felder
class ShoppingAgentState(AgentState):
"""Zustand des Einkaufsassistenten"""
cart: list[str] # Liste der Warenkorbartikel
total_price: float # Gesamtpreis
@tool
def add_to_cart(
item: str,
price: float,
state: Annotated[dict, InjectedState],
) -> str:
"""Fügt einen Artikel zum Warenkorb hinzu.
Argumente:
item: Artikelname
: item
"""
cart = state.get("cart", [])
total = state.get("total_price", 0.0)
return {
"cart": cart + [item],
"total_price": total + price,
"messages": [], # Keine zusätzlichen Nachrichten hinzufügen
}
@tool
def view_cart(
state: Annotated[dict, InjectedState],
) -> str:
"""Inhalt des Warenkorbs anzeigen"""
cart = state.get("cart", [])
total = state.get("total_price", 0.0)
if not cart:
return "Der Warenkorb ist leer"
items = "、".join(cart)
return f"Warenkorb: {items}, Gesamtpreis: ¥{total:.2f}"
model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
model=model,
tools=[add_to_cart, view_cart],
state_schema=ShoppingAgentState, # Benutzerdefinierten Zustand verwenden
system_prompt="Du bist der Einkaufsassistent des Example-Shops.",
)
# Der Anfangszustand enthält einen leeren Einkaufswagen
result = agent.invoke({
"messages": [HumanMessage(content="Hilf mir, ein Python-Tutorial zum Einkaufswagen hinzuzufügen, Preis 49.9")],
"cart": [],
"total_price": 0.0,
})
print(f"Einkaufswagen: {result.get('cart', [])}")
print(f"Gesamtpreis: ¥{result.get('total_price', 0):.2f}")
print(f"Antwort: {result['messages'][-1].content}")
Ausgabe:
Cart: ['Python 教程'] Total: ¥49.90 Reply: 已将《Python 教程》(¥49.90)添加到购物车。当前购物车共 1 件商品,总价 ¥49.90。
state_schema vs. Middleware-state_schema
Du kannst den Zustand über den Parameter state_schema von create_agent() erweitern oder über das state_schema der Middleware. Der Unterschied zwischen den beiden:
| Methode | Anwendungsfall | Priorität |
|---|---|---|
| create_agent(state_schema=...) | Globale State-Erweiterung, gemeinsam genutzt von allen Knoten | Höchste (überschreibt Felder mit demselben Namen in Middleware) |
| AgentMiddleware(state_schema=...) | State-Erweiterung für bestimmte Middleware | Niedriger, kann von create_agent überschrieben werden |
Weitere ErweiterungenEmpfohlene Vorgehensweise: Platzieren Sie gemeinsame Business-State-Felder in state_schema und middleware-spezifische interne Felder im state_schema der Middleware. Dies hält die Verantwortlichkeiten klar und vermeidet Kreuzkontamination.