Anatomija tal-SDK: Aġent, Runner, Għodda, Guardrail
F'din il-paġna
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.
Aġent — Il-moħħ
Jiddefinixxi l-istruzzjonijiet, il-mudell, l-għodod u l-guardrails. Din hija l-konfigurazzjoni tal-aġent tiegħek.
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).
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.
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ġentinstructions: Il-prompt tas-sistema li jiddefinixxi l-imġibamodel: 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 disponibblihandoff_description: Deskrizzjoni użata għall-passaġġi bejn l-aġentioutput_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:
- Int issejjaħ
Runner.run(agent, message) - Ir-Runner jiċċekkja l-input guardrails
- Ir-Runner jibgħat il-messaġġ lill-mudell tal-Aġent
- Jekk il-mudell jitlob għodda, ir-Runner jesegwixxiha
- Ir-Runner jirritorna r-riżultat lill-mudell (lura għall-pass 3)
- Meta l-mudell jipproduċi risposta finali, ir-Runner jiċċekkja l-output guardrails
- Ir-
RunResulttiġi rritornata
Punti Ewlenin
Agentjiddefinixxi l-imġiba (istruzzjonijiet, mudell, għodod)Runnerjikkoordina 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à
RunResultfiha r-risposta finali u l-istorja sħiħa