OpenAI Agents · Beta

OpenAI-Agents-Observability jenseits eines grünen Agents

Ein beendeter Agent-Lauf heißt: der Agent ist durchgelaufen. Nicht: der Job war ein Erfolg. Observability muss beides auf demselben Lauf zeigen.

Was gelaufen ist vs. Bedeutung

OpenAI Agents setzen Agent, Tools und einen Trace-Processor zusammen. Spans zeigen, welche Tools gelaufen sind. Und dass die Schleife fertig ist. Das hilft. Es ist aber nur die halbe Geschichte.

Du brauchst auch ein klares Ziel. Hat der Job gehalten, den du benannt hast? Ohne diese Frage kann ein grüner Agent eine leere Antwort verstecken. Oder eine falsche Antwort hinter gesunden Spans.

Denk in Schichten auf einem Lauf. Tracing für Spans. Checks für Qualität. Kosten für Spend. Outcomes für „war der Job erledigt?“ Halte sie zusammen. Lass die letzte Schicht nicht nur in einem Chat oder einer Tabelle liegen.

Was das in der Praxis heißt

Stell dir einen OpenAI-Agents-Lauf von Start bis Ende vor. Du gehst denselben Lauf zweimal durch. Einmal für Agent und Tools. Einmal für den Job, den du dem Nutzer zugesagt hast.

Zuerst schaust du auf Tracing. Der Agent ist fertig. Tools haben geantwortet. Keine Exception. Die Spans sehen gut aus. Das sagt nur: Der Agent hat seine Schleife beendet.

Dann kommt die Frage zum Job. Gibt es eine brauchbare Antwort? Ist sie korrekt genug zum Ausliefern? Fallen die Checks durch, ist der Lauf für den Nutzer ein Fail. Auch wenn der Agent grün wirkt.

Hänge Kosten an dieselbe Lauf-ID. Tokens und Tool-Spend zählen mehr, wenn du weißt, ob das Ziel passt. Ein günstiger Fail und ein teurer Fail sind zwei Reviews. Beide brauchen das markierte Ziel.

Schreib die Regel einmal neben den Code. Jede Person soll denselben Lauf gleich werten. Das ist OpenAI-Agents-Observability jenseits einer grünen Ampel.

Beispiel: falscher Erfolg

Der Agent kann fertig werden. Tools können antworten. Es muss keine Exception geben. Die Antwort kann trotzdem leer sein. Oder falsch für den benannten Job. Diese Lücke ist ein falscher Erfolg.

Ops traut vielleicht dem grünen Pfad. Produkt sieht trotzdem einen Fail. Ohne ein benanntes Ziel auf dem Lauf treffen sich diese beiden Sichten nie.

Ein fertiger Agent-Span ist nicht dasselbe wie eine brauchbare Antwort. Ein sauberer Tool-Return beweist nicht das richtige Ergebnis für den Job.

Ein Produktziel ist eine kurze, geteilte Regel für „fertig“. Belege sind die Felder, die Pass oder Fail zeigen. Behalte beides neben den OpenAI-Agents-Spans.

Dann kann ein Review fair fragen: Haben wir Geld für einen echten Erfolg ausgegeben? Oder für einen sauberen Agent, der den Job trotzdem verfehlt hat?

Agent-Lauf anbinden

Nutze eine Stelle zum Anbinden. Wrappe den Lauf. Behalte den nativen Trace-Processor. Hänge Sinn an die Daten, die zurückkommen.

Das Snippet unten meldet, ob eine Antwort da ist. Das ist ein einfacher Start. Später kannst du mehr Checks ergänzen. Die Wrap-Form bleibt gleich.

from witdem_sdk.integrations.openai_agents import instrument

observed_run = instrument(
    run,
    report_result=lambda answer: {
        "result": "completed" if answer else "unresolved",
        "result_valid": bool(answer),
        "requirements": {"non_empty_answer": bool(answer)},
        "metrics": {"answer_characters": len(answer)},
    },
)
print(observed_run())

Erfolg neben dem Code deklarieren

Lege das Produktziel im Repo ab. Dann wertet jede Person denselben Lauf mit derselben Regel.

Ein Contract benennt Artefakt und Ziel. Pass heißt: Das Antwortfeld ist da. Das Lehr-YAML darunter zeigt die Form lesbar. Das live OSS-Beispiel nutzt Contract v2 mit einer gemeinsamen useful-answer-Regel — dieselbe Idee, neben dem Agent-Code statt nur im Dashboard.

version: 1
service:
  name: openai-agents-answer
  runtime: openai_agents
contracts:
  useful_answer:
    artifact:
      name: Answer
      valid:
        non_empty: $.answer
    product_goal:
      name: Non-empty answer
      achieved:
        all:
          - $.witdem.artifact_valid

Was am Lauf zählt

Ob das Ziel hält, welche Belege da sind und was der Spend war: Das sollte dieselbe Lauf-ID teilen. Behalte es neben den OpenAI-Agents-Spans. Ersetze Spans nicht durch einen einzelnen Score.

Wenn du einen Lauf öffnest, willst du Pfad und Outcome zusammen. So findest du einen falschen Erfolg. Ohne über Tools hinweg zu raten.

Beispiel ausführen

Starte mit dem basic-agent-Beispiel im Open-Source-Repo. Binde den Helper an. Deklariere ein Ziel. Prüfe einen Lauf von Ende zu Ende.

Lies die OpenAI-Agents-Docs, wenn du die API-Form brauchst. Behalte den Trace-Processor. Ergänze die Outcome-Schicht daneben. Die Integration ist Beta. Die Wrap-Form bleibt. Details können noch enger werden.

FAQ

Heißt ein grüner OpenAI-Agents-Lauf Erfolg? Nein. Grün heißt: Der Agent ist fertig. Erfolg heißt: Das Ziel, das du benannt hast, hat für diesen Lauf gehalten.

Ersetze ich den nativen Trace-Processor? Nein. Behalte natives Tracing für Spans. Hänge Outcome-Felder daneben an denselben Lauf. Sie arbeiten zusammen.

Was ist ein Produktziel für einen Agent? Eine kurze, geteilte Regel für „fertig“. Zum Beispiel: Antwort ist nicht leer. Belege sind die Felder, die Pass oder Fail zeigen.

Ist die OpenAI-Agents-Integration stabil? Sie ist Beta. Der Wrap und die Idee „Ziel auf dem Lauf“ bleiben. APIs können noch enger werden, während Beispiele reifen.

Weiterführend

Observability für agentische Workflows · Haystack · LangGraph · LangChain