SDK anatoomia: agent, runner, tööriist, turvavöö
Sellel lehel
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.
Agent – aju
Määratleb juhised, mudeli, tööriistad ja turvavööd. See on sinu agendi konfiguratsioon.
Runner – täitmismootor
Koordineerib arutlutsüklit: saadab päringuid, käivitab tööriistu ja haldab üleandmisi.
Tool – võimekused
Funktsioonid, mida agent saab kutsuda: veebiotsing, koodi käivitamine, API-kutsed ja muu.
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 identifikaatorinstructions: süsteemne viip, mis määratleb käitumisemodel: kasutatav mudel (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: saadaolevate tööriistade loendhandoff_description: kirjeldus, mida kasutatakse agentide vahelisteks üleandmisteksoutput_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:
- Kutsume
Runner.run(agent, message) - Runner kontrollib sisendturvavöösid
- Runner saadab sõnumi agendi mudelile
- Kui mudel nõuab tööriista, käivitab Runner selle
- Runner tagastab tulemuse mudelile (tagasi samm 3)
- Kui mudel genereerib lõpliku vastuse, kontrollib Runner väljunditurvavöösid
- Tagastatakse
RunResult
Peamised punktid
Agentmääratleb käitumise (juhised, mudel, tööriistad)Runnerkoordineerib 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
RunResulthoiab lõplikku vastust ja kogu ajalugu