Anatómia SDK: Agent, Runner, Tool, Guardrail
Na tejto strane
Anatómia SDK: Agent, Runner, Tool, Guardrail
SDK pre agentov stojí na štyroch kľúčových konceptoch: Agent, Runner, Tool a Guardrail. Každý z nich má jedinú zodpovednosť. Práve ich súhra – kto rozhoduje, kto vykonáva, kto koná a kto kontroluje – robí SDK čitateľným, akonáhle si tieto pojmy osvojíš.
Agent – Mozog
Definuje inštrukcie, model, nástroje a ochranné mechanizmy. Toto je konfigurácia tvojho agenta.
Runner – Vykonávací engine
Orchestruje cyklus uvažovania: odosiela požiadavky, vykonáva nástroje a riadi odovzdávanie úloh.
Tool – Schopnosti
Funkcie, ktoré môže agent volať: vyhľadávanie na webe, vykonávanie kódu, volania API a ďalšie.
Guardrail – Bezpečnosť
Overuje vstupy a výstupy agenta. Blokuje nebezpečné alebo tematicky nepatričné požiadavky.
Agent: Konfigurácia
Trieda Agent je čisto deklaratívna: nič nespúšťa, iba opisuje. Všetko, čo definuje správanie tvojho agenta, sa nachádza na jednom mieste.
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
)
Kľúčové parametre triedy Agent:
name: Čitateľný identifikátor agenta pre človekainstructions: Systémový prompt, ktorý definuje správaniemodel: Model, ktorý sa má použiť (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Zoznam dostupných nástrojovhandoff_description: Popis používaný pri odovzdávaní úloh medzi agentmioutput_type: Typ Pydantic na štruktúrovanie výstupu
Runner: Vykonávanie
Runner je engine, ktorý spúšťa tvojho agenta. Riadi celý cyklus a ponúka tri režimy v závislosti od kontextu volania.
from agents import Runner
# Synchronický režim (vývoj)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asynchrónny režim (produkcia)
result = await Runner.run(agent, "What is the price of the widget?")
# Streamovací režim (reálny čas)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Bez ohľadu na režim dostaneš späť objekt RunResult, ktorý obsahuje oveľa viac než len zobraziteľnú odpoveď. Úplná história ti umožňuje pokračovať v konverzácii a atribút last_agent sa stáva kľúčovým hneď, ako si agenti navzájom odovzdávajú úlohy.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Konečná odpoveď agenta
print(result.final_output)
# Úplná história konverzácie
print(result.to_input_list())
# Posledný aktívny agent (užitočné pri odovzdávaní úloh)
print(result.last_agent.name)
Tool: Schopnosti
SDK podporuje tri spôsoby definovania nástrojov, od najbežnejšieho po najviac architektonický.
1. Funkčné nástroje (najbežnejšie)
Dekorovaná funkcia v Pythone sa stane nástrojom; SDK automaticky odvodia schému z podpisu funkcie a dokumentačného reťazca (docstring).
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. Nástroje hostované spoločnosťou OpenAI
Tieto nástroje bežia na strane OpenAI: nepíšeš logiku vyhľadávania ani Python sandbox.
from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool
tools = [
WebSearchTool(), # Web search
FileSearchTool(vector_store_ids=["vs_123"]), # File search
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}), # Code execution
]
3. Agenti ako nástroje
Jeden agent môže používať iného ako nástroj. Nižšie uvedený koordinátor deleguje výskum, nikdy však nepreberá kontrolu nad konverzáciou, čo ho odlišuje od odovzdania úlohy (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: Bezpečnosť
Guardrail je kontrolný agent umiestnený pred tvojim business agentom. Tu overovateľ kontroluje, či požiadavka spadá do oblasti predaja, ešte predtým, ako odpovie predajný agent.
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),
],
)
Ak sa guardrail aktivuje (tripwire_triggered=True), vykonávanie sa zastaví a vyhodí sa výnimka InputGuardrailTripwireTriggered. Naplánuj si jej zachytenie vo svojej aplikácii; inak vrátiš používateľovi chybu 500 len preto, že sa opýtal na nepatričnú tému.
Ako tieto časti spolupracujú
Celý tok prebieha nasledovne:
- Zavoláš
Runner.run(agent, message) - Runner skontroluje vstupné guardraily
- Runner odošle správu modelu agenta
- Ak model požaduje nástroj, Runner ho vykoná
- Runner vráti výsledok modelu (návrat na krok 3)
- Keď model vygeneruje konečnú odpoveď, Runner skontroluje výstupné guardraily
- Vrátia sa výsledky
RunResult
Kľúčové poznatky
Agentdefinuje správanie (inštrukcie, model, nástroje)Runnerorchestruje vykonávanie cyklu agenta- Nástroje deklaruj pomocou
@function_tool, vstavaných tried alebo.as_tool() - Guardraily overujú vstupy a výstupy kvôli bezpečnosti
RunResultobsahuje konečnú odpoveď a úplnú históriu