SDK:n anatomia: Agent, Runner, Tool, Guardrail
Tällä sivulla
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.
Agent – Aivot
Määrittelee ohjeet, mallin, työkalut ja turvavälit. Tämä on agenttisi konfiguraatio.
Runner – Suoritusmoottori
Orkestroi päättelysilmukan: lähettää pyynnöt, suorittaa työkalut ja hallitsee siirtymät.
Tool – Ominaisuudet
Funktiot, joita agentti voi kutsua: verkkohaku, koodin suoritus, API-kutsut ja muut.
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 agentilleinstructions: Järjestelmäkehotus, joka määrittelee käyttäytymisenmodel: Käytettävä malli (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Luettelo käytettävissä olevista työkaluistahandoff_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:
- Kutset
Runner.run(agent, message) - Runner tarkistaa syötteen turvavälit
- Runner lähettää viestin agentin mallille
- Jos malli pyytää työkalua, Runner suorittaa sen
- Runner palauttaa tuloksen mallille (palaa vaiheeseen 3)
- Kun malli tuottaa lopullisen vastauksen, Runner tarkistaa tulosteen turvavälit
RunResultpalautetaan
Keskeiset asiat
Agentmäärittelee käyttäytymisen (ohjeet, malli, työkalut)Runnerorkestroi 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
RunResultsisältää lopullisen vastauksen ja koko historian