Căutare de instrumente: Instrumente dinamice
Pe această pagină
Căutare de instrumente: Instrumente dinamice
Un agent demonstrativ se descurcă perfect cu trei sau patru instrumente. Un agent de nivel enterprise, însă, acumulează inevitabil zeci, uneori sute: facturare, resurse umane, CRM, documente, programări. La o astfel de scară, trimiterea întregului catalog către model la fiecare solicitare devine ineficientă și costisitoare din punct de vedere al tokenilor. Căutarea de instrumente (Tool Search) rezolvă această problemă prin selectarea dinamică a instrumentelor relevante pentru fiecare solicitare.
Problema prea multor instrumente
Imaginați-vă un agent cu 50 de instrumente. La fiecare apel API, schemele pentru toate cele 50 de instrumente sunt trimise în prompt. Acest lucru consumă mii de tokeni și poate confuza modelul: cu cât lista este mai lungă, cu atât descrierile devin mai similare, iar modelul ezită tot mai mult între instrumentele învecinate. Costurile cresc, iar precizia scade – cea mai proastă combinație posibilă.
# Problemă: prea multe instrumente
agent = Agent(
name="Super Agent",
instructions="You can do anything.",
tools=[tool_1, tool_2, tool_3, ... , tool_50], # 50 tools = lots of tokens
)
Activarea căutării de instrumente
Căutarea de instrumente utilizează un index semantic pentru a selecta instrumentele relevante pe baza solicitării. Declarați instrumentele ca de obicei, dar parametrul tool_use_behavior="auto" permite modelului să aleagă din catalog în loc să încarce totul de la început. În exemplul de mai jos, o solicitare de a trimite un memento de plată nu va declanșa instrumentele de resurse umane și viceversa.
from agents import Agent, Runner, function_tool
# Definirea multor instrumente
@function_tool
def create_invoice(client: str, amount: float) -> str:
"""Creates an invoice for a client."""
return f"Invoice created for {client}: €{amount}"
@function_tool
def send_reminder(invoice_id: str) -> str:
"""Sends a payment reminder for an unpaid invoice."""
return f"Reminder sent for invoice {invoice_id}"
@function_tool
def generate_hr_report(month: str) -> str:
"""Generates a human resources report for a given month."""
return f"HR report generated for {month}"
@function_tool
def schedule_interview(candidate: str, date: str) -> str:
"""Schedules a job interview with a candidate."""
return f"Interview scheduled with {candidate} on {date}"
# Multe alte instrumente...
agent = Agent(
name="Enterprise Agent",
instructions="You manage company operations.",
tools=[
create_invoice,
send_reminder,
generate_hr_report,
schedule_interview,
# ... 50 other tools
],
tool_use_behavior="auto", # Modelul selectează dinamic
)
Model: Selectarea manuală a instrumentelor
Dacă doriți un control total asupra selectării instrumentelor, implementați propria logică. Principiul este simplu: un agent router mic citește solicitarea și numește doar domeniul relevant. Apoi, construiți agentul specializat din zbor, folosind doar instrumentele pentru acel domeniu. O frază precum „trimite un memento pentru factura F-2026-114“ iese din router cu răspunsul accounting, iar agentul de execuție nu vede niciodată instrumentele de resurse umane.
from agents import Agent, Runner, function_tool
# Gruparea instrumentelor pe domenii
accounting_tools = [create_invoice, send_reminder]
hr_tools = [generate_hr_report, schedule_interview]
# Un agent router care selectează domeniul
router = Agent(
name="Router",
instructions="""Determine the domain of the request.
Respond only with 'accounting' or 'hr'.""",
model="gpt-5.6-terra", # Rapid și ieftin pentru rutare
output_type=str,
)
async def handle_request(message: str):
# Pasul 1: Determinarea domeniului
route = await Runner.run(router, message)
domain = route.final_output.strip().lower()
# Pasul 2: Crearea agentului specializat cu instrumentele corecte
if domain == "accounting":
tools = accounting_tools
instructions = "You manage the company's accounting."
elif domain == "hr":
tools = hr_tools
instructions = "You manage human resources."
else:
tools = accounting_tools + hr_tools
instructions = "You manage company operations."
specialized_agent = Agent(
name=f"{domain.capitalize()} Agent",
instructions=instructions,
tools=tools,
model="gpt-5.6-terra",
)
result = await Runner.run(specialized_agent, message)
return result.final_output
Utilizarea gpt-5.6-terra atât pentru rutare, cât și pentru execuție aparține generației anterioare de modele; raționamentul din spatele modelului rămâne identic cu familia GPT-5.6, unde setările de efort disting routerul rapid de executor.
Model: Instrumente dinamice conștiente de context
Selecția nu depinde doar de întrebarea pusă; depinde și de cine o pune. Puteți adapta instrumentele disponibile în funcție de utilizatorul autentificat, omorând două muște dintr-o lovitură: mai puțini tokeni trimiși și, mai important, controale de acces aplicate înainte ca modelul să raționeze măcar. Un angajat din vânzări primește instrumente de ofertare, dar delete_account pur și simplu nu există în agentul său.
from dataclasses import dataclass
@dataclass
class UserContext:
role: str # "admin", "manager", "employee"
department: str
def get_tools_for_role(ctx: UserContext) -> list:
"""Returns authorized tools based on role."""
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="Custom Agent",
instructions=f"You assist a {ctx.role} in the {ctx.department} department.",
tools=tools,
model="gpt-5.6-terra",
)
Optimizarea descrierilor instrumentelor
Indiferent de mecanismul de selecție ales, acesta se bazează pe un singur material: textul descrierilor dumneavoastră. Calitatea acestor descrieri impactează direct relevanța selecției. Comparați cele două declarații de mai jos: prima nu spune nimic despre scenariul de utilizare, în timp ce a doua numește intrările, ieșirea și momentul utilizării.
# Rău: descriere vagă
@function_tool
def process_data(data: str) -> str:
"""Processes data."""
return "OK"
# Bun: descriere precisă și contextualizată
@function_tool
def calculate_gross_margin(revenue: float, production_cost: float) -> str:
"""Calculates gross margin as a percentage from revenue
and production cost. Useful for quarterly financial analysis."""
margin = ((revenue - production_cost) / revenue) * 100
return f"Gross margin: {margin:.1f}% (Revenue: €{revenue}, Costs: €{production_cost})"
O descriere bună a unui instrument este ca un docstring bun: explică când să utilizați instrumentul, nu doar ce face. Alocați zece minute pentru a revizui descrierile agentului dumneavoastră, întrebându-vă pentru fiecare dacă un coleg ar putea alege instrumentul corect citind doar acea propoziție. Exact acesta este exercițiul pe care îl efectuează modelul.
Puncte cheie
- Căutarea de instrumente selectează dinamic instrumentele relevante pentru fiecare solicitare
- Cu multe instrumente, un agent router poate determina domeniul din start
- Adaptați instrumentele disponibile în funcție de rolul și contextul utilizatorului
- Calitatea descrierii instrumentului impactează acuratețea selecției
- Utilizați un model ușor pentru rutare rapidă și un model capabil pentru execuție