Anatomia SDK: Agent, Runner, Tool, Guardrail
Pe această pagină
Anatomia SDK: Agent, Runner, Tool, Guardrail
SDK-ul Agents se bazează pe patru concepte fundamentale: Agent, Runner, Tool și Guardrail. Fiecare are o singură responsabilitate. Interacțiunea lor – cine decide, cine execută, cine acționează, cine controlează – este ceea ce face SDK-ul ușor de înțeles odată ce îl internalizați.
Agent — Creierul
Definește instrucțiunile, modelul, instrumentele și guardrail-urile. Aceasta este configurația agentului dumneavoastră.
Runner — Motorul de execuție
Orchestrează bucla de raționament: trimite cereri, execută instrumente și gestionează transferurile (handoffs).
Tool — Capacități
Funcții pe care agentul le poate apela: căutare web, executare de cod, apeluri API și altele.
Guardrail — Siguranță
Validează intrările și ieșirile agentului. Blochează cererile periculoase sau care se abat de la subiect.
Agent: Configurație
Clasa Agent este pur declarativă: nu execută nimic, ci doar descrie. Tot ceea ce definește comportamentul agentului dumneavoastră se află într-un singur loc.
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
)
Parametrii cheie ai clasei Agent:
name: Identificator lizibil pentru om al agentuluiinstructions: Promptul de sistem care definește comportamentulmodel: Modelul de utilizat (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Lista instrumentelor disponibilehandoff_description: Descriere utilizată pentru transferurile între agențioutput_type: Tip Pydantic pentru structurarea ieșirii
Runner: Execuție
Runner este motorul care rulează agentul dumneavoastră. Gestionează întreaga buclă și vine în trei moduri, în funcție de contextul de apelare.
from agents import Runner
# Synchronous mode (development)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Asynchronous mode (production)
result = await Runner.run(agent, "What is the price of the widget?")
# Streaming mode (real time)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Indiferent de mod, primiți înapoi un obiect RunResult, care conține mult mai mult decât răspunsul afișabil. Istoricul complet vă permite să reluați o conversație, iar last_agent devine esențial imediat ce mai mulți agenți își transferă controlul unul altuia.
result = Runner.run_sync(agent, "What is the price of the widget?")
# The agent's final response
print(result.final_output)
# The complete conversation history
print(result.to_input_list())
# The last active agent (useful with handoffs)
print(result.last_agent.name)
Tool: Capacități
SDK-ul suportă trei modalități de declarare a instrumentelor, de la cea mai comună la cea mai arhitecturală.
1. Instrumente funcție (cele mai comune)
O funcție Python decorată devine un instrument; SDK-ul deduce schema din semnătură și 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. Instrumente găzduite de OpenAI
Aceste instrumente rulează din partea OpenAI: nu scrieți logica de căutare sau sandbox-ul Python.
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. Agenți ca instrumente
Un agent poate folosi un altul ca instrument. Coordinatorul de mai jos deleagă cercetarea fără a ceda vreodată controlul conversației, ceea ce îl distinge de un transfer (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: Siguranță
Un guardrail este un agent de control plasat în fața agentului dumneavoastră de business. Aici, un verificator stabilește dacă cererea ține de vânzări înainte ca agentul de vânzări să răspundă.
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),
],
)
Dacă guardrail-ul se activează (tripwire_triggered=True), execuția se oprește și este aruncată o excepție InputGuardrailTripwireTriggered. Planificați prinderea acesteia în aplicația dumneavoastră; altfel, veți returna o eroare 500 unui utilizator care a pus doar o întrebare fără legătură cu subiectul.
Cum interacționează aceste componente
Fluxul complet se desfășoară astfel:
- Apelați
Runner.run(agent, message) - Runner verifică guardrail-urile de intrare
- Runner trimite mesajul către modelul Agentului
- Dacă modelul solicită un instrument, Runner îl execută
- Runner returnează rezultatul modelului (înapoi la pasul 3)
- Când modelul produce un răspuns final, Runner verifică guardrail-urile de ieșire
- Este returnat obiectul
RunResult
Puncte cheie
Agentdefinește comportamentul (instrucțiuni, model, instrumente)Runnerorchestrează execuția buclei agentului- Declarați instrumentele cu
@function_tool, clase integrate sau.as_tool() - Guardrail-urile validează intrările și ieșirile pentru siguranță
RunResultconține răspunsul final și istoricul complet