Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Anatómia SDK: Agent, Runner, Tool, Guardrail

Lekcia 5 z 25 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Anatómia SDK: Agent, Runner, Tool, Guardrail
  2. Agent: Konfigurácia
  3. Runner: Vykonávanie
  4. Tool: Schopnosti
  5. Guardrail: Bezpečnosť
  6. Ako tieto časti spolupracujú
  7. Kľúčové poznatky

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íš.

1

Agent – Mozog

Definuje inštrukcie, model, nástroje a ochranné mechanizmy. Toto je konfigurácia tvojho agenta.

2

Runner – Vykonávací engine

Orchestruje cyklus uvažovania: odosiela požiadavky, vykonáva nástroje a riadi odovzdávanie úloh.

3

Tool – Schopnosti

Funkcie, ktoré môže agent volať: vyhľadávanie na webe, vykonávanie kódu, volania API a ďalšie.

4

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 človeka
  • instructions: Systémový prompt, ktorý definuje správanie
  • model: Model, ktorý sa má použiť (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Zoznam dostupných nástrojov
  • handoff_description: Popis používaný pri odovzdávaní úloh medzi agentmi
  • output_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:

  1. Zavoláš Runner.run(agent, message)
  2. Runner skontroluje vstupné guardraily
  3. Runner odošle správu modelu agenta
  4. Ak model požaduje nástroj, Runner ho vykoná
  5. Runner vráti výsledok modelu (návrat na krok 3)
  6. Keď model vygeneruje konečnú odpoveď, Runner skontroluje výstupné guardraily
  7. Vrátia sa výsledky RunResult

Kľúčové poznatky

  • Agent definuje správanie (inštrukcie, model, nástroje)
  • Runner orchestruje 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
  • RunResult obsahuje konečnú odpoveď a úplnú históriu