Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Anatomija SDK-a: Agent, Runner, Tool, Guardrail

Lekcija 5 od 25 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Anatomija SDK-a: Agent, Runner, Tool, Guardrail
  2. Agent: Konfiguracija
  3. Runner: Izvršavanje
  4. Tool: Mogućnosti
  5. Guardrail: Sigurnost
  6. Kako ovi dijelovi međusobno djeluju
  7. Ključne točke

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

1

Agent — Mozak

Definira upute, model, alate i zaštitne mehanizme. Ovo je konfiguracija tvog agenta.

2

Runner — Izvršni motor

Orkestrira petlju razmišljanja: šalje zahtjeve, izvršava alate i upravlja predajama.

3

Tool — Mogućnosti

Funkcije koje agent može pozvati: pretraživanje weba, izvršavanje koda, pozivi API-ja i više toga.

4

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 ljudima
  • instructions: Sistemski prompt koji definira ponašanje
  • model: Model koji će se koristiti (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Popis dostupnih alata
  • handoff_description: Opis koji se koristi za predaje između agenata
  • output_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:

  1. Pozoveš Runner.run(agent, message)
  2. Runner provjerava ulazne guardraile
  3. Runner šalje poruku modelu agenta
  4. Ako model zatraži alat, Runner ga izvršava
  5. Runner vraća rezultat modelu (povratak na korak 3)
  6. Kada model proizvede konačni odgovor, Runner provjerava izlazne guardraile
  7. Vraća se RunResult

Ključne točke

  • Agent definira ponašanje (upute, model, alati)
  • Runner orkestrira izvršavanje petlje agenta
  • Alate deklariraj s @function_tool, ugrađenim klasama ili .as_tool()
  • Guardraili validiraju ulaze i izlaze radi sigurnosti
  • RunResult sadrži konačni odgovor i potpunu povijest