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 import Annotated
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]
FeldTypeErforderlich?Beschreibung
messageslist[AnyMessage]JaNachrichtenverlauf, angehängt unter Verwendung des add_messages-Reducers
jump_tostr or NoneneinProzesssprungsteuerung, optionale Werte: tools, model, end. Flüchtiges Attribut, nach der Verwendung automatisch gelöscht
structured_responseAnyneinStrukturiertes 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 langchain.messages import HumanMessage, AIMessage
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 import create_agent
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 valueSpringe zuWirkung
"tools"Direkt zum Tool-Ausführungsknoten gehenModellaufruf überspringen, das angegebene Tool direkt ausführen
"model"Zum Modellknoten zurückkehrenDas Modell erneut verarbeiten lassen (normalerweise kombiniert mit Tool-Nachrichten-Injektion)
"end"Agent-Schleife beendenDirekt 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 pydantic import BaseModel, Field
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 typing import Annotated
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:

MethodeAnwendungsfallPriorität
create_agent(state_schema=...)Globale State-Erweiterung, gemeinsam genutzt von allen KnotenHöchste (überschreibt Felder mit demselben Namen in Middleware)
AgentMiddleware(state_schema=...)State-Erweiterung für bestimmte MiddlewareNiedriger, kann von create_agent überschrieben werden

Empfohlene 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.

Weitere Erweiterungen