Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Anatomija tal-SDK: Aġent, Runner, Għodda, Guardrail

Lezzjoni 5 / 25 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Anatomija tal-SDK: Aġent, Runner, Għodda, Guardrail
  2. Aġent: Konfigurazzjoni
  3. Runner: Eżekuzzjoni
  4. Għodda: Kapaċitajiet
  5. Guardrail: Sigurtà
  6. Kif dawn il-biċċiet jinteraġixxu
  7. Punti Ewlenin

Anatomija tal-SDK: Aġent, Runner, Għodda, Guardrail

L-SDK tal-Aġenti jistrieħ fuq erba’ kunċetti ewlenin: Aġent, Runner, Għodda, u Guardrail. Kull wieħed għandu responsabbiltà waħda biss. L-interazzjoni tagħhom—min jiddeċiedi, min jesegwixxi, min jaġixxi, min jikkontrolla—hija dak li jagħmel lill-SDK leġibbli ladarba tifhmu sew kif jaħdmu flimkien.

1

Aġent — Il-moħħ

Jiddefinixxi l-istruzzjonijiet, il-mudell, l-għodod u l-guardrails. Din hija l-konfigurazzjoni tal-aġent tiegħek.

2

Runner — Il-magna ta' eżekuzzjoni

Jikkoordina ċ-ċiklu tar-raġunament: jibgħat it-talbiet, jesegwixxi l-għodod u jimmaniġġja l-passaġġi (handoffs).

3

Għodda — Il-kapaċitajiet

Il-funzjonijiet li l-aġent jista' jsejjaħ: tfittxija fuq il-web, eżekuzzjoni tal-kodiċi, sejħiet API u aktar.

4

Guardrail — Is-sigurtà

Jivvalida l-inputs u l-outputs tal-aġent. Jibblokka talbiet perikolużi jew barra mit-tema.

Aġent: Konfigurazzjoni

Il-klassi Agent hija purament dikjarattiva: ma tħaddim xejn; hija tiddeskrivi biss. Kollox li jiddefinixxi l-imġiba tal-aġent tiegħek jinsab f’post wieħed.

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
)

Parametri ewlenin tal-Agent:

  • name: Identifikatur li jista’ jinqara mill-bniedem għall-aġent
  • instructions: Il-prompt tas-sistema li jiddefinixxi l-imġiba
  • model: Il-mudell li għandu jintuża (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Il-lista tal-għodod disponibbli
  • handoff_description: Deskrizzjoni użata għall-passaġġi bejn l-aġenti
  • output_type: Tip ta’ Pydantic biex tiġi strutturata l-output

Runner: Eżekuzzjoni

Ir-Runner huwa l-magna li tħaddem l-aġent tiegħek. Jimmaniġġja ċ-ċiklu sħiħ u jiġi f’tliet modi skont il-kuntest tas-sejħa tiegħek.

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?")

Irregolarment mill-mod, tirċievi RunResult, li fiha ħafna aktar mill-biss ir-risposta li tista’ tintwera. L-istorja sħiħa tippermettilek tkompli konversazzjoni, u last_agent issir essenzjali hekk kif aġenti multipli jagħmlu handoff ma’ xulxin.

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)

Għodda: Kapaċitajiet

L-SDK jappoġġja tliet modi biex tiddikjara l-għodod, mill-aktar komuni għall-aktar arkitettoniku.

1. Għodod tal-funzjoni (l-aktar komuni)

Funzjoni Python imżejna ssir għodda; l-SDK jiddeduċi l-iskema mis-sinjala u d-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. Għodod ospitati minn OpenAI

Dawn l-għodod jaħdmu fuq in-naħa ta’ OpenAI: inti ma tiktebx il-loġika tat-tfittxija jew is-sandbox tal-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. Aġenti bħala għodod

Aġent wieħed jista’ juża ieħor bħala għodda. Il-koordinatur hawn taħt jiddelega r-riċerka mingħajr qatt ma jitlaq il-kontroll tal-konversazzjoni, li jiddistingwi dan minn 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: Sigurtà

Guardrail huwa aġent ta’ kontroll imqiegħed quddiem l-aġent tan-negozju tiegħek. Hawnhekk, verifikatur jiċċekkja jekk it-talba taqax fil-qasam tal-bejgħ qabel ma l-aġent tal-bejgħ iwieġeb.

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),
    ],
)

Jekk il-guardrail jiġi attivat (tripwire_triggered=True), l-eżekuzzjoni tieqaf u tinħareġ eċċezzjoni InputGuardrailTripwireTriggered. Ippjana li taqbad din fl-applikazzjoni tiegħek; inkella, se tirritorna żball 500 lil utent li sempliċiment għamel mistoqsija barra mit-tema.

Kif dawn il-biċċiet jinteraġixxu

Il-fluss sħiħ jimxi kif ġej:

  1. Int issejjaħ Runner.run(agent, message)
  2. Ir-Runner jiċċekkja l-input guardrails
  3. Ir-Runner jibgħat il-messaġġ lill-mudell tal-Aġent
  4. Jekk il-mudell jitlob għodda, ir-Runner jesegwixxiha
  5. Ir-Runner jirritorna r-riżultat lill-mudell (lura għall-pass 3)
  6. Meta l-mudell jipproduċi risposta finali, ir-Runner jiċċekkja l-output guardrails
  7. Ir-RunResult tiġi rritornata

Punti Ewlenin

  • Agent jiddefinixxi l-imġiba (istruzzjonijiet, mudell, għodod)
  • Runner jikkoordina l-eżekuzzjoni taċ-ċiklu tal-aġent
  • Iddikjara l-għodod b’@function_tool, klassijiet integrati, jew .as_tool()
  • Il-Guardrails jivvalidaw l-inputs u l-outputs għas-sigurtà
  • RunResult fiha r-risposta finali u l-istorja sħiħa