LangChain @tool-Dekorator — Tools definieren

Ein Tool ist die Brücke für einen Agenten, um mit der externen Welt zu interagieren.

Mit dem@tool-Decorator können Sie jede Python-Funktion schnell in ein Tool umwandeln, das von einem Agenten aufgerufen werden kann.


@tool Basis-Syntax

@tool ist ein von LangChain bereitgestellter Dekorator. Seine Verwendung ist extrem einfach: Füge einer Funktion den @tool-Dekorator hinzu, und die Funktion wird zu einem Tool.

Beispiel

from langchain.tools import tool

# Das einfachste Tool: eine gewöhnliche Funktion + @tool-Dekorator
@tool
def hello_tool(name: str) -> str:
    """Sag Hallo zu der angegebenen Person.

    Argumente:
name: der Name der zu begrüßenden Person
    """

    return f"Hallo, {name}! Willkommen beim EXAMPLE Tutorial."

# Ein Tool ist ebenfalls eine gewöhnliche Python-Funktion und kann direkt aufgerufen werden
result = hello_tool.invoke({"name": "Xiao Ming"})
print(result)

# Das Tool enthält automatisch generierte Beschreibungsinformationen
print(f"\nTool-Name: {hello_tool.name}")
print(f"Tool-Beschreibung: {hello_tool.description}")

Ausgabe:

你好,小明!欢迎来到Example。

Tool name: hello_tool
Tool description: 向指定的人打招呼。

    Args:
        name: 要打招呼的人的名字

Der Docstring der Funktion wird automatisch zur Beschreibung des Tools. Der Agent verlässt sich auf diese Beschreibung, um zu bestimmen, "was dieses Tool kann" und "wann es aufgerufen werden sollte." Je klarer der Docstring, desto präziser verwendet der Agent das Tool. In der Beschreibung sollten Parameterbedeutungen, Funktionsverhalten und Anwendungsszenarien erläutert werden.


Verwendung verschiedener Parametertypen

@tool unterstützt mehrere Parametertypen, darunter int, float, bool und Enum-Werte:

Beispiel

from langchain.tools import tool
from typing import Literal


@tool
def search_courses(
    keyword: str,
    level: Literal["Beginner", "Intermediate", "Advanced"],
    max_results: int = 5,
    free_only: bool = True,
) -> str:
    """Kurse auf EXAMPLE Tutorial suchen.

    Argumente:
keyword: Suchbegriff
level: Schwierigkeitsgrad des Kurses
max_results: maximale Anzahl der zurückzugebenden Ergebnisse
free_only: ob nur kostenlose Kurse angezeigt werden sollen
    """

    # Suchergebnisse simulieren
    courses = {
        ("python", "Anfänger"): "Python3-Grundlagen-Tutorial (Kostenlos)",
        ("python", "Mittelstufe"): "Python-Datenanalyse-Übung (Kostenlos)",
        ("python", "Fortgeschritten"): "Python Machine Learning Fortgeschritten (Nur für Mitglieder)",
        ("html", "Anfänger"): "HTML-Grundlagen-Tutorial (Kostenlos)",
    }
    key = (keyword.lower(), level)
    course = courses.get(key, f"Keine {keyword}-Kurse auf dem {level}-Niveau gefunden")
    if free_only and "Nur für Mitglieder" in course:
        return f"Suchergebnis: {course} — dieser Kurs erfordert eine Mitgliedschaft und wurde für dich herausgefiltert"
    return f"Suchergebnis: {course}"


# Testaufrufe mit unterschiedlichen Parametern
print(search_course.invoke({
    "keyword": "python",
    "level": "Anfänger",
}))
# Ausgabe: Suchergebnis: Python3-Grundlagen-Tutorial (Kostenlos)

print(search_course.invoke({
    "keyword": "python",
    "level": "Fortgeschritten",
    "free_only": False,
}))
# Ausgabe: Suchergebnis: Python Maschinelles Lernen Fortgeschritten (Nur für Mitglieder)

Werkzeuge beim Agenten registrieren

Übergeben Sie das definierte Werkzeug an den Parameter tools von create_agent(), und der Agent kann es verwenden:

Beispiel

from dotenv import load_dotenv
load_dotenv()

from langchain.tools import tool
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage


@tool
def search_courses(keyword: str) -> str:
    """Suchen Sie nach Kursen auf EXAMPLE Tutorial. Übergeben Sie ein Schlüsselwort und erhalten Sie eine Liste verwandter Kurse.

    Argumente:
keyword: Suchschlüsselwort, z. B. python, html, java
    """

    courses = {
        "python": "Python3-Grundlagen-Tutorial, Python-Datenanalyse, Einführung in Python-Web-Crawler",
        "html": "HTML-Grundlagen-Tutorial, Neue Funktionen in HTML5, Übung zu HTML-Formularen",
        "java": "Java-Grundlagen-Tutorial, Objektorientiertes Java, Java Spring Framework",
    }
    return courses.get(keyword.lower(), f"Keine Kurse zu {keyword} gefunden")


