SDK-anatomi: Agent, Runner, Tool, Guardrail
På denne side
SDK-anatomi: Agent, Runner, Tool, Guardrail
Agents SDK hviler på fire kernebegreber: Agent, Runner, Tool og Guardrail. Hver har ét enkelt ansvar. Det er deres samspil – hvem der beslutter, hvem der udfører, hvem der handler, og hvem der styrer – der gør SDK’et læseligt, når du først har internaliseret det.
Agent – Hjernen
Definerer instrukser, model, værktøjer og guardrails. Dette er din agents konfiguration.
Runner – Eksekveringsmotoren
Orkestrerer ræsonnementsløkken: sender anmodninger, udfører værktøjer og håndterer overgivelser.
Tool – Egenskaber
Funktioner, som agenten kan kalde: websøgning, kodeeksekvering, API-kald og mere.
Guardrail – Sikkerhed
Validerer agentens input og output. Blokerer farlige eller emnefremmede anmodninger.
Agent: Konfiguration
Klassen Agent er rent deklarativ: Den kører ingenting; den beskriver. Alt, der definerer din agents adfærd, findes ét sted.
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
)
Vigtige parametre for Agent:
name: Menneskelæselig identifikator for agenteninstructions: Systemprompten, der definerer adfærdenmodel: Modellen, der skal bruges (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Listen over tilgængelige værktøjerhandoff_description: Beskrivelse brugt til overgivelser mellem agenteroutput_type: Pydantic-type til at strukturere outputtet
Runner: Eksekvering
Runner er motoren, der kører din agent. Den styrer hele løkken og findes i tre tilstande afhængigt af din kaldkontekst.
from agents import Runner
# Synkron tilstand (udvikling)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asynkron tilstand (produktion)
result = await Runner.run(agent, "What is the price of the widget?")
# Streaming-tilstand (realtid)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Uanset tilstand får du et RunResult tilbage, som indeholder langt mere end det svar, der kan vises. Den fulde historik lader dig genoptage en samtale, og last_agent bliver essentiel, så snart flere agenter overgiver kontrollen til hinanden.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Agentens endelige svar
print(result.final_output)
# Den komplette samtalehistorik
print(result.to_input_list())
# Den sidste aktive agent (nyttig ved overgivelser)
print(result.last_agent.name)
Tool: Egenskaber
SDK’et understøtter tre måder at deklarere værktøjer på, fra mest almindelig til mest arkitektonisk.
1. Funktionsværktøjer (mest almindelig)
En dekoreret Python-funktion bliver til et værktøj; SDK’et udleder skemaet fra signaturen og docstrengen.
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. Værktøjer hostet af OpenAI
Disse værktøjer kører på OpenAIs side: Du skriver ikke søgelogikken eller Python-sandboxen.
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. Agenter som værktøjer
Én agent kan bruge en anden som værktøj. Koordinatoren nedenfor delegerer research uden nogensinde at afgive kontrollen over samtalen, hvilket adskiller dette fra en overgivelse (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: Sikkerhed
En guardrail er en kontrolagent placeret foran din forretningsagent. Her tjekker en verifikator, om anmodningen falder inden for salg, før salgsagenten svarer.
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),
],
)
Hvis guardrailen udløses (tripwire_triggered=True), stoppes eksekveringen, og en InputGuardrailTripwireTriggered-undtagelse kastes. Planlæg at fange denne i din applikation; ellers vil du returnere en 500-fejl til en bruger, der blot stillede et emnefremmed spørgsmål.
Hvordan disse dele interagerer
Det fulde flow kører som følger:
- Du kalder
Runner.run(agent, message) - Runner tjekker input guardrails
- Runner sender beskeden til agentens model
- Hvis modellen anmoder om et tool, udfører Runner det
- Runner returnerer resultatet til modellen (tilbage til trin 3)
- Når modellen producerer et endeligt svar, tjekker Runner output guardrails
RunResultreturneres
Vigtige pointer
Agentdefinerer adfærd (instrukser, model, værktøjer)Runnerorkestrerer eksekveringen af agentløkken- Deklarér værktøjer med
@function_tool, indbyggede klasser eller.as_tool() - Guardrails validerer input og output af hensyn til sikkerheden
RunResultindeholder det endelige svar og den komplette historik