0%

Ein kleiner Agent · Übung

Fragen, bevor etwas verändert wird

Bisher lesen die Tools des Agenten nur. Ein falscher Aufruf von read_note kostet ein paar Tokens und sonst nichts. In dieser Lektion bekommt der Agent ein Tool, das eine Datei schreibt, und das Programm fragt einen Menschen, bevor es läuft.

Ein Tool, das etwas verändert

Weit oben in agent.py steht das dritte Tool, save_flashcard, mit seiner Hilfsfunktion:

def card_name_ok(name):
    """Return True when name has 1 to 40 characters, all from CARD_NAME_CHARACTERS."""
    if len(name) < 1 or len(name) > 40:
        return False
    for character in name:
        if character not in CARD_NAME_CHARACTERS:
            return False
    return True


def save_flashcard(arguments):
    """Tool: save a card as flashcards/<name>.md. It writes a file, so it needs approval."""
    name = arguments.get("name")
    front = arguments.get("front")
    back = arguments.get("back")
    if not isinstance(name, str) or not card_name_ok(name):
        raise ValueError(
            "save_flashcard needs a name made of lowercase letters, digits and hyphens, such as list-copying."
        )
    if not isinstance(front, str) or not isinstance(back, str):
        raise ValueError("save_flashcard needs front and back strings.")
    FLASHCARDS_DIR.mkdir(exist_ok=True)
    with open(FLASHCARDS_DIR / f"{name}.md", "w", encoding="utf-8") as handle:
        handle.write(f"Q: {front}\nA: {back}\n")
    return f"Saved flashcards/{name}.md."

Das Modell wählt alle drei Argumente, auch den Dateinamen. Ein Name wird an einen Ordner angehängt, um einen Pfad zu bilden, und ein Name wie ../notes/01-variables würde aus flashcards herausklettern und eine der Kursnotizen überschreiben. Deshalb akzeptiert card_name_ok nur Kleinbuchstaben, Ziffern und Bindestriche (CARD_NAME_CHARACTERS), und save_flashcard lehnt jeden anderen Namen mit einem ValueError ab, bevor es einen Pfad baut. Ein Punkt oder ein Schrägstrich kommt nicht durch. Der ValueError erreicht das Modell als Fehlerergebnis, über run_tool aus Kapitel 6.

Diese Prüfung hält jeden Schreibvorgang innerhalb von flashcards, aber sie kann nicht entscheiden, ob die Person überhaupt eine Lernkarte will, und sie verhindert nicht, dass eine neue Karte eine frühere mit demselben Namen ersetzt. Ein Modell, das die Frage missverstanden hat, könnte eine Karte speichern, um die niemand gebeten hat, oder viele. Eine Notiz zu lesen verändert nichts, also darf der Agent das frei tun. Eine Datei zu schreiben verändert etwas, also entscheidet ein Mensch.

Wer entscheidet

agent.py führt die Tools auf, die etwas verändern:

CHANGING_TOOLS = ["save_flashcard"]

Bevor eines davon läuft, fragt die Schleife nach. Wie sie fragt, bestimmt der Aufrufer: Ein Kommandozeilenprogramm könnte den Aufruf ausgeben und auf input() warten, eine Web-App könnte einen Button zeigen, und ein Test antwortet automatisch. Deshalb ist das Fragen eine Funktion, die der Aufrufer übergibt, namens approve. Die Schleife ruft approve(call) mit dem Dictionary des Aufrufs auf und führt das Tool nur aus, wenn True zurückkommt.

Das heißt, eine Funktion als Argument zu übergeben. Die andere Hälfte der Idee kennst du schon: TOOLS hat Funktionen als Werte in einem Dictionary gespeichert, und run_tool hat die gefundene aufgerufen. Hier kommt die Funktion als Parameter an, und run_calls ruft sie auf, ohne zu wissen, was sie tut.

Für die Demonstrationsläufe gibt es zwei solche Funktionen:

def approve_all(call):
    """Approve every call. A real program would ask the person, for example with input()."""
    return True


def refuse_all(call):
    """Refuse every call. A real program would ask the person, for example with input()."""
    return False

Eine Ablehnung ist kein Fehler im Programm. Das Modell hat um etwas gebeten, und die Antwort war Nein. Sie geht als Tool-Ergebnis an das Modell zurück, damit das Modell der Person sagen kann, was passiert ist:

Error: save_flashcard was not approved, so it did not run.

Baue run_calls

run_calls(calls, tools, approve) ersetzt tool_messages in der Schleife:

  1. Beginne mit einer leeren Liste.

  2. Für jeden Aufruf, der Reihe nach: Wenn sein Name in CHANGING_TOOLS steht und approve(call) nicht True zurückgibt, ist das Ergebnis f"Error: {name} was not approved, so it did not run.". Andernfalls ist das Ergebnis run_tool(call, tools).

  3. Hänge für jeden Aufruf tool_result(call, result) an und gib die Liste zurück.

