Wie man Tools entwirft

Wie gut ein Agent funktioniert, hängt zu einem großen Teil von den Tools ab. Das Modell sieht nur Name, Beschreibung und Parameterdefinition eines Tools, nicht deinen Code. Ist die Beschreibung vage, muss das Modell raten: Was kann dieses Tool? Wann soll ich es nutzen? Was trage ich als Parameter ein?

Diese Lektion misst zuerst in einem Experiment, wie viel eine gute oder schlechte Beschreibung ausmacht, und erklärt dann, wie man sie konkret schreibt.

Experiment: vage und klare Beschreibungen

Dieselben drei Funktionen: in der Dokumentation suchen, eine Dokumentationsdatei lesen, die Versionsnummer auf PyPI nachschlagen. Dazu zwei Sätze Beschreibungen.

Der vage Satz: Die Namen sind allgemeine Verben, die Beschreibungen nur zwei, drei Zeichen lang:

VAGUE = [
    fn("search", "搜索", q="内容"),
    fn("read", "读取", x="要读的东西"),
    fn("lookup", "查找信息", name="名字"),
]

Der klare Satz: Die Namen nennen das Objekt der Operation, die Beschreibungen sagen klar, was das Tool kann, wann man es nutzt und wie die Parameter auszufüllen sind:

CLEAR = [
    fn("search_docs", "在 httpx 官方文档里按英文关键词全文搜索，返回匹配的文件名和行号。"
       "用户问 httpx 某个功能怎么用、某个参数是什么意思时，先用它。",
       keyword="英文关键词，例如 timeout、proxy、follow_redirects"),
    fn("read_doc", "读取 httpx 文档里某个文件的内容。通常在 search_docs 找到文件名之后使用。",
       path="文档文件路径，例如 advanced/timeouts.md"),
    fn("get_pypi_info", "查询某个 Python 包在 PyPI 上的最新版本号和发布信息。只在用户问版本号、是否已发布新版本时使用。",
       package="PyPI 上的包名，例如 httpx"),
]

(fn ist eine kleine Funktion, die die Tool-Beschreibung erzeugt; vollständiger Code in code/05-agents/tool_design.py.)

Dann bereiten wir 10 Fragen vor und vermerken zu jeder, welches Tool im ersten Schritt aufgerufen werden sollte. Bei der Frage „你好“ (Hallo) ist die richtige Antwort, gar kein Tool aufzurufen. Jede Frage wird mit jedem Beschreibungssatz 3-mal gestellt; wir sehen nur, welches Tool das Modell im ersten Schritt wählt, und führen nichts wirklich aus:

QUESTIONS = [
    ("httpx 怎么设置代理？", "search_docs"),
    ("httpx 最新版本是多少？", "get_pypi_info"),
    ("帮我看看 advanced/ssl.md 里写了什么", "read_doc"),
    ("follow_redirects 参数是干什么的？", "search_docs"),
    ("requests 现在出到哪个版本了？", "get_pypi_info"),
    ("httpx 怎么上传文件？", "search_docs"),
    ("你好", None),
    ("把 quickstart.md 的内容给我看一下", "read_doc"),
    ("httpx 有没有发布 1.0 正式版？", "get_pypi_info"),
    ("httpx 的 event hooks 怎么用？", "search_docs"),
]

Ergebnis:

含糊的工具：14/30 次选对
    httpx 怎么设置代理？  应该用 search_docs，实际 {'None': 2, 'search_docs': 1}
    httpx 最新版本是多少？  应该用 get_pypi_info，实际 {'search_docs': 3}
    帮我看看 advanced/ssl.md 里写了什么  应该用 read_doc，实际 {'read_doc': 2, 'get_pypi_info': 1}
    follow_redirects 参数是干什么的？  应该用 search_docs，实际 {'search_docs': 1, 'None': 1, 'get_pypi_info': 1}
    requests 现在出到哪个版本了？  应该用 get_pypi_info，实际 {'get_pypi_info': 1, 'search_docs': 2}
    httpx 怎么上传文件？  应该用 search_docs，实际 {'None': 3}
    httpx 有没有发布 1.0 正式版？  应该用 get_pypi_info，实际 {'search_docs': 3}
