Skip to main content

Installation

Unterstützt: pydantic-ai-slim 2.0 bis 3.0. Version 2.0 hat Agent(instrument=...) entfernt und das Capability-Protokoll eingeführt, auf dem dieser Adapter aufbaut. Version 1.x kann daher auf diese Weise nicht instrumentiert werden.

Instrumentierung

instrument() muss ausgeführt werden, bevor ein Agent erstellt wird. Die Capability wird beim Erstellen angehängt – ein vorher erstellter Agent enthält keine und zeichnet nichts auf, ohne dass ein Fehler ausgegeben wird, da technisch nichts schiefgelaufen ist. Dies ist die häufigste Ursache für einen leeren Trace mit diesem Adapter.
Agenten auf Modulebene sind dabei besonders tückisch:
Zur Überprüfung:
Pydantic AI fasst die übergebene Liste zu einer einzelnen root_capability zusammen, daher gibt es kein agent.capabilities-Attribut zum Auslesen. Agenten, die während der Instrumentierung erstellt wurden, behalten die Capability – uninstrument() und erneutes Instrumentieren sind ohne Neuerstellung möglich.

Was aufgezeichnet wird

Es gibt hier kein Hook-Paar und kein Human-in-the-Loop-Paar. Pydantic AI hat keine Node- oder Schrittgrenze zum Einklammern und keine eingebaute menschliche Pause – daher gibt es nichts zuzuordnen. Falls Sie beides implementieren, senden Sie die Ereignisse selbst – siehe Benutzerdefinierte Agenten. output_type hat keinen Einfluss auf den Trace. Ein typisierter Lauf und ein String-Lauf erzeugen dieselben Ereignisse.

Beispiel

Im Trace erscheint restock_eta als tool_result mit einem Fehler, gefolgt von einem weiteren Modellaufruf, bei dem der Agent damit umgeht – der Lauf endet dennoch mit success. Beide Informationen werden festgehalten.

Fehler, Wiederholungsversuche und Kontrollfluss

Pydantic AI wirft Ausnahmen für drei verschiedene Fälle, und der Adapter unterscheidet zwischen ihnen: ModelRetry gehört bewusst zur ersten Gruppe. Es bedeutet, dass ein Versuch tatsächlich fehlgeschlagen ist und das Modell aufgefordert wurde, es erneut zu versuchen – genau dafür ist das Fehlerfeld eines Tool-Spans gedacht. Eine Einordnung als Kontrollfluss würde echte Tool-Fehler hinter einem grünen Lauf verbergen.

Spans benennen

Pydantic AIs eigener Run-Span heißt agent. Umschließen Sie den Aufruf, um ihm einen selbst gewählten Namen zu geben:
Der Framework-Span wird dann unter inventory eingebettet, und dort hängen die Modell- und Tool-Ereignisse. Halten Sie agent_id mit geringer Kardinalität. Es ist die primäre Facette auf jeder Dashboard-Oberfläche – verwenden Sie daher einen Rollennamen, niemals eine UUID oder einen laufspezifischen String.

Session steuern

Wird in dieser Reihenfolge aufgelöst, der erste Treffer gewinnt:
  1. instrument("pydantic_ai", session_id=...)
  2. Der umschließende failproofai_sdk.session()-Scope
  3. Die conversation_id des Laufs, dann dessen run_id
  4. Eine generierte uuid4().hex

Optionen

Häufige Probleme

Der Agent wurde erstellt, bevor instrument() ausgeführt wurde. Siehe den Hinweis oben und prüfen Sie agent.root_capability.capabilities.
Ein bloßes raise wird weitergegeben – das ist das Design von Pydantic AI. Damit das Modell damit umgehen kann, verwenden Sie ModelRetry mit einer Nachricht, auf die es reagieren kann. Der Fehler wird in jedem Fall aufgezeichnet.
Dieser untergeordnete Span ist Pydantic AIs eigener Run-Span, und dort hängen die Modell- und Tool-Ereignisse. Entfernen Sie Ihren eigenen Scope, wenn Sie einen einzelnen Span möchten – auf Kosten des benutzerdefinierten Namens.
Pydantic AIs asynchroner Graph-Stack ist länger als das Feldlimit der Nutzlast, und die letzte Zeile eines Tracebacks ist die Ausnahme selbst. Dieses Feld wird von vorne statt von hinten gekürzt, sodass die benötigte Zeile erhalten bleibt.

Weiter

Funktionsweise

Paare, IDs, Session-Lebenszyklus und Übertragung.

Einen Trace lesen

Kausalität durch die gerade aufgezeichnete Session verfolgen.

Andere Frameworks

LangGraph, CrewAI, LlamaIndex und benutzerdefinierte Agenten.