Anatomija SDK-ja: Agent, Runner, Tool, Guardrail
Na tej strani
Anatomija SDK-ja: Agent, Runner, Tool, Guardrail
SDK za agente temelji na štirih osnovnih konceptih: Agent, Runner, Tool in Guardrail. Vsak ima eno samo odgovornost. Njihovo medsebojno delovanje – kdo odloča, kdo izvaja, kdo deluje in kdo nadzira – je tisto, zaradi česar je SDK berljiv, ko ga enkrat ponotranjiš.
Agent — Možgani
Določa navodila, model, orodja in varnostne omejitve. To je konfiguracija tvojega agenta.
Runner — Izvedbeni pogon
Usklajuje zanko razmišljanja: pošilja zahteve, izvaja orodja in upravlja predaje.
Tool — Zmožnosti
Funkcije, ki jih lahko agent kliče: iskanje po spletu, izvajanje kode, klici API-jev in drugo.
Guardrail — Varnost
Preverja vhode in izhode agenta. Blokira nevarne ali irelevantne zahteve.
Agent: Konfiguracija
Razred Agent je zgolj deklarativen: ničesar ne izvaja, le opisuje. Vse, kar določa obnašanje tvojega agenta, se nahaja na enem mestu.
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
)
Ključni parametri razreda Agent:
name: Človeku berljiv identifikator agentainstructions: Sistemski poziv, ki določa obnašanjemodel: Model za uporabo (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Seznam razpoložljivih orodijhandoff_description: Opis, ki se uporablja za predaje med agentioutput_type: Tip Pydantic za strukturiranje izhoda
Runner: Izvajanje
Runner je pogon, ki poganja tvojega agenta. Upravlja celotno zanko in je na voljo v treh načinih, odvisno od konteksta klica.
from agents import Runner
# Sinhroni način (razvoj)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asinhroni način (produkcija)
result = await Runner.run(agent, "What is the price of the widget?")
# Način pretakanja (realni čas)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Ne glede na način dobiš nazaj RunResult, ki vsebuje veliko več kot le odziv, prikazan uporabniku. Polna zgodovina ti omogoča nadaljevanje pogovora, last_agent pa postane ključen takoj, ko več agentov začne medsebojno predajati naloge.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Končni odziv agenta
print(result.final_output)
# Celotna zgodovina pogovora
print(result.to_input_list())
# Zadnji aktivni agent (uporabno pri predajah)
print(result.last_agent.name)
Tool: Zmožnosti
SDK podpira tri načine deklariranja orodij, od najpogostejšega do najbolj arhitekturnega.
1. Funkcijska orodja (najpogostejše)
Okrasena funkcija Python postane orodje; SDK samodejno sklepa shemo iz podpisa funkcije in dokumentacijskega niza (docstring).
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. Orodja, ki jih gostuje OpenAI
Ta orodja delujejo na strani OpenAI: logike iskanja ali peskovnika Python ne pišeš sam.
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. Agenti kot orodja
En agent lahko uporabi drugega kot orodje. Spodnji koordinator delegira raziskovanje, ne da bi kdajkoli prepustil nadzor nad pogovorom, kar to razlikuje od predaje (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: Varnost
Guardrail je nadzorni agent, postavljen pred tvoj poslovni agent. Tu preverjevalec ugotovi, ali zahteva spada v področje prodaje, preden prodajni agent odgovori.
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),
],
)
Če se guardrail sproži (tripwire_triggered=True), se izvajanje ustavi in sproži izjema InputGuardrailTripwireTriggered. Načrtuj ujemanje te izjeme v svoji aplikaciji; v nasprotnem primeru boš uporabniku, ki je postavil le irelevantno vprašanje, vrnil napako 500.
Kako ti deli medsebojno delujejo
Celoten potek deluje takole:
- Pokličeš
Runner.run(agent, message) - Runner preveri vhodne varnostne omejitve (input guardrails)
- Runner pošlje sporočilo modelu agenta
- Če model zahteva orodje, ga Runner izvede
- Runner vrne rezultat modelu (nazaj na korak 3)
- Ko model ustvari končni odziv, Runner preveri izhodne varnostne omejitve (output guardrails)
- Vrni se
RunResult
Ključne ugotovitve
Agentdoloča obnašanje (navodila, model, orodja)Runnerusklajuje izvajanje zanke agenta- Orodja deklariraj z
@function_tool, vgrajenimi razredi ali.as_tool() - Guardrails preverjajo vhode in izhode zaradi varnosti
RunResultvsebuje končni odziv in celotno zgodovino