@tool
def get_course_detail(course_name: str) -> str:
    """Detaillierte Informationen zum angegebenen Kurs abrufen, einschließlich der Anzahl der Kapitel und der Lernzeit.

    Argumente:
course_name: Kursname, z. B. "Python3 Basics Tutorial"
    """

    details = {
        "python3 basics tutorial": "Insgesamt 30 Kapitel, geschätzte Lernzeit 20 Stunden, geeignet für absolute Anfänger",
        "html basics tutorial": "Insgesamt 25 Kapitel, geschätzte Lernzeit 15 Stunden, geeignet für absolute Anfänger",
    }
    return details.get(
        course_name.lower(),
        f"{course_name}-Details: für Anfänger geeignet, inhaltsreich, mit Praxisbeispielen"
    )


# Agent erstellen
model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
    model=model,
    tools=[search_courses, get_course_detail],
    system_prompt="Du bist ein Lernberater für EXAMPLE Tutorial und hilfst Nutzern, passende Kurse zu finden.",
)


# Agent ausführen
def ask(question: str):
    result = agent.invoke({"messages": [HumanMessage(content=question)]})
    print(f"Benutzer: {question}")
    print(f"Berater: {result['messages'][-1].content}")
    print("-" * 60)


ask("Ich möchte Python lernen. Welche Kurse empfehlen Sie?")
ask("Wie lange dauert es, das Python3-Grundlagen-Tutorial abzuschließen?")

Ausgabe:

User: 我想学 Python,有什么课程推荐?
Advisor: 在Example 中有以下 Python 相关课程:
Python3 基础教程、Python 数据分析、Python 爬虫入门。
这些课程很适合 Python 初学者和进阶学习者,您可以根据兴趣选择!
------------------------------------------------------------
User: Python3 基础教程学完需要多久?
Advisor: Python3 基础教程共 30 章,预计学习时长 20 小时,非常适合零基础入门学习。
------------------------------------------------------------

Mehrere Tools arbeiten zusammen

Ein Agent kann mehrere Tools registrieren, und das Modell entscheidet automatisch, wann welches Tool verwendet wird:

Beispiel

from langchain.tools import tool
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage


@tool
def get_stock_price(symbol: str) -> str:
    """Fragt den aktuellen Preis einer Aktie ab.

    Argumente:
symbol: Aktiensymbol, z. B. AAPL, GOOGL, TSLA
    """

    # Simuliere Aktiendaten
    prices = {"AAPL": 185.50, "GOOGL": 142.30, "TSLA": 245.80}
    price = prices.get(symbol.upper())
    if price is None:
        return f"Aktiensymbol {symbol} nicht gefunden"
    return f"{symbol.upper()} aktueller Preis: ${price}"


@tool
def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
    """Währungsumrechnung.

    Argumente:
amount: Geldbetrag
from_currency: ursprünglicher Währungscode, z. B. USD, CNY
to_currency: Zielwährungscode, z. B. CNY, USD
    """

    # Wechselkurse simulieren
    rates = {
        ("USD", "CNY"): 7.25,
        ("CNY", "USD"): 0.138,
    }
    rate = rates.get((from_currency.upper(), to_currency.upper()))
    if rate is None:
        return f"Umrechnung von {from_currency} nach {to_currency} wird nicht unterstützt"
    result = round(amount * rate, 2)
    return f"{amount} {from_currency} = {result} {to_currency}"


model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
    model=model,
    tools=[get_stock_price, convert_currency],
    system_prompt="Du bist ein Finanzassistent, der Benutzern hilft, Aktienkurse zu prüfen und Währungen umzurechnen.",
)

# Der Agent entscheidet automatisch, welches Tool aufgerufen wird
result = agent.invoke({
    "messages": [HumanMessage(content="Wie hoch ist der Aktienkurs von Apple? Wie viel ist das in RMB?")]
})

for msg in result["messages"]:
    if msg.type == "tool":
        print(f"[Tool {msg.name} wird aufgerufen] {msg.content}")
    elif msg.type == "ai" and msg.content:
        print(f"\nEndgültige Antwort: {msg.content}")

Ausgabe:

[调用工具 get_stock_price] AAPL 当前价格:$185.5
[调用工具 convert_currency] 185.5 USD = 1344.88 CNY

Final answer: 苹果(AAPL)当前股价为 $185.50,按当前汇率换算约为 1344.88 人民币。

Optionale Parameter und Standardwerte für Werkzeuge

