Salt la conținutul principal
Română— Alege o limbă
Meniu

Anatomia SDK: Agent, Runner, Tool, Guardrail

Lecția 5 din 25 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Anatomia SDK: Agent, Runner, Tool, Guardrail
  2. Agent: Configurație
  3. Runner: Execuție
  4. Tool: Capacități
  5. Guardrail: Siguranță
  6. Cum interacționează aceste componente
  7. Puncte cheie

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.

1

Agent — Creierul

Definește instrucțiunile, modelul, instrumentele și guardrail-urile. Aceasta este configurația agentului dumneavoastră.

2

Runner — Motorul de execuție

Orchestrează bucla de raționament: trimite cereri, execută instrumente și gestionează transferurile (handoffs).

3

Tool — Capacități

Funcții pe care agentul le poate apela: căutare web, executare de cod, apeluri API și altele.

4

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 agentului
  • instructions: Promptul de sistem care definește comportamentul
  • model: Modelul de utilizat (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Lista instrumentelor disponibile
  • handoff_description: Descriere utilizată pentru transferurile între agenți
  • output_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:

  1. Apelați Runner.run(agent, message)
  2. Runner verifică guardrail-urile de intrare
  3. Runner trimite mesajul către modelul Agentului
  4. Dacă modelul solicită un instrument, Runner îl execută
  5. Runner returnează rezultatul modelului (înapoi la pasul 3)
  6. Când modelul produce un răspuns final, Runner verifică guardrail-urile de ieșire
  7. Este returnat obiectul RunResult

Puncte cheie

  • Agent definește comportamentul (instrucțiuni, model, instrumente)
  • Runner orchestrează 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ță
  • RunResult conține răspunsul final și istoricul complet