Anatomie van de SDK: Agent, Runner, Tool, Guardrail
Op deze pagina
Anatomie van de SDK: Agent, Runner, Tool, Guardrail
De Agents SDK rust op vier kernconcepten: Agent, Runner, Tool en Guardrail. Elk heeft één enkele verantwoordelijkheid. Hun samenspel—wie beslist, wie voert uit, wie handelt, wie controleert—maakt de SDK leesbaar zodra u het onder de knie heeft.
Agent — Het brein
Definieert instructies, model, tools en guardrails. Dit is de configuratie van uw agent.
Runner — De uitvoeringsengine
Orchestreert de redeneerlus: verstuurt verzoeken, voert tools uit en behandelt overdrachten.
Tool — Mogelijkheden
Functies die de agent kan aanroepen: webzoekopdrachten, code-uitvoering, API-aanroepen en meer.
Guardrail — Veiligheid
Valideert inputs en outputs van de agent. Blokkeert gevaarlijke of off-topic verzoeken.
Agent: Configuratie
De Agent-klasse is puur declaratief: deze voert niets uit, maar beschrijft alleen. Alles wat het gedrag van uw agent definieert, staat op één plek.
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
)
Belangrijke Agent-parameters:
name: Een voor mensen leesbare identificatie voor de agentinstructions: De systeemprompt die het gedrag definieertmodel: Het te gebruiken model (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: De lijst met beschikbare toolshandoff_description: Beschrijving gebruikt voor overdrachten tussen agentsoutput_type: Pydantic-type om de output te structureren
Runner: Uitvoering
De Runner is de engine die uw agent uitvoert. Deze beheert de volledige lus en is beschikbaar in drie modi, afhankelijk van uw aanroepcontext.
from agents import Runner
# Synchrone modus (ontwikkeling)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asynchrone modus (productie)
result = await Runner.run(agent, "What is the price of the widget?")
# Streaming-modus (real-time)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Ongeacht de modus krijgt u een RunResult terug, dat veel meer bevat dan alleen de weergeefbare respons. De volledige geschiedenis stelt u in staat een gesprek te hervatten, en last_agent wordt essentieel zodra meerdere agents taken aan elkaar overdragen.
result = Runner.run_sync(agent, "What is the price of the widget?")
# De definitieve respons van de agent
print(result.final_output)
# De volledige gespreksgeschiedenis
print(result.to_input_list())
# De laatst actieve agent (nuttig bij overdrachten)
print(result.last_agent.name)
Tool: Mogelijkheden
De SDK ondersteunt drie manieren om tools te declareren, van meest gebruikelijk tot meest architecturaal.
1. Functietools (meest gebruikelijk)
Een gedecoreerde Python-functie wordt een tool; de SDK leidt het schema af uit de signatuur en de 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. Tools gehost door OpenAI
Deze tools draaien aan de kant van OpenAI: u schrijft de zoeklogica of de Python-sandbox niet zelf.
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. Agents als tools
Eén agent kan een andere als tool gebruiken. De onderstaande coördinator delegeert onderzoek zonder ooit de controle over het gesprek uit handen te geven, wat dit onderscheidt van een overdracht (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: Veiligheid
Een guardrail is een controle-agent die voor uw zakelijke agent wordt geplaatst. Hier controleert een verificateur of het verzoek binnen het verkoopdomein valt voordat de verkoopagent antwoordt.
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),
],
)
Als de guardrail afgaat (tripwire_triggered=True), stopt de uitvoering en wordt een InputGuardrailTripwireTriggered-exceptie gegenereerd. Zorg dat u deze in uw applicatie afvangt; anders retourneert u een 500-fout aan een gebruiker die simpelweg een off-topic vraag stelde.
Hoe deze onderdelen samenwerken
De volledige stroom verloopt als volgt:
- U roept
Runner.run(agent, message)aan - De Runner controleert input guardrails
- De Runner stuurt het bericht naar het model van de Agent
- Als het model een tool aanvraagt, voert de Runner deze uit
- De Runner retourneert het resultaat aan het model (terug naar stap 3)
- Wanneer het model een definitieve respons produceert, controleert de Runner output guardrails
- Het
RunResultwordt geretourneerd
Belangrijkste punten
Agentdefinieert gedrag (instructies, model, tools)Runnerorchestreert de uitvoering van de agent-lus- Declareer tools met
@function_tool, ingebouwde klassen of.as_tool() - Guardrails valideren inputs en outputs voor veiligheid
RunResultbevat de definitieve respons en de volledige geschiedenis