Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Anatomie SDK: Agent, Runner, Tool, Guardrail

Lekce 5 z 25 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Anatomie SDK: Agent, Runner, Tool, Guardrail
  2. Agent: Konfigurace
  3. Runner: Vykonávání
  4. Tool: Schopnosti
  5. Guardrail: Bezpečnost
  6. Jak tyto části spolupracují
  7. Klíčové poznatky

Anatomie SDK: Agent, Runner, Tool, Guardrail

SDK pro agenty stojí na čtyřech základních konceptech: Agent, Runner, Tool a Guardrail. Každý z nich má jedinou odpovědnost. Právě jejich souhra – kdo rozhoduje, kdo vykonává, kdo jedná a kdo řídí – činí SDK čitelným, jakmile si ji osvojíš.

1

Agent – Mozek

Definuje pokyny, model, nástroje a ochranné mechanismy. Toto je konfigurace tvého agenta.

2

Runner – Výkonný engine

Orchestruje smyčku uvažování: odesílá požadavky, spouští nástroje a zpracovává předávání.

3

Tool – Schopnosti

Funkce, které může agent volat: vyhledávání na webu, spouštění kódu, volání API a další.

4

Guardrail – Bezpečnost

Ověřuje vstupy a výstupy agenta. Blokuje nebezpečné nebo nepřípustné požadavky.

Agent: Konfigurace

Třída Agent je čistě deklarativní: nic nespouští, pouze popisuje. Vše, co definuje chování tvého agenta, se nachází na jednom místě.

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
)

Klíčové parametry Agent:

  • name: Čitelný identifikátor agenta pro člověka
  • instructions: Systémový prompt definující chování
  • model: Použitý model (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Seznam dostupných nástrojů
  • handoff_description: Popis používaný při předávání mezi agenty
  • output_type: Typ Pydantic pro strukturování výstupu

Runner: Vykonávání

Runner je engine, který spouští tvého agenta. Spravuje celou smyčku a nabízí tři režimy v závislosti na kontextu volání.

from agents import Runner

# Synchronní režim (vývoj)
result = Runner.run_sync(agent, "What is the price of the widget?")

# Asynchronní režim (produkce)
result = await Runner.run(agent, "What is the price of the widget?")

# Streamovací režim (reálný čas)
result = Runner.run_streamed(agent, "What is the price of the widget?")

Bez ohledu na režim obdržíš objekt RunResult, který obsahuje mnohem více než jen zobrazitelnou odpověď. Úplná historie ti umožňuje pokračovat v konverzaci a atribut last_agent se stává klíčovým, jakmile si agenti začnou předávat úkoly.

result = Runner.run_sync(agent, "What is the price of the widget?")

# Konečná odpověď agenta
print(result.final_output)

# Úplná historie konverzace
print(result.to_input_list())

# Poslední aktivní agent (užitečné při předávání)
print(result.last_agent.name)

Tool: Schopnosti

SDK podporuje tři způsoby definice nástrojů, od nejčastějšího po nejarchitektoničtější.

1. Funkční nástroje (nejčastější)

Dekorovaná funkce Pythonu se stane nástrojem; SDK odvodí schéma z podpisu funkce a dokumentačního řetězce (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é společností OpenAI

Tyto nástroje běží na straně OpenAI: nepíšeš logiku vyhledávání 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 jako nástroje

Jeden agent může používat jiného jako nástroj. Níže uvedený koordinátor deleguje výzkum, aniž by kdy předal kontrolu nad konverzací, což jej odlišuje od předání (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čnost

Guardrail je řídicí agent umístěný před tvým obchodním agentem. Zde ověřovač kontroluje, zda požadavek spadá do oblasti prodeje, než obchodní agent odpoví.

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),
    ],
)

Pokud se guardrail aktivuje (tripwire_triggered=True), vykonávání se zastaví a vyvolá se výjimka InputGuardrailTripwireTriggered. Naplánuj si její zachycení ve své aplikaci; jinak vrátíš uživatelovi, který se pouze zeptal na nepřípustné téma, chybu 500.

Jak tyto části spolupracují

Celý tok probíhá následovně:

  1. Zavoláš Runner.run(agent, message)
  2. Runner zkontroluje vstupní guardrails
  3. Runner odešle zprávu modelu agenta
  4. Pokud model požádá o nástroj, Runner jej spustí
  5. Runner vrátí výsledek modelu (zpět na krok 3)
  6. Když model vytvoří konečnou odpověď, Runner zkontroluje výstupní guardrails
  7. Je vrácen objekt RunResult

Klíčové poznatky

  • Agent definuje chování (pokyny, model, nástroje)
  • Runner orchestruje vykonávání smyčky agenta
  • Nástroje deklaruj pomocí @function_tool, vestavěných tříd nebo .as_tool()
  • Guardrails ověřují vstupy a výstupy z hlediska bezpečnosti
  • RunResult obsahuje konečnou odpověď a úplnou historii