Lähe põhisisu juurde
Eesti— Vali keel
Menüü

SDK anatoomia: agent, runner, tööriist, turvavöö

Õppetund 5 / 25 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. SDK anatoomia: agent, runner, tööriist, turvavöö
  2. Agent: konfiguratsioon
  3. Runner: täitmine
  4. Tool: võimekused
  5. Guardrail: ohutus
  6. Kuidas need osad koos toimivad
  7. Peamised punktid

SDK anatoomia: agent, runner, tööriist, turvavöö

Agents SDK põhineb neljal põhikontseptsioonil: Agent, Runner, Tool ja Guardrail. Igal neist on üks kindel ülesanne. Just nende koostoime – kes otsustab, kes täidab, kes tegutseb ja kes kontrollib – muudab SDK loetavaks, kui oled selle omaks võtnud.

1

Agent – aju

Määratleb juhised, mudeli, tööriistad ja turvavööd. See on sinu agendi konfiguratsioon.

2

Runner – täitmismootor

Koordineerib arutlutsüklit: saadab päringuid, käivitab tööriistu ja haldab üleandmisi.

3

Tool – võimekused

Funktsioonid, mida agent saab kutsuda: veebiotsing, koodi käivitamine, API-kutsed ja muu.

4

Guardrail – ohutus

Kontrollib agendi sisendeid ja väljundeid. Blokeerib ohtlikud või teemast kõrvalekalduvad päringud.

Agent: konfiguratsioon

Klass Agent on puhtalt deklaratiiivne: see ei käivita midagi, vaid kirjeldab. Kõik, mis määratleb sinu agendi käitumise, asub ühes kohas.

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
)

Peamised Agent parameetrid:

  • name: inimesele loetav agendi identifikaator
  • instructions: süsteemne viip, mis määratleb käitumise
  • model: kasutatav mudel (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: saadaolevate tööriistade loend
  • handoff_description: kirjeldus, mida kasutatakse agentide vahelisteks üleandmisteks
  • output_type: Pydantici tüüp väljundi struktureerimiseks

Runner: täitmine

Runner on mootor, mis käivitab sinu agendi. See haldab kogu tsüklit ja pakub kolme režiimi sõltuvalt sinu kutsekontekstist.

from agents import Runner

# Sünkroonne režiim (arendus)
result = Runner.run_sync(agent, "What is the price of the widget?")

# Asünkroonne režiim (tootmine)
result = await Runner.run(agent, "What is the price of the widget?")

# Voogedastusrežiim (reaalaeg)
result = Runner.run_streamed(agent, "What is the price of the widget?")

Sõltumata režiimist saad tagasi RunResult, mis sisaldab palju enamat kui ainult kuvatavat vastust. Täielik ajalugu võimaldab vestlust jätkata ja last_agent muutub hädavajalikuks niipea, kui mitu agentt annavad ülesandeid üksteisele üle.

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

# Agendi lõplik vastus
print(result.final_output)

# Kogu vestluse ajalugu
print(result.to_input_list())

# Viimane aktiivne agent (kasulik üleandmistel)
print(result.last_agent.name)

Tool: võimekused

SDK toetab tööriistade deklareerimist kolmel viisil, levinumast kuni arhitektuurilisemani.

1. Funktsioonitööriistad (levinuim)

Dekoreeritud Pythoni funktsioonist saab tööriist; SDK tuletab skeemi allkirjast ja dokumendistringist.

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. OpenAI poolt majutatud tööriistad

Need tööriistad töötavad OpenAI poolel: sa ei kirjuta otsinguloogikat ega Pythoni liivakasti.

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. Agendid tööriistadena

Üks agent saab kasutada teist tööriistana. Allpool olev koordinaator delegeerib uurimistööd loovutamata kunagi vestluse kontrolli, mis eristab seda üleandmisest.

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: ohutus

Turvavöö on juhtagent, mis asetatakse sinu äriagendi ette. Siin kontrollib verifitseerija, kas päring kuulub müügi valdkonda, enne kui müügiagent vastab.

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

Kui turvavöö käivitub (tripwire_triggered=True), peatub täitmine ja tõstetakse erind InputGuardrailTripwireTriggered. Planeeri see oma rakenduses püüda; vastasel juhul tagastad kasutajale, kes esitas lihtsalt teemavälise küsimuse, 500 vea.

Kuidas need osad koos toimivad

Täielik voog kulgeb järgmiselt:

  1. Kutsume Runner.run(agent, message)
  2. Runner kontrollib sisendturvavöösid
  3. Runner saadab sõnumi agendi mudelile
  4. Kui mudel nõuab tööriista, käivitab Runner selle
  5. Runner tagastab tulemuse mudelile (tagasi samm 3)
  6. Kui mudel genereerib lõpliku vastuse, kontrollib Runner väljunditurvavöösid
  7. Tagastatakse RunResult

Peamised punktid

  • Agent määratleb käitumise (juhised, mudel, tööriistad)
  • Runner koordineerib agendi tsükli täitmist
  • Deklareeri tööriistu kasutades @function_tool, sisseehitatud klasse või .as_tool()
  • Turvavööd valideerivad ohutuse huvides sisendeid ja väljundeid
  • RunResult hoiab lõplikku vastust ja kogu ajalugu