SDK-anatomi: Agent, Runner, Tool, Guardrail
På denna sida
SDK-anatomi: Agent, Runner, Tool, Guardrail
Agents SDK bygger på fyra kärnbegrepp: Agent, Runner, Tool och Guardrail. Var och en har ett enda ansvarsområde. Det är samspelet mellan dem – vem som beslutar, vem som exekuterar, vem som agerar och vem som kontrollerar – som gör SDK:t lättläst så fort du har internaliserat det.
Agent – Hjärnan
Definierar instruktioner, modell, verktyg och skyddsräcken. Detta är din agents konfiguration.
Runner – Exekveringsmotorn
Orkestrerar resonemangsloopen: skickar förfrågningar, exekuterar verktyg och hanterar överlämningar.
Tool – Möjligheter
Funktioner som agenten kan anropa: webbsökning, kodexekvering, API-anrop med mera.
Guardrail – Säkerhet
Validerar agentens in- och utdata. Blockerar farliga eller ovidkommande förfrågningar.
Agent: Konfiguration
Klassen Agent är rent deklarativ: den kör ingenting, den beskriver. Allt som definierar din agents beteende finns på ett ställe.
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
)
Viktiga parametrar för Agent:
name: Människoläsbar identifierare för agenteninstructions: Systemprompten som definierar beteendetmodel: Modellen som ska användas (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Listan över tillgängliga verktyghandoff_description: Beskrivning som används vid överlämningar mellan agenteroutput_type: Pydantic-typ för att strukturera utdata
Runner: Exekvering
Runner är motorn som kör din agent. Den hanterar hela loopen och finns i tre lägen beroende på ditt anropssammanhang.
from agents import Runner
# Synkront läge (utveckling)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asynkront läge (produktion)
result = await Runner.run(agent, "What is the price of the widget?")
# Strömmande läge (realtid)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Oavsett läge får du tillbaka ett RunResult, som innehåller mycket mer än det svar som visas. Den fullständiga historiken låter dig återuppta en konversation, och last_agent blir avgörande så fort flera agenter överlämnar till varandra.
result = Runner.run_sync(agent, "What is the price of the widget?")
# Agentens slutgiltiga svar
print(result.final_output)
# Den kompletta konversationshistoriken
print(result.to_input_list())
# Senast aktiva agent (användbart vid överlämningar)
print(result.last_agent.name)
Tool: Möjligheter
SDK:t stöder tre sätt att deklarera verktyg, från vanligast till mest arkitektoniskt.
1. Funktionsverktyg (vanligast)
En dekorerad Python-funktion blir ett verktyg; SDK:t härleder schemat från signatur och 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. Verktyg som hostas av OpenAI
Dessa verktyg körs på OpenAIs sida: du skriver inte söklogiken eller Python-sandlådan.
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 verktyg
En agent kan använda en annan som ett verktyg. Koordinatorn nedan delegerar research utan att någonsin släppa kontrollen över konversationen, vilket skiljer detta från en överlämning.
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: Säkerhet
Ett guardrail är en kontrollagent placerad framför din affärsagent. Här kontrollerar en verifierare om förfrågningen rör försäljning innan försäljningsagenten svarar.
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),
],
)
Om guardrailet utlöses (tripwire_triggered=True) stoppas exekveringen och ett undantag InputGuardrailTripwireTriggered kastas. Planera att fånga detta i din applikation; annars returnerar du ett 500-fel till en användare som helt enkelt ställde en ovidkommande fråga.
Hur dessa delar samverkar
Hela flödet ser ut så här:
- Du anropar
Runner.run(agent, message) - Runner kontrollerar input guardrails
- Runner skickar meddelandet till agentens modell
- Om modellen begär ett tool exekuterar Runner det
- Runner returnerar resultatet till modellen (tillbaka till steg 3)
- När modellen producerar ett slutgiltigt svar kontrollerar Runner output guardrails
RunResultreturneras
Viktiga punkter
Agentdefinierar beteende (instruktioner, modell, verktyg)Runnerorkestrerar exekveringen av agentloopen- Deklarera verktyg med
@function_tool, inbyggda klasser eller.as_tool() - Guardrails validerar in- och utdata för säkerhet
RunResultinnehåller det slutgiltiga svaret och den kompletta historiken