Anatomie SDK: Agent, Runner, Tool, Guardrail
Na této stránce
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íš.
Agent – Mozek
Definuje pokyny, model, nástroje a ochranné mechanismy. Toto je konfigurace tvého agenta.
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í.
Tool – Schopnosti
Funkce, které může agent volat: vyhledávání na webu, spouštění kódu, volání API a další.
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ěkainstructions: 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 agentyoutput_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ě:
- Zavoláš
Runner.run(agent, message) - Runner zkontroluje vstupní guardrails
- Runner odešle zprávu modelu agenta
- Pokud model požádá o nástroj, Runner jej spustí
- Runner vrátí výsledek modelu (zpět na krok 3)
- Když model vytvoří konečnou odpověď, Runner zkontroluje výstupní guardrails
- Je vrácen objekt
RunResult
Klíčové poznatky
Agentdefinuje chování (pokyny, model, nástroje)Runnerorchestruje 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
RunResultobsahuje konečnou odpověď a úplnou historii