SDK felépítése: Agent, Runner, Tool, Guardrail
Ezen az oldalon
SDK felépítése: Agent, Runner, Tool, Guardrail
Az Agents SDK négy alapvető koncepcióra épül: Agent, Runner, Tool és Guardrail. Mindegyiknek egyetlen felelőssége van. A kölcsönhatásuk – ki dönt, ki hajt végre, ki cselekszik, ki kontrollál – teszi olvashatóvá az SDK-t, ha egyszer belsővé vált benned.
Agent – Az agy
Meghatározza az utasításokat, a modellt, az eszközöket és a guardraileket. Ez az ügynököd konfigurációja.
Runner – A végrehajtó motor
Orkesztrálja a következtetési ciklust: kéréseket küld, végrehajtja az eszközöket, és kezeli az átadásokat.
Tool – Képességek
Funkciók, amelyeket az ügynök meghívhat: webes keresés, kódvégrehajtás, API-hívások és egyebek.
Guardrail – Biztonság
Érvényesíti az ügynök bemeneteit és kimeneteit. Blokkolja a veszélyes vagy témán kívüli kéréseket.
Agent: Konfiguráció
Az Agent osztály tisztán deklaratív: nem futtat semmit, csak leír. Minden, ami az ügynöd viselkedését meghatározza, egyetlen helyen található.
from agents import Agent, function_tool, WebSearchTool
@function_tool
def get_price(product: str) -> str:
"""Retrieves the price of a product."""
prices = {"widget": "€29.99", "gadget": "€49.99"}
return prices.get(product, "Unknown product")
agent = Agent(
name="Sales Agent",
instructions="""You are a sales agent for an online store.
Help customers find products and learn their prices.
Always respond in French with a professional tone.""",
model="gpt-5.6-terra",
tools=[get_price, WebSearchTool()],
handoff_description="Agent specialized in selling products",
output_type=None, # or a Pydantic type to enforce an output format
)
Főbb Agent paraméterek:
name: Ember által olvasható azonosító az ügynök számárainstructions: A viselkedést meghatározó rendszerutasítás (system prompt)model: A használandó modell (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Az elérhető eszközök listájahandoff_description: Az ügynökök közötti átadásokhoz használt leírásoutput_type: Pydantic típus a kimenet strukturálásához
Runner: Végrehajtás
A Runner az a motor, amely futtatja az ügynöködet. Kezeli a teljes ciklust, és a hívási kontextustól függően három módban érhető el.
from agents import Runner
# Szinkron mód (fejlesztéshez)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Aszinkron mód (éles környezethez)
result = await Runner.run(agent, "What is the price of the widget?")
# Streaming mód (valós idejű)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Függetlenül a módtól, egy RunResult objektumot kapsz vissza, amely sokkal többet tartalmaz, mint a megjeleníthető válasz. A teljes előzmények lehetővé teszik a beszélgetés folytatását, a last_agent pedig akkor válik alapvető fontosságúvá, ha több ügynök adja át egymásnak a feladatot.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Az ügynök végső válasza
print(result.final_output)
# A teljes beszélgetés előzményei
print(result.to_input_list())
# Az utolsó aktív ügynök (hasznos átadásoknál)
print(result.last_agent.name)
Tool: Képességek
Az SDK háromféle módon támogatja az eszközök deklarációját, a leggyakoribbtól a legarchitektonikusabbig.
1. Függvény alapú eszközök (leggyakoribb)
Egy dekorált Python függvény eszközzé válik; az SDK a függvény aláírásából és docstringjéből következteti ki a sémát.
from agents import function_tool
@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
"""Sends an email to a recipient."""
# Your sending logic here
return f"Email sent to {recipient}"
2. Az OpenAI által hostolt eszközök
Ezek az eszközök az OpenAI oldalán futnak: neked nem kell megírnod a keresési logikát vagy a Python homokozót.
from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool
tools = [
WebSearchTool(), # Webes keresés
FileSearchTool(vector_store_ids=["vs_123"]), # Fájlk keresés
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}), # Kódvégrehajtás
]
3. Ügynökök eszközként
Egy ügynök használhat egy másikat eszközként. Az alábbi koordinátor delegálja a kutatást anélkül, hogy valaha is átengedné a beszélgetés irányítását, ami megkülönbözteti ezt egy átadástól (handoff).
search_agent = Agent(
name="Researcher",
instructions="You look up precise information.",
tools=[WebSearchTool()],
)
primary_agent = Agent(
name="Coordinator",
instructions="You coordinate research.",
tools=[search_agent.as_tool(
tool_name="search",
tool_description="Performs in-depth research"
)],
)
Guardrail: Biztonság
A guardrail egy vezérlő ügynök, amelyet az üzleti ügynököd elé helyezel. Itt egy ellenőrző (verifier) megvizsgálja, hogy a kérés a sales területére esik-e, mielőtt a sales ügynök válaszolna.
from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner
guardrail_agent = Agent(
name="Verifier",
instructions="Determine whether the request concerns sales. Respond true or false.",
output_type=bool,
)
async def verify_topic(ctx, agent, input_data):
result = await Runner.run(guardrail_agent, input_data, context=ctx)
return GuardrailFunctionOutput(
output_info=result.final_output,
tripwire_triggered=not result.final_output,
)
protected_agent = Agent(
name="Protected Sales Agent",
instructions="You are a sales agent.",
input_guardrails=[
InputGuardrail(guardrail_function=verify_topic),
],
)
Ha a guardrail aktiválódik (tripwire_triggered=True), a végrehajtás leáll, és egy InputGuardrailTripwireTriggered kivétel dobódik. Tervezd meg, hogy elkapod ezt az alkalmazásodban; ellenkező esetben 500-as hibát küldesz vissza annak a felhasználónak, aki csupán egy témán kívüli kérdést tett fel.
Hogyan lépnek kölcsönhatásba ezek az elemek
A teljes folyamat a következőképpen zajlik:
- Meghívod a
Runner.run(agent, message)függvényt - A Runner ellenőrzi a bemeneti guardraileket
- A Runner elküldi az üzenetet az Agent modelljének
- Ha a modell egy eszközt kér, a Runner végrehajtja azt
- A Runner visszaadja az eredményt a modellnek (vissza a 3. lépéshez)
- Amikor a modell előáll a végső válasszal, a Runner ellenőrzi a kimeneti guardraileket
- A
RunResultvisszaadásra kerül
Főbb megállapítások
- Az
Agenthatározza meg a viselkedést (utasítások, modell, eszközök) - A
Runnerorkesztrálja az ügynök ciklusának végrehajtását - Az eszközöket a
@function_tooldekorátorral, beépített osztályokkal vagy az.as_tool()metódussal deklarálhatod - A Guardrailek biztonsági okokból érvényesítik a bemeneteket és kimeneteket
- A
RunResulttartalmazza a végső választ és a teljes előzményeket