Eszkökkeresés: Dinamikus eszközök
Ezen az oldalon
Eszközkeresés: Dinamikus eszközök
Egy bemutató ügynök nyugodtan elboldogul három-négy eszközzel. Egy vállalati szintű ügynök azonban elkerülhetetlenül tucatnyi, néha több száz eszközt halmoz fel: számlázás, HR, CRM, dokumentumkezelés, ütemezés. Ekkora méretreténél minden kéréshez elküldeni az teljes eszközkatalógust a modellnek hatékonytalanná és tokenköltség szempontjából drágává válik. Az eszközkeresés (Tool Search) oldja meg ezt a problémát azáltal, hogy minden egyes kéréshez dinamikusan kiválasztja a releváns eszközöket.
A túl sok eszköz problémája
Képzelj el egy ügynököt 50 eszközzel. Minden API-hívás során mind az 50 eszköz sémája bekerül a promptba. Ez több ezer tokent emészt fel, és összezavarhatja a modellt: minél hosszabb a lista, annál hasonlóbbak lesznek a leírások, és annál inkább habozik a modell a szomszédos eszközök között. A költségek nőnek, míg a pontosság csökken – ez a lehető legrosszabb kombináció.
# Probléma: túl sok eszköz
agent = Agent(
name="Super Agent",
instructions="Bármit meg tudsz csinálni.",
tools=[tool_1, tool_2, tool_3, ... , tool_50], # 50 eszköz = rengeteg token
)
Az eszközkeresés engedélyezése
Az eszközkeresés egy szemantikai indexet használ a kérés alapján releváns eszközök kiválasztásához. Az eszközöket a szokásos módon deklarálod, de a tool_use_behavior="auto" paraméter lehetővé teszi, hogy a modell a katalógusból válasszon, ahelyett, hogy előre betöltené az egészet. Az alábbi példában egy fizetési emlékeztető küldésére vonatkozó kérés nem aktiválja a HR-eszközöket, és fordítva.
from agents import Agent, Runner, function_tool
# Sok eszköz definiálása
@function_tool
def create_invoice(client: str, amount: float) -> str:
"""Számlát hoz létre egy ügyfél számára."""
return f"Számla létrehozva {client} részére: €{amount}"
@function_tool
def send_reminder(invoice_id: str) -> str:
"""Fizetési emlékeztetőt küld egy ki nem fizetett számlához."""
return f"Emlékeztető elküldve a(z) {invoice_id} számlához"
@function_tool
def generate_hr_report(month: str) -> str:
"""Emberi erőforrás jelentést generál egy adott hónapra."""
return f"HR jelentés generálva a(z) {month} hónapra"
@function_tool
def schedule_interview(candidate: str, date: str) -> str:
"""Állásinterjút ütemez egy jelölttel."""
return f"Interjú ütemezve {candidate} jelölttel erre az időpontra: {date}"
# Sok más eszköz...
agent = Agent(
name="Vállalati ügynök",
instructions="Kezeled a vállalat működését.",
tools=[
create_invoice,
send_reminder,
generate_hr_report,
schedule_interview,
# ... 50 másik eszköz
],
tool_use_behavior="auto", # A modell dinamikusan választ
)
Minta: Kézi eszközválasztás
Ha teljes kontrollt szeretnél az eszközválasztás felett, implementáld a saját logikádat. Az elv egyszerű: egy kis router ügynök elolvassa a kérést, és egyszerűen megnevezi az érintett domaint. Ezután futás közben hozod létre a specializált ügynököt csak az adott domainhez tartozó eszközökkel. Egy olyan mondat, mint „küldj emlékeztetőt az F-2026-114 számlához“, a routertől accounting (számvitel) válasszal tér vissza, és a végrehajtó ügynök sosem látja a HR-eszközöket.
from agents import Agent, Runner, function_tool
# Eszközök csoportosítása domainek szerint
accounting_tools = [create_invoice, send_reminder]
hr_tools = [generate_hr_report, schedule_interview]
# Egy router ügynök, amely kiválasztja a domaint
router = Agent(
name="Router",
instructions="""Határozd meg a kérés domainjét.
Csak 'accounting' vagy 'hr' választ adj.""",
model="gpt-5.6-terra", # Gyors és olcsó útvonalválasztáshoz
output_type=str,
)
async def handle_request(message: str):
# 1. lépés: A domain meghatározása
route = await Runner.run(router, message)
domain = route.final_output.strip().lower()
# 2. lépés: A specializált ügynök létrehozása a megfelelő eszközökkel
if domain == "accounting":
tools = accounting_tools
instructions = "Kezeled a vállalat számvitelét."
elif domain == "hr":
tools = hr_tools
instructions = "Kezeled az emberi erőforrásokat."
else:
tools = accounting_tools + hr_tools
instructions = "Kezeled a vállalat működését."
specialized_agent = Agent(
name=f"{domain.capitalize()} ügynök",
instructions=instructions,
tools=tools,
model="gpt-5.6-terra",
)
result = await Runner.run(specialized_agent, message)
return result.final_output
A gpt-5.6-terra használata mind az útvonalválasztáshoz, mind a végrehajtáshoz a modellek előző generációjához tartozik; a minta mögött álló logika azonban azonos marad a GPT-5.6 családdal is, ahol az erőfeszítés-beállítások választják el a gyors routert a végrehajtótól.
Minta: Kontextusfüggő dinamikus eszközök
A kiválasztás nemcsak a feltett kérdéstől függ, hanem attól is, ki kérdez. A rendelkezésre álló eszközöket a bejelentkezett felhasználó alapján is igazíthatod, ezzel két legyet ütsz egy csapásra: kevesebb tokent küldesz, és ami még fontosabb, a hozzáférés-vezérlést már azt megelőzően érvényesíted, hogy a modell egyáltalán gondolkodni kezdene. Egy értékesítési alkalmazott kap árajánlat-készítő eszközöket, de a delete_account egyszerűen nem létezik az ő ügynökében.
from dataclasses import dataclass
@dataclass
class UserContext:
role: str # "admin", "manager", "employee"
department: str
def get_tools_for_role(ctx: UserContext) -> list:
"""A szerepkör alapján engedélyezett eszközöket adja vissza."""
base_tools = [search_document, view_schedule]
if ctx.role in ("admin", "manager"):
base_tools.extend([create_invoice, generate_hr_report])
if ctx.role == "admin":
base_tools.extend([modify_permissions, delete_account])
if ctx.department == "sales":
base_tools.extend([search_client, create_quote])
return base_tools
async def create_agent_for_user(ctx: UserContext):
tools = get_tools_for_role(ctx)
return Agent(
name="Egyéni ügynök",
instructions=f"Egy {ctx.department} osztályon dolgozó {ctx.role} szerepkörű felhasználót segítesz.",
tools=tools,
model="gpt-5.6-terra",
)
Az eszközleírások optimalizálása
Bármelyik kiválasztási mechanizmust is választod, az egyetlen anyagra támaszkodik: a leírásaid szövegére. Ezen leírások minősége közvetlenül befolyásolja a kiválasztás relevanciáját. Hasonlítsd össze az alábbi két deklarációt: az első semmit nem mond a használati forgatókönyvről, míg a második megnevezi a bemeneteket, a kimenetet és azt, hogy mikor kell használni.
# Rossz: homályos leírás
@function_tool
def process_data(data: str) -> str:
"""Adatfeldolgozás."""
return "OK"
# Jó: pontos és kontextusba helyezett leírás
@function_tool
def calculate_gross_margin(revenue: float, production_cost: float) -> str:
"""Kiszámítja a bruttó árrést százalékban az árbevétel és
a gyártási költség alapján. Negyedéves pénzügyi elemzésekhez hasznos."""
margin = ((revenue - production_cost) / revenue) * 100
return f"Bruttó árrés: {margin:.1f}% (Árbevétel: €{revenue}, Költségek: €{production_cost})"
Egy jó eszközleírás olyan, mint egy jó docstring: elmagyarázza, mikor kell használni az eszközt, nem csak azt, hogy mit csinál. Szánj tíz percet az ügynököd leírásainak áttekintésére, és minden egyes esetben tedd fel magadnak a kérdést: egy kolléga ki tudná választani a megfelelő eszközt csak ezen mondat elolvasása alapján? Pontosan ezt a gyakorlatot végzi el a modell is.
Főbb megállapítások
- Az eszközkeresés dinamikusan kiválasztja a releváns eszközöket minden egyes kéréshez
- Sok eszköz esetén egy router ügynök előre meghatározhatja a domaint
- Igazítsd a rendelkezésre álló eszközöket a felhasználó szerepköre és kontextusa alapján
- Az eszközleírások minősége befolyásolja a kiválasztás pontosságát
- Használj könnyűsúlyú modellt a gyors útvonalválasztáshoz, és egy erősebb modellt a végrehajtáshoz