SDK Anatomija: Aģents, Izpildītājs, Rīks, Drošības barjera
Šajā lapā
SDK Anatomija: Aģents, Izpildītājs, Rīks, Drošības barjera
Aģentu SDK balstās uz četriem pamatjēdzieniem: Aģents, Izpildītājs (Runner), Rīks un Drošības barjera (Guardrail). Katram no tiem ir viens konkrēts uzdevums. Tieši to mijiedarbība – kurš pieņem lēmumus, kurš izpilda, kurš darbojas un kurš kontrolē – padara SDK saprotamu, tiklīdz to esi apguvis.
Aģents — Smadzenes
Definē instrukcijas, modeli, rīkus un drošības barjeras. Šī ir tava aģenta konfigurācija.
Izpildītājs — Izpildes dzinējs
Vada spriešanas ciklu: sūta pieprasījumus, izpilda rīkus un apstrādā nodošanu starp aģentiem.
Rīks — Iespējas
Funkcijas, ko aģents var izsaukt: meklēšana tīmeklī, koda izpilde, API izsaukumi un citas.
Drošības barjera — Drošība
Pārbauda aģenta ievades un izvades. Bloķē bīstamus vai no tēmas novirzītus pieprasījumus.
Aģents: Konfigurācija
Klase Agent ir tikai deklaratīva: tā neko nepalina, tā tikai apraksta. Viss, kas definē tava aģenta uzvedību, atrodas vienā vietā.
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
)
Galvenie Agent parametri:
name: Cilvēkam lasāms aģenta identifikatorsinstructions: Sistēmas uzvedne, kas definē uzvedībumodel: Izmantojamais modelis (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Pieejamo rīku sarakstshandoff_description: Apraksts, ko izmanto, nododot vadību starp aģentiemoutput_type: Pydantic tips, lai strukturētu izvadi
Izpildītājs: Izpilde
Runner ir dzinējs, kas palaiž tavu aģentu. Tas pārvalda visu ciklu un darbojas trīs režīmos atkarībā no izsaukuma konteksta.
from agents import Runner
# Sinhronais režīms (izstrāde)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asinhronais režīms (produkcija)
result = await Runner.run(agent, "What is the price of the widget?")
# Straumēšanas režīms (reāllaiks)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Neatkarīgi no režīma tu saņem atpakaļ RunResult, kas satur daudz vairāk nekā tikai attēlojamo atbildi. Pilnā vēsture ļauj atsākt sarunu, bet last_agent kļūst būtisks, tiklīdz vairāki aģenti nodod vadību viens otram.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Aģenta beigu atbilde
print(result.final_output)
# Pilna sarunas vēsture
print(result.to_input_list())
# Pēdējais aktīvais aģents (noderīgi, nododot vadību)
print(result.last_agent.name)
Rīks: Iespējas
SDK atbalsta trīs veidus, kā deklarēt rīkus, sākot no visbiežāk lietotā līdz arhitektūras ziņā sarežģītākajam.
1. Funkciju rīki (visbiežāk lietotie)
Dekorēta Python funkcija kļūst par rīku; SDK automātiski ģenerē shēmu, balstoties uz funkcijas parakstu un dokumentācijas virkni.
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 mitināti rīki
Šie rīki darbojas OpenAI pusē: tev nav jāraksta meklēšanas loģika vai Python smilškaste.
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. Aģenti kā rīki
Viens aģents var izmantot citu kā rīku. Tālāk redzamais koordinators deleģē pētniecību, nekad neatdodot sarunas kontroli, kas to atšķir no vadības nodošanas (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"
)],
)
Drošības barjera: Drošība
Drošības barjera ir kontrolaģents, kas novietots priekšā tavam biznesa aģentam. Šeit verificētājs pārbauda, vai pieprasījums attiecas uz pārdošanu, pirms pārdošanas aģents sniedz atbildi.
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),
],
)
Ja drošības barjera iedarbojas (tripwire_triggered=True), izpilde tiek apturēta un tiek izraisīts izņēmums InputGuardrailTripwireTriggered. Plāno to noķert savā lietotnē; pretējā gadījumā lietotājam, kurš vienkārši uzdeva jautājumu ne par tēmu, tu atgriezīsi 500 kļūdu.
Kā šīs daļas mijiedarbojas
Pilns process norisinās šādi:
- Tu izsauc
Runner.run(agent, message) - Izpildītājs pārbauda ievades drošības barjeras
- Izpildītājs nosūta ziņojumu aģenta modelim
- Ja modelis pieprasa rīku, Izpildītājs to izpilda
- Izpildītājs atgriež rezultātu modelim (atgriežas pie 3. solņa)
- Kad modelis ģenerē galīgo atbildi, Izpildītājs pārbauda izvades drošības barjeras
- Tiek atgriezts
RunResult
Galvenās atziņas
Agentdefinē uzvedību (instrukcijas, modelis, rīki)Runnerorganizē aģenta cikla izpildi- Deklarē rīkus, izmantojot
@function_tool, iebūvētās klases vai.as_tool() - Drošības barjeras pārbauda ievades un izvades drošībai
RunResultsatur galīgo atbildi un pilnu vēsturi