Frag nur bei Tools in CHANGING_TOOLS nach, und frag einmal pro Aufruf. Ein abgelehnter Aufruf hält die anderen in derselben Antwort nicht auf: Jeder Aufruf bekommt sein eigenes Ergebnis, wie in Kapitel 6, Lektion 7.

Gib dann run_agent einen Keyword-only-Parameter approve, nach system, und rufe run_calls(calls, tools, approve) dort auf, wo bisher tool_messages(calls, tools) stand. Die Ergebnisse landen weiterhin im Trace, also taucht eine Ablehnung dort auf.

Ausführen

Führe python agent.py aus. Die Demonstration sendet Make a flashcard about copying a list. mit AGENT_TOOLS, zuerst mit approve_all und dann mit refuse_all, und danach Make a flashcard called ../notes/01-variables. mit approve_all:

Make a flashcard about copying a list. With approve_all:
Step 1 (50 tokens)
  read_note {"note_id": "03-lists"} -> 1226 characters
Step 2 (391 tokens)
  save_flashcard {"name": "copying-a-list", "front": "How do you make an independent copy of a list?", "back": "Use scores.copy() or list(scores). Both build a new list."} -> 35 characters
Step 3 (384 tokens)
  answered
answer: I saved a flashcard called copying-a-list. It asks how to make an independent copy of a list. (03-lists)
Make a flashcard about copying a list. With refuse_all:
Step 1 (50 tokens)
  read_note {"note_id": "03-lists"} -> 1226 characters
Step 2 (391 tokens)
  save_flashcard {"name": "copying-a-list", "front": "How do you make an independent copy of a list?", "back": "Use scores.copy() or list(scores). Both build a new list."} -> 58 characters
Step 3 (414 tokens)
  answered
answer: I did not save the flashcard, because you did not approve it. Here it is, so you can write it down yourself: How do you make an independent copy of a list? Use scores.copy() or list(scores). (03-lists)
Make a flashcard called ../notes/01-variables. With approve_all:
Step 1 (75 tokens)
  save_flashcard {"name": "../notes/01-variables", "front": "What is a variable?", "back": "A name that refers to a value."} -> 103 characters
Step 2 (95 tokens)
  answered
answer: I couldn't save that flashcard. The tool answered with an error, which you can read in the trace.
flashcards/copying-a-list.md holds:
Q: How do you make an independent copy of a list?
A: Use scores.copy() or list(scores). Both build a new list.
Run stopped at the next function to build: repeated_call is built in Lesson 7.

Im genehmigten Lauf wurde die Karte gespeichert, und ihr Ergebnis mit 35 Zeichen lautet Saved flashcards/copying-a-list.md.. Im abgelehnten Lauf war das Ergebnis die Ablehnung mit 58 Zeichen, und die letzte Antwort des Modells sagt, dass es die Karte nicht gespeichert hat. Das geskriptete Modell kann so antworten, weil seine Zeile für diese Frage eine Antwort für eine Anfrage enthält, deren Tool-Ergebnisse was not approved enthalten, wie SCRIPTED_MODEL.md sagt. Ein Live-Modell würde die Ablehnung lesen und seine eigene Antwort schreiben.

Der dritte Lauf wurde genehmigt, und save_flashcard hat trotzdem abgelehnt: Das Ergebnis mit 103 Zeichen ist seine ValueError-Meldung zum Namen. Die Genehmigung ist nicht die einzige Sicherung. Ein Mensch kann einen Aufruf genehmigen, ohne den Dateinamen genau zu lesen, und das Tool prüft trotzdem, was es bekommt.

In deinem Arbeitsbereich gibt es jetzt einen neuen Ordner flashcards mit der gespeicherten Karte darin.

Während eines Laufs fordert das Modell read_note und dann save_flashcard an. Wie oft ruft run_calls approve auf?

approve lehnt einen Aufruf von save_flashcard ab. Was bekommt das Modell dafür zurück?

approve_all genehmigt den Aufruf von save_flashcard mit dem Namen ../notes/01-variables. Was passiert?

Aufgabe

Ersetze in agent.py den unfertigen Rumpf von run_calls(calls, tools, approve) und verwende die Funktion dann in run_agent.

  • run_calls: Für jeden Aufruf, der Reihe nach: Wenn sein Name in CHANGING_TOOLS steht und approve(call) nicht True zurückgibt, ist das Ergebnis f"Error: {name} was not approved, so it did not run.". Andernfalls ist das Ergebnis run_tool(call, tools). Gib pro Aufruf eine Nachricht tool_result(call, result) zurück.

  • Rufe approve nur für Tools in CHANGING_TOOLS auf, einmal pro Aufruf, mit dem Dictionary des Aufrufs.

  • Gib run_agent einen Keyword-only-Parameter approve, nach system, und verwende run_calls(calls, tools, approve) dort, wo bisher tool_messages(calls, tools) stand.

Führe python agent.py aus, um auf drei Arten eine Lernkarte anzufordern, und prüfe dann deine Arbeit.