清楚的工具：30/30 次选对

Dasselbe Modell, nur andere Beschreibungen, und die Trefferquote steigt von 47 % auf 100 %.

Was an den vagen Beschreibungen falsch ist

Unklar, wofür das Tool zuständig ist. Wo sucht „搜索“ (Suche)? Im Web, in der Dokumentation oder im Code? Das Modell weiß es nicht. Also wählte es bei „Was ist die neueste Version von httpx?“ alle 3 Male search, weil „Suche“ am allgemeinsten klingt.

Unklar, wann man es nutzt. Bei „Wie lädt man mit httpx Dateien hoch?“ rief es 3-mal gar kein Tool auf und antwortete direkt aus dem Gedächtnis. Es wusste nicht, dass search ihm eine verlässlichere Antwort liefern kann, und hatte keinen Grund, es zu nutzen.

Name und Funktion passen nicht zusammen. lookup schlägt eigentlich Versionen auf PyPI nach, aber die Beschreibung „Informationen nachschlagen“ lässt sich nicht von „lesen“ und „suchen“ unterscheiden, also wählt das Modell zufällig. Bei „Wofür ist der Parameter follow_redirects?“ ergaben 3 Versuche 3 verschiedene Ergebnisse.

Die klaren Beschreibungen sagen all das: Gesucht wird in der „offiziellen httpx-Dokumentation“, „wenn der Nutzer fragt, wie man eine Funktion von httpx nutzt, zuerst dieses verwenden“; das Versionstool ist „nur zu verwenden, wenn der Nutzer nach der Versionsnummer fragt“. Das Modell muss nicht raten.

Namen

• Das Objekt der Operation nennen. search_docs ist besser als search, get_pypi_info besser als lookup. Bei vielen Tools kollidieren allgemeine Namen leicht.
• Mit einem Verb beginnen und einheitlich bleiben. get_, search_, read_, create_ – eine Regel, durchgehend angewendet.
• Keine Abkürzungen. Du weißt, was gpi ist, das Modell nicht.

Beschreibungen

Eine gute Beschreibung beantwortet drei Fragen:

1. Was kann es? „Durchsucht die offizielle httpx-Dokumentation im Volltext nach englischen Stichwörtern und liefert passende Dateinamen und Zeilennummern.“
2. Wann soll man es nutzen? „Wenn der Nutzer fragt, wie man eine Funktion von httpx nutzt, zuerst dieses verwenden.“
3. Wann nicht? „Nur verwenden, wenn der Nutzer nach der Versionsnummer oder nach einer neu veröffentlichten Version fragt.“

Der dritte Punkt ist besonders wichtig, wenn Tools leicht zu verwechseln sind. Außerdem kann die Beschreibung festhalten, wie Tools zusammenspielen, etwa bei read_doc „normalerweise nachdem search_docs den Dateinamen gefunden hat“; dann weiß das Modell, dass es erst sucht und dann liest.

Parameter

• Jeden Parameter beschreiben, am besten mit Beispiel. „Englisches Stichwort, z. B. timeout, proxy, follow_redirects.“ Das Beispiel zeigt dem Modell das Format und deutet zugleich an: „Die Dokumentation ist englisch, also englisch suchen.“
• So wenige Parameter wie möglich. Hat ein Tool sieben, acht Parameter, lässt das Modell leicht welche aus oder füllt sie falsch. Wo ein Standardwert möglich ist, einen setzen.
• Werte mit Aufzählungen begrenzen. Kann ein Parameter nur wenige feste Werte annehmen, im Schema per enum aufzählen (in Modul 02, Lektion 4 verwendet).
• Namen und Typen eindeutig machen. Parameternamen wie x, q, name sind schlechter als path, keyword, package.

Rückgabewerte

Der Rückgabewert eines Tools geht unverändert in den Kontext, und jeder weitere Schritt bezahlt ihn mit. Deshalb:

• Nur nützliche Informationen zurückgeben. get_pypi_info aus der vorigen Lektion wählt nur vier Felder aus (Versionsnummer, Kurzbeschreibung, Anforderung an die Python-Version usw.), statt die Dutzende KB rohes JSON von PyPI komplett hineinzustopfen.
• Die Länge begrenzen. grep_docs aus der vorigen Lektion liefert höchstens 20 Treffer, read_doc höchstens 80 Zeilen auf einmal, und die Schleife kürzt zusätzlich auf 3000 Zeichen.
• Den nächsten Schritt des Modells erleichtern. grep_docs liefert „Dateiname:Zeilennummer:Inhalt“, und das Modell kann Dateiname und Zeilennummer direkt an read_doc übergeben.
• Leere Ergebnisse klar benennen. „Nichts zu pool timeout gefunden“ zurückgeben statt eines leeren Strings. Ein leerer String verwirrt das Modell: Ist das Tool kaputt, oder gibt es wirklich nichts?

Fehlermeldungen

Fehlermeldungen sind für das Modell geschrieben und sollen ihm helfen, sich zu korrigieren:

错误：没有这个文件 advanced/timeout.md，请先用 list_docs 查看有哪些文件

Dieser eine Satz sagt drei Dinge: was schiefgegangen ist, bei welchem Parameter und was als Nächstes zu tun ist. Pythons Standardmeldung FileNotFoundError: [Errno 2] No such file or directory versteht das Modell auch, weiß dann aber nicht, mit welchem Tool es den richtigen Dateinamen findet.

Wenn es viele Tools werden

Je mehr Tools, desto schwerer wählt das Modell richtig, und desto länger werden die Beschreibungen in jeder Anfrage. Einige Erfahrungswerte:

• Ähnliche Tools zusammenlegen. Kannst selbst du den Unterschied zwischen search_docs und search_api_reference nicht erklären, leg sie zu einem zusammen und unterscheide per Parameter.
• Nach Einsatzzweck gruppieren. Verschiedene Aufgaben bekommen nur die jeweils relevanten Tools; die Mehr-Agenten-Systeme in Lektion 6 nutzen diese Idee.
• Die Spur ansehen. Ein Tool, das oft falsch verwendet wird, ist ein Tool, dessen Beschreibung geändert werden muss.

Übungen

1. Streich in der klaren Gruppe von tool_design.py aus der Beschreibung von search_docs den Satz „wenn der Nutzer fragt, wie man eine Funktion von httpx nutzt, zuerst dieses verwenden“ und führ es erneut aus. Ändert sich das Ergebnis bei der Frage „Wie lädt man mit httpx Dateien hoch?“?
2. Füg beiden Tool-Sätzen eine Funktion hinzu: list_docs, das alle Dokumentationsdateien auflistet. In der vagen Gruppe heißt es list mit der Beschreibung „Liste“, in der klaren Gruppe schreib es nach der Methode dieser Lektion. Füg zwei Fragen hinzu, um es zu testen.
3. Such eine Funktion, die du früher geschrieben hast, schreib nach der Methode dieser Lektion eine Tool-Beschreibung dafür und lass das Modell sie aufrufen.

Selbsttest

1. Welche Fragen sollte eine gute Tool-Beschreibung beantworten?

Was es kann; wann man es nutzen soll; wann nicht (vor allem, wenn es leicht mit anderen Tools verwechselt wird). Zusätzlich kann man festhalten, wie es mit anderen Tools zusammenspielt, etwa „normalerweise nach search_docs verwenden“.

2. Warum sollten Rückgabewerte von Tools möglichst kurz sein?

Der Rückgabewert landet unverändert in der Nachrichtenliste; jeder weitere Schritt des Agenten ruft das Modell mit ihm auf und bezahlt ihn mit. Zu lange Rückgaben lassen das Modell außerdem das Wesentliche verlieren und können sogar das Kontextfenster füllen. Nur nützliche Felder zurückgeben und eine Längengrenze setzen.

3. Wie schreibt man Fehlermeldungen eines Tools am besten?

Für das Modell: klar sagen, was schiefgegangen ist, wo, und was als Nächstes zu tun ist. Etwa „Diese Datei X gibt es nicht, bitte erst mit list_docs nachsehen, welche Dateien es gibt“. So kann sich das Modell selbst korrigieren, statt immer wieder denselben Fehler zu machen.