Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

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

Lekcija 5 od 25 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Anatomija SDK-ja: Agent, Runner, Tool, Guardrail
  2. Agent: Konfiguracija
  3. Runner: Izvajanje
  4. Tool: Zmožnosti
  5. Guardrail: Varnost
  6. Kako ti deli medsebojno delujejo
  7. Ključne ugotovitve

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

SDK za agente temelji na štirih osnovnih konceptih: Agent, Runner, Tool in Guardrail. Vsak ima eno samo odgovornost. Njihovo medsebojno delovanje – kdo odloča, kdo izvaja, kdo deluje in kdo nadzira – je tisto, zaradi česar je SDK berljiv, ko ga enkrat ponotranjiš.

1

Agent — Možgani

Določa navodila, model, orodja in varnostne omejitve. To je konfiguracija tvojega agenta.

2

Runner — Izvedbeni pogon

Usklajuje zanko razmišljanja: pošilja zahteve, izvaja orodja in upravlja predaje.

3

Tool — Zmožnosti

Funkcije, ki jih lahko agent kliče: iskanje po spletu, izvajanje kode, klici API-jev in drugo.

4

Guardrail — Varnost

Preverja vhode in izhode agenta. Blokira nevarne ali irelevantne zahteve.

Agent: Konfiguracija

Razred Agent je zgolj deklarativen: ničesar ne izvaja, le opisuje. Vse, kar določa obnašanje tvojega agenta, se nahaja na enem mestu.

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 razreda Agent:

  • name: Človeku berljiv identifikator agenta
  • instructions: Sistemski poziv, ki določa obnašanje
  • model: Model za uporabo (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Seznam razpoložljivih orodij
  • handoff_description: Opis, ki se uporablja za predaje med agenti
  • output_type: Tip Pydantic za strukturiranje izhoda

Runner: Izvajanje

Runner je pogon, ki poganja tvojega agenta. Upravlja celotno zanko in je na voljo v treh načinih, odvisno od konteksta klica.

from agents import Runner

# Sinhroni način (razvoj)
result = Runner.run_sync(agent, "What is the price of the widget?")

# Asinhroni način (produkcija)
result = await Runner.run(agent, "What is the price of the widget?")

# Način pretakanja (realni čas)
result = Runner.run_streamed(agent, "What is the price of the widget?")

Ne glede na način dobiš nazaj RunResult, ki vsebuje veliko več kot le odziv, prikazan uporabniku. Polna zgodovina ti omogoča nadaljevanje pogovora, last_agent pa postane ključen takoj, ko več agentov začne medsebojno predajati naloge.

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

# Končni odziv agenta
print(result.final_output)

# Celotna zgodovina pogovora
print(result.to_input_list())

# Zadnji aktivni agent (uporabno pri predajah)
print(result.last_agent.name)

Tool: Zmožnosti

SDK podpira tri načine deklariranja orodij, od najpogostejšega do najbolj arhitekturnega.

1. Funkcijska orodja (najpogostejše)

Okrasena funkcija Python postane orodje; SDK samodejno sklepa shemo iz podpisa funkcije in dokumentacijskega niza (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. Orodja, ki jih gostuje OpenAI

Ta orodja delujejo na strani OpenAI: logike iskanja ali peskovnika Python ne pišeš sam.

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 kot orodja

En agent lahko uporabi drugega kot orodje. Spodnji koordinator delegira raziskovanje, ne da bi kdajkoli prepustil nadzor nad pogovorom, kar to 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: Varnost

Guardrail je nadzorni agent, postavljen pred tvoj poslovni agent. Tu preverjevalec ugotovi, ali zahteva spada v področje prodaje, preden prodajni agent 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),
    ],
)

Če se guardrail sproži (tripwire_triggered=True), se izvajanje ustavi in sproži izjema InputGuardrailTripwireTriggered. Načrtuj ujemanje te izjeme v svoji aplikaciji; v nasprotnem primeru boš uporabniku, ki je postavil le irelevantno vprašanje, vrnil napako 500.

Kako ti deli medsebojno delujejo

Celoten potek deluje takole:

  1. Pokličeš Runner.run(agent, message)
  2. Runner preveri vhodne varnostne omejitve (input guardrails)
  3. Runner pošlje sporočilo modelu agenta
  4. Če model zahteva orodje, ga Runner izvede
  5. Runner vrne rezultat modelu (nazaj na korak 3)
  6. Ko model ustvari končni odziv, Runner preveri izhodne varnostne omejitve (output guardrails)
  7. Vrni se RunResult

Ključne ugotovitve

  • Agent določa obnašanje (navodila, model, orodja)
  • Runner usklajuje izvajanje zanke agenta
  • Orodja deklariraj z @function_tool, vgrajenimi razredi ali .as_tool()
  • Guardrails preverjajo vhode in izhode zaradi varnosti
  • RunResult vsebuje končni odziv in celotno zgodovino