OpenAI Agents SDK: könnyű agent-runtime éles szélekkel

Az OpenAI Agents SDK az a agent-runtime, amelyet az OpenAI Pythonra és TypeScriptra szállít: kevés primitív, egy fordulóciklus, és olyan tracing, amely már azelőtt be van kapcsolva, hogy bárki kérné. Jó alapérték azoknak a csapatoknak, amelyek OpenAI-modellekre egységesülnek, és a ciklust inkább egy könyvtárban, mint kézzel írt asyncióban látják. A rossz eszköz, amint a workflow állapotgéppé válik.

A nyers Responses API és egy teljes оркесztrációs keret közé ül. A Responses API a modell interfésze. Az SDK hozzáad egy runnert, amely a fordulókat, az eszközhívás-végrehajtást, a guardrail-eket, a handoffokat és a sessionöket kezeli. A LangGraphhez hasonló graph runtime-ok mindkettő fölött helyezkednek el, és kifejezetten kódolják a workflow-t. A dokumentáció maga húzza meg a határt: közvetlenül a Responses API-t kell használni, ha a ciklust, az eszköz-végrehajtást és az állapotkezelést saját kezünkbe akarjuk venni.

Mi ez

A felépítés szándékosan vékony. Egy ügynök utasításokból, modellből és eszközökből áll. A delegációnak pontosan két formája van: az Agent.as_tool() egy menedzserhez tartozik, amely megtartja a beszélgetést, a handoff() pedig egy szakemberhez, aki átveszi. A guardrail-ek szokásos függvények, amelyek tripwire-jelzőt adnak vissza. Minden más, a sessionök, az MCP, a sandbox-kliensek, a realtime és a voice, modulok e körül, nem új absztrakció, amit előbb tanulni kellene.

• Csomag: openai-agents a PyPI-on, MIT licenc, Python 3.10 vagy újabb kell hozzá.
• Verzió: 0.23.1, 2026. október 2. A 123. kiadás a 2025. március 4-i 0.0.1 óta; ezekből 77 csak 2026-ban jelent meg.
• Modellek: alapértelmezetten az OpenAI Responses API, alternatívaként a Chat Completions, más szolgáltatókhoz LiteLLM- és AnyLLM-adapter.
• Eszközök: egyszerű Python-függvények a @function_tool dekorátor mögött, továbbá hosztolt eszközök, computer use, shell és apply patch.
• MCP: stdio, Streamable HTTP, az elavult SSE szállítás és hosztolt MCP-szerverek, mindegyik eszköszűrőkkel és jóváhagyási szabályokkal.
• Memória: SQLite, SQLAlchemy, Redis, MongoDB, Dapr, titkosított és az OpenAI Conversations API-re épülő sessionök.
• Tartós végrehajtás: nincs a csomagban; a dokumentáció hosszú futásokhoz Temporal, DBOS, Dapr vagy Restate rendszert ajánl.

Hogyan működik a ciklus

A Runner.run() ciklus, nem függvényhívás. Az aktuális bemenetet elküldi a modellnek, majd a válasszal hármat tesz: a várt kimeneti típusú, eszközhívás nélküli szöveget végső kimenetnek tekinti, handoff esetén másik ügynökre vált, vagy végrehajtja a kért eszközöket, hozzáfűzi az eredményeket, és kezdi újra.

Ezt a végső kimenet definícióját érdemes kétszer elolvasni, mert ez teszi a ciklust ciklussá. Egy futás akkor ér véget, amikor a modell a kért típusú szöveget adja és nem kér semmit. Minden más életben tartja, ezért a max_turns az első beállítás, amit szándékosan kell eldönteni, nem örökölni. A max_turns=None teljesen eltávolítja a korlátot.

Első lépések

A pip install openai-agents az egész beállítás, és az SDK az OPENAI_API_KEY-t az első kliens létrehozásakor olvassa. Egy minimális ügynök egy eszközzel és tipizált válasszal körülbelül húsz sor:

from pydantic import BaseModel

from agents import Agent, Runner, function_tool


@function_tool
def order_status(order_id: str) -> str:
    """Look up the fulfilment status of an order."""
    return STATUS.get(order_id, "unknown")


class Reply(BaseModel):
    answer: str
    order_id: str


agent = Agent(
    name="Order assistant",
    instructions="Answer with the status of the order the customer names.",
    tools=[order_status],
    output_type=Reply,
)

result = Runner.run_sync(agent, "Where is order A-1024?", max_turns=6)
print(result.final_output)
print(result.context_wrapper.usage.total_tokens)

