Anatomija SDK-a: Agent, Runner, Tool, Guardrail
Na ovoj stranici
Anatomija SDK-a: Agent, Runner, Tool, Guardrail
Agents SDK počiva na četiri ključna koncepta: Agent, Runner, Tool i Guardrail. Svaki od njih ima jednu jedinu odgovornost. Njihova međusobna interakcija – tko odlučuje, tko izvršava, tko djeluje, tko kontrolira – ono je što SDK čini čitljivim čim ga internaliziraš.
Agent — Mozak
Definira upute, model, alate i zaštitne mehanizme. Ovo je konfiguracija tvog agenta.
Runner — Izvršni motor
Orkestrira petlju razmišljanja: šalje zahtjeve, izvršava alate i upravlja predajama.
Tool — Mogućnosti
Funkcije koje agent može pozvati: pretraživanje weba, izvršavanje koda, pozivi API-ja i više toga.
Guardrail — Sigurnost
Validira ulaze i izlaze agenta. Blokira opasne ili nebitne zahtjeve.
Agent: Konfiguracija
Klasa Agent je isključivo deklarativna: ona ništa ne pokreće, već opisuje. Sve što definira ponašanje tvog agenta nalazi se na jednom mjestu.
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
)
Ključni parametri za Agent:
name: Identifikator agenta čitljiv ljudimainstructions: Sistemski prompt koji definira ponašanjemodel: Model koji će se koristiti (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Popis dostupnih alatahandoff_description: Opis koji se koristi za predaje između agenataoutput_type: Pydantic tip za strukturiranje izlaza
Runner: Izvršavanje
Runner je motor koji pokreće tvog agenta. Upravlja cijelom petljom i dolazi u tri načina rada, ovisno o kontekstu poziva.
from agents import Runner
# Sinkroni način (razvoj)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asinkroni način (produkcija)
result = await Runner.run(agent, "What is the price of the widget?")
# Način strujanja (stvarno vrijeme)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Bez obzira na način, dobivaš natrag RunResult, koji sadrži mnogo više od same odgovarajuće poruke za prikaz. Potpuna povijest omogućuje ti nastavak razgovora, a last_agent postaje ključan čim više agenata međusobno prenosi kontrolu.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Konačni odgovor agenta
print(result.final_output)
# Potpuna povijest razgovora
print(result.to_input_list())
# Posljednji aktivni agent (korisno kod predaja)
print(result.last_agent.name)
Tool: Mogućnosti
SDK podržava tri načina deklariranja alata, od najčešćeg do najarhitektonskijeg.
1. Funkcijski alati (najčešći)
Dekorirana Python funkcija postaje alat; SDK automatski zaključuje shemu iz potpisa funkcije i docstringa.
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. Alati koje hostira OpenAI
Ovi se alati izvršavaju na strani OpenAI-ja: ne pišeš logiku pretraživanja niti 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 kao alati
Jedan agent može koristiti drugog kao alat. Koordinator u nastavku delegira istraživanje, a da pritom nikada ne prepusti kontrolu nad razgovorom, što ga razlikuje od predaje (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: Sigurnost
Guardrail je kontrolni agent postavljen ispred tvog poslovnog agenta. Ovdje verifier provjerava odnosi li se zahtjev na prodaju prije nego što agent za prodaju odgovori.
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),
],
)
Ako se guardrail aktivira (tripwire_triggered=True), izvršavanje se zaustavlja i baca se iznimka InputGuardrailTripwireTriggered. Planiraj hvatanje ove iznimke u svojoj aplikaciji; u suprotnom, korisniku koji je jednostavno postavio nebitno pitanje vratit ćeš pogrešku 500.
Kako ovi dijelovi međusobno djeluju
Cjelokupni tijek odvija se na sljedeći način:
- Pozoveš
Runner.run(agent, message) - Runner provjerava ulazne guardraile
- Runner šalje poruku modelu agenta
- Ako model zatraži alat, Runner ga izvršava
- Runner vraća rezultat modelu (povratak na korak 3)
- Kada model proizvede konačni odgovor, Runner provjerava izlazne guardraile
- Vraća se
RunResult
Ključne točke
Agentdefinira ponašanje (upute, model, alati)Runnerorkestrira izvršavanje petlje agenta- Alate deklariraj s
@function_tool, ugrađenim klasama ili.as_tool() - Guardraili validiraju ulaze i izlaze radi sigurnosti
RunResultsadrži konačni odgovor i potpunu povijest