Das Festlegen von Standardwerten für Werkzeugparameter macht Werkzeuge flexibler in der Nutzung:

Beispiel

from langchain.tools import tool


@tool
def recommend_tutorial(
    language: str,
    level: str = "Beginner",
    count: int = 3,
) -> str:
    """Empfiehlt Kurse aus EXAMPLE Tutorial basierend auf Programmiersprache und Schwierigkeitsgrad.

    Argumente:
language: Programmiersprache, z. B. Python, Java, HTML
level: Schwierigkeitsgrad, Optionen "Beginner", "Intermediate", "Advanced". Standard "Beginner"
count: Anzahl der zu empfehlenden Kurse, Standard 3
    """

    tutorials = {
        "python": ["Python3 Basics", "Python Object-Oriented", "Python Web Crawler", "Python-Datenanalyse"],
        "java": ["Java-Grundlagen", "Java-Objektorientierung", "Java Collections Framework", "Java-Multithreading"],
    }
    all_tutorials = tutorials.get(language.lower(), [f"{language} Grundlagen-Tutorial"])

    selected = all_tutorials[:count]
    return f"Empfohlene {language}-Kurse für {level}: {'、'.join(selected)}"


# Beim Aufruf müssen nur die erforderlichen Parameter übergeben werden
print(recommend_tutorial.invoke({"language": "Python"}))
# Ausgabe: Empfohlene Python-Kurse für Anfänger: Python3-Grundlagen, Python-Objektorientierung, Python-Webcrawler

# Sie können die Standardparameter auch überschreiben
print(recommend_tutorial.invoke({
    "language": "Java",
    "level": "Mittelstufe",
    "count": 2,
}))
# Ausgabe: Empfohlene Java-Kurse für die Mittelstufe: Java Basics, Java Object-Oriented

Standardwerte ermöglichen es dem Agenten, beim Aufrufen von Tools nicht jedes Mal alle Parameter angeben zu müssen. Beachte jedoch: Wenn ein Parameter keinen Standardwert hat und der Agent ihn nicht angibt, schlägt der Aufruf fehl. Setze keine Standardwerte für Schlüsselparameter.


Das args_schema des Tools — Benutzerdefinierte Parametervalidierung

Für komplexe Anforderungen an die Parametervalidierung kann ein Pydantic-Modell als args_schema verwendet werden:

Beispiel

from pydantic import BaseModel, Field
from langchain.tools import tool


# Parametermodell definieren (ermöglicht eine feinere Parametersteuerung)
class CourseSearchInput(BaseModel):
    """Parameter für die Kurssuche"""
    keyword: str = Field(
        description="Suchbegriff, unterstützt Fuzzy-Matching",
        min_length=1,            # Mindestens 1 Zeichen
        max_length=50,           # Höchstens 50 Zeichen
    )
    category: str = Field(
        default="all",
        description="Kurskategorie: all (all), frontend (frontend), backend (backend), data (Datenwissenschaft)",
        pattern=r"^(all|frontend|backend|data)$",  # Erlaubte Werte einschränken
    )
    page: int = Field(
        default=1,
        description="Seitennummer, beginnend bei 1",
        ge=1,                    # Größer oder gleich 1
        le=100,                  # Kleiner oder gleich 100
    )


@tool(args_schema=CourseSearchInput)
def search_course(keyword: str, category: str = "all", page: int = 1) -> str:
    """Kurse auf EXAMPLE-Website suchen"""
    "Suche nach '{keyword}' (Kategorie: {category}, Seite {page}): insgesamt 15 Ergebnisse gefunden" f"Searching '{keyword}' (category: {category}, page {page}): found 15 results in total"


# Gültiger Aufruf
print(search_course.invoke({"keyword": "Python", "category": "backend", "page": 1}))

# Ungültiger Aufruf (Kategorie nicht in den zulässigen Werten)
try:
    search_course.invoke({"keyword": "Python", "category": "invalid"})
except Exception as e:
    print(f"Parametervalidierung fehlgeschlagen: {e}")

Ausführungsergebnisse:

搜索 'Python' (分类: backend, 第 1 页):共找到 15 条结果
参数校验失败: ...

Vergleich der Methoden zur Tool-Definition

MethodeCodeumfangAnwendbare SzenarienBeispiel
@tool-DekoratorAm geringstenEinfache bis mäßig komplexe ToolsDie meisten Szenarien
@tool + args_schemaMittelTools, die eine feingranulare Parametervalidierung erfordernAPI-Wrapping, Datenbankoperationen
Pydantic-Klasse als ToolMehrTools mit komplexer GeschäftslogikTools, die internen Zustand enthalten
Dictionary-FormatAm wenigsten (aber nicht empfohlen)Beschreiben von Remote-/integrierten ToolsMCP-Tools, serverseitige Tools
Weitere Erweiterungen