A dekorátor a szignatúrából és a docstringből állítja elő a JSON sémát, így a modell pontosan annyit lát, amennyit a docstring állít. Az output_type validált Pydantic modellt csinál a végső üzenetből string helyett. Az usage összesíti az összes modellhívást a futásban, azokat is, amelyek eszközhívásokat és handoffokat termeltek.

Guardrail-ek és jóváhagyások

A guardrail-eket értik félre a leggyakrabban, mert nem mind ugyanazon a ponton lépnek közbe. A bemeneti guardrail-ek csak a lánc első ügynökére futnak, a kimenetiek csak arra az ügynökre, amelyik a végső kimenetet állítja elő, és egyik sem látja a köztük lévő delegált munkát.

• A run_in_parallel=False egy bemeneti guardrail-on megállítja az ügynököt, mielőtt elindul. Az alapértelmezés az ügynök mellett futtatja a guardrail-t, ami csökkenti a késleltetést, de a tripwire megtelésekor a tokenek már elmentek.
• Az eszköz guardrail-ek egyedi function toolokat és lokális MCP-eszközöket ölelnek körül, és az egyetlen fajta, amely a multi-agent lánc minden hívását látja.
• A tripwire InputGuardrailTripwireTriggered vagy OutputGuardrailTripwireTriggered hibát dob. Ha maga a guardrail-függvény dob, az ítélet ismeretlennek számít, és a runner a hiba megjelenítése előtt menti a befejezett fordulót.
• A needs_approval egy eszközön, az Agent.as_tool() híváson, a ShellTool vagy az ApplyPatchTool eszközön megállítja a futást; a függőben lévő hívások a result.interruptions mezőben jelennek meg.
• A hívható jóváhagyási szabályok zárt ajtóként működnek. Ha az argumentumok hiányoznak, hibásak vagy nem JSON-objektumok, a hívás kézi jóváhagyást igényel, nem megy át automatikusan.

A jóváhagyási állapot a RunState-en keresztül sorosítható, így egy leállt futás egy sorban várakozhat, és másik folyamatban folytatható. A dokumentáció egyértelműen kimondja, hogy a RunState.from_json() nem hitelesít semmit: egy nem megbízható helyen tárolt pillanatkép utasításkészlet, amelyet a szerver végrehajt, ezért szerveroldali tárolóba kell kerüljön, a jóváhagyót pedig az alkalmazásnak kell hitelesítenie. Ez ugyanaz a jóváhagyási minta, mint a human-in-the-loop értékelésben, csak állapotfájl helyett socket.

Tracing és költségkontroll

A tracing a legerősebb érv emellett, és egyben a legkevésbé kontrollált része. A spanek lefedik a runnert, a taskot és a fordulót, minden ügynököt, minden generálást, minden függvényhívást, a guardrail-eket, a handoffokat és a hangot. Az alapértelmezett BatchTraceProcessor a háttérben másodpercenként exportál, így egy worker befejezheti a munkát és kiléphet, mielőtt a dashboard megjeleníti a futást.

• Alapértelmezetten keletkező spanek: runner, task, turn, agent, generation, function, guardrail, handoff, transzkripció és beszéd.
• Globálisan kikapcsolható az OPENAI_AGENTS_DISABLE_TRACING=1 vagy a set_tracing_disabled(True) hívással, egy futásra a RunConfig(tracing_disabled=True) értékkel.
• Szállítási garanciához a flush_traces() hívást a trace kontextus elhagyása után kell meghívni. A tracing kikapcsolása nem dobja el a már pufferezett spaneket.
• Az add_trace_processor() hozzáad egy célpontot, és az OpenAI exportőrt regisztráltan hagyja. A set_trace_processors() lecseréli az alapértelmezést, saját BatchTraceProcessorrel és exportőrrel kell.
• A dokumentáció körülbelül 27 külső processzort sorol fel, köztük a Langfuse-ot, az MLflow-t, az Arize Phoenixot, a LangSmith-et, a Braintrustot, a Datadogot és a Pydantic Logfire-t.

A költségkontroll számolás, nem konfiguráció. A result.context_wrapper.usage a requests, input_tokens, output_tokens, total_tokens értékeket, a kérésenkénti bejegyzéseket, valamint a gyorsítótárazott és reasoning token részleteket tartalmazza; a Responses session tömörítési kérése ugyanazokba az összegekbe kerül. A fontos szám a sikeres futásonkénti költség, és a legnagyobb hatású kar a max_turns, mert egy olyan ciklus, amelynek tizenkét forduló kell a kudarchoz, minden alkalommal tizenkettőt tölt.

Hol csikrik

