Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

SDK:n anatomia: Agent, Runner, Tool, Guardrail

Oppitunti 5 / 25 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. SDK:n anatomia: Agent, Runner, Tool, Guardrail
  2. Agent: Konfiguraatio
  3. Runner: Suoritus
  4. Tool: Ominaisuudet
  5. Guardrail: Turvallisuus
  6. Miten nämä osat toimivat yhdessä
  7. Keskeiset asiat

SDK:n anatomia: Agent, Runner, Tool, Guardrail

Agents SDK perustuu neljään ydinkäsitteeseen: Agent, Runner, Tool ja Guardrail. Jokaisella on yksi selkeä vastuualue. Niiden yhteispeli – kuka päättää, kuka suorittaa, kuka toimii ja kuka valvoo – tekee SDK:sta helposti luettavan, kun sisäistät sen logiikan.

1

Agent – Aivot

Määrittelee ohjeet, mallin, työkalut ja turvavälit. Tämä on agenttisi konfiguraatio.

2

Runner – Suoritusmoottori

Orkestroi päättelysilmukan: lähettää pyynnöt, suorittaa työkalut ja hallitsee siirtymät.

3

Tool – Ominaisuudet

Funktiot, joita agentti voi kutsua: verkkohaku, koodin suoritus, API-kutsut ja muut.

4

Guardrail – Turvallisuus

Validoi agentin syötteet ja tulosteet. Estää vaaralliset tai aiheeseen kuulumattomat pyynnöt.

Agent: Konfiguraatio

Agent-luokka on puhtaasti deklaratiivinen: se ei suorita mitään, vaan kuvaa. Kaikki, mikä määrittelee agenttisi käyttäytymisen, sijaitsee yhdessä paikassa.

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
)

Keskeiset Agent-parametrit:

  • name: Ihmiselle luettava tunniste agentille
  • instructions: Järjestelmäkehotus, joka määrittelee käyttäytymisen
  • model: Käytettävä malli (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Luettelo käytettävissä olevista työkaluista
  • handoff_description: Kuvaus, jota käytetään siirryttäessä agenttien välillä
  • output_type: Pydantic-tyyppi tulosteen rakenteen pakottamiseksi

Runner: Suoritus

Runner on moottori, joka ajaa agenttisi. Se hallitsee koko silmukan ja toimii kolmessa tilassa kutsukontekstistasi riippuen.

from agents import Runner

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

# Asynkroninen tila (tuotanto)
result = await Runner.run(agent, "What is the price of the widget?")

# Streamaus-tila (reaaliaika)
result = Runner.run_streamed(agent, "What is the price of the widget?")

Tilasta riippumatta saat takaisin RunResult-objektin, joka sisältää paljon enemmän kuin vain näytettävän vastauksen. Täysi historia mahdollistaa keskustelun jatkamisen, ja last_agent muuttuu oleelliseksi heti, kun useat agentit siirtävät vastuuta toisilleen.

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

# Agentin lopullinen vastaus
print(result.final_output)

# Koko keskusteluhistoria
print(result.to_input_list())

# Viimeisin aktiivinen agentti (hyödyllinen siirtymien kanssa)
print(result.last_agent.name)

Tool: Ominaisuudet

SDK tukee kolmea tapaa määritellä työkaluja yleisimmästä arkkitehtonisimpaan.

1. Funktiotyökalut (yleisin)

Koristeltu Python-funktio muuttuu työkaluksi; SDK päättelee skeeman allekirjoituksesta ja docstringistä.

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:n isännöimät työkalut

Nämä työkalut suoritetaan OpenAI:n puolella: et kirjoita hakulogiikkaa tai Python-hiekkalaatikkoa itse.

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. Agentit työkaluina

Yksi agentti voi käyttää toista työkaluna. Alla oleva koordinaattori delegoi tutkimustyön luovuttamatta koskaan keskustelun hallintaa, mikä erottaa tämän siirtymästä (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: Turvallisuus

Guardrail on valvova agentti, joka sijoitetaan business-agenttisi eteen. Tässä varmentaja tarkistaa, kuuluuko pyyntö myyntiin, ennen kuin myyntiagentti vastaa.

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

Jos guardrail laukeaa (tripwire_triggered=True), suoritus pysähtyy ja InputGuardrailTripwireTriggered-poikkeus heitetään. Suunnittele tämän käsittely sovellukseesi; muuten palautat 500-virheen käyttäjälle, joka esitti vain aiheeseen kuulumattoman kysymyksen.

Miten nämä osat toimivat yhdessä

Koko virta etenee seuraavasti:

  1. Kutset Runner.run(agent, message)
  2. Runner tarkistaa syötteen turvavälit
  3. Runner lähettää viestin agentin mallille
  4. Jos malli pyytää työkalua, Runner suorittaa sen
  5. Runner palauttaa tuloksen mallille (palaa vaiheeseen 3)
  6. Kun malli tuottaa lopullisen vastauksen, Runner tarkistaa tulosteen turvavälit
  7. RunResult palautetaan

Keskeiset asiat

  • Agent määrittelee käyttäytymisen (ohjeet, malli, työkalut)
  • Runner orkestroi agenttisilmukan suorituksen
  • Määrittele työkalut käyttämällä @function_tool, sisäänrakennettuja luokkia tai .as_tool()-metodia
  • Guardrailit validoivat syötteet ja tulosteet turvallisuuden vuoksi
  • RunResult sisältää lopullisen vastauksen ja koko historian