Kezdjük a gyengeségekkel. A tartós végrehajtás nincs a csomagban: egy olyan futásnak, amelynek túl kell élnie egy folyamat újraindítását, órákig kell várnia jóváhagyásra, vagy új konténerben kell folytatnia, Temporal, DBOS, Dapr vagy Restate kell mellé. A Python szandbox- és harness-munka 0.14.0-ban, 2026 áprilisában érkezett, a TypeScript-támogatást az írás időpontjában még jövőbeli munkaként írta le a vendor. A tracing alapértelmezetten hasznos adatokat küld az OpenAI-nak, és ZDR alatt egyszerűen nem elérhető. És a providerfüggetlenségi állítás halkabb, mint amennyire hangzik: a computer use, a hosted tool search és a programmatic tool calling elutasításra kerül a Chat Completions modelleken és a nem Responses backenden.

Ezután jön a kiadási tempó. A projekt 2026 első kilenc hónapjában hetvenhét kiadást adott ki, és a 0.21.0 az openai>=3.0.0,<4 alsó korlátra emelte, ami az alapértelmezett szolgáltatót HTTPX2-re váltotta, és eltörte azokat az alkalmazásokat, amelyek legacy httpx klienst adtak át. Egy ilyen tempóban továbbra is 0.x verziószámú könyvtár a rögzített verzió és a changelog olvasásának érve, nem a release-címsor olvasásáé.

A negyedik oszlopot olvassa a második előtt. A LangGraph 1.x-nél és az ADK 2.x-nél kompatibilitási ígéret van, a 0.23.1-nél az OpenAI egy patch kiadásban is mozgathat egy konstruktor-aláírást, amit az openai kliens alsó korlátjával már megtett. A vezérlési modell oszlopa kevésbé fontos, mint látszik: egy modellirányított ciklus gyorsabban épül, és egy graph csak addig könnyen követhető, amíg a graph kicsi marad.

Ítélek

Az SDK ott nyer, amit később nehéz pótolni. A tracing, amely már a megfigyelhetőségi kód megírása előtt létezik, a tisztán sorosítható jóváhagyási megszakítások és az MCP négy szállításon át, saját kliens nélkül, mindegyik valódi fejlesztési időt takarít meg. Ott veszít, amit később nem lehet átírás nélkül pótolni: a tartós végrehajtást és azt a kifejezett vezérlési folyamat, amely naprakésszé teszi a workflow-t.

1. Vedd fel, ha a csapat OpenAI-modellekre egységesül, és a workflow egy guardrail-ekkel és jóváhagyásokkal rendelkező eszközciklus. Erre tervezték.
2. Vedd fel, ha a tracing nem tárgyalható, mert a span modell és a dashboard már a runtime-ra van kötve, nem utólag lett ragasztva.
3. Vedd fel MCP-dús ügynökökhöz, ahol a négy szállítás és a szerverenkénti eszköszűrők több kódot spárnak, mint amennyibe a framework kerül.
4. Ne vetted fel egyetlen runtime-ként, ha a futásoknak túl kell élniük egy újraindítást, órákig kell várniuk egy emberre, vagy friss konténerben kell folytatniuk. Párosítsd Temporal-lal vagy DBOS-sel az első naptól.
5. Ne vetted fel olyan workflow-hoz, amelynek következő lépése üzleti szabály. Ha a sorrend ismert, egy graph runtime vagy egyszerű kód őszintébben mondja ki, mint egy modell, amely talán nem is követi.
6. Hagyd ki teljesen, ha az egész feladat egy modellhívás, amely egyetlen választ ad. A Responses API plusz Pydantic kisebb és olcsóbb.

Ebből semmi nem hibája a csomagnak. Ez egy kis, olvasható, MIT-licencű könyvtár, amely egy szűk feladatot rendesen elvégez, és ezt a saját dokumentációjában be is mondja. Az elkerülendő hiba nem az, hogy ezt választod, hanem hogy azért választod, mert a tracing ingyenes, és egy év múlva felderül, hogy a workflow logika olyan promptokban él, amelyeket senki nem diffel. A tartós végrehajtás és az üzleti szabályok maradjanak a runneren kívül.

Elég funkció ahhoz, hogy érdemes legyen használni, de elég kevés primitív ahhoz, hogy gyorsan megtanulható legyen. — a két tervezési alapelv az OpenAI Agents SDK dokumentációjából.

Források

1. OpenAI Agents SDK documentation
2. OpenAI Agents SDK documentation
3. OpenAI Agents SDK documentation
4. OpenAI Agents SDK documentation
5. OpenAI Agents SDK documentation
6. OpenAI Agents SDK documentation
7. openai-agents 0.23.1 on PyPI, release history and licence
8. OpenAI
9. OpenAI API documentation
10. Arize