Eszközök deklarálása az SDK-ban
Ezen az oldalon
Eszközök deklarálása az SDK-ban
Az eszközök az ügynököd konkrét képességei. Eszközök nélkül az ügynök csupán szöveget képes generálni; eszközökkel azonban adatbázisokat kérdezhet le, API-kat hívhat meg és e-maileket küldhet. Mindenképpen megfelelően kell deklarálnod őket, mert egy eszköz minősége nem csupán a kódján múlik – azon is, hogy a modell mennyire érti meg azt.
A @function_tool dekorátor
Az eszközök létrehozásának legegyszerűbb módja a @function_tool dekorátor használata, amely egy szabványos Python-függvényt az ügynök által hívható képességgé alakít.
from agents import function_tool
@function_tool
def search_customer(email: str) -> str:
"""Ügyfél keresése e-mail cím alapján az adatbázisban.
Args:
email: A keresendő ügyfél e-mail címe.
"""
# Éles környezetben: hívd meg az adatbázisodat
customers = {
"[email protected]": {"name": "Alice Dupont", "plan": "Pro", "since": "2024"},
"[email protected]": {"name": "Bob Martin", "plan": "Starter", "since": "2025"},
}
customer = customers.get(email)
if customer:
return f"Ügyfél megtalálva: {customer['name']}, csomag: {customer['plan']}, ügyfél {customer['since']} óta"
return f"Nem található ügyfél a(z) {email} e-mail címmel"
Semmit sem kell kétszer deklarálnod: az SDK a függvény nevét használja eszköznévként, a dokumentációs sztringet (docstring) leírásként, a típusjelöléseket pedig a paraméterek JSON-sémájának generálásához. Más szóval a dokumentációs sztringed többé nem csupán megjegyzés a kollégáid számára; ez az a szöveg, amelyet a modell olvas, hogy eldöntse, meghívja-e ezt a függvényt. A bizonytalan leírás pontatlan hívásokhoz vezet.
Név és leírás testreszabása
Ha a függvényneved belső konvenciókat követ a üzleti logika helyett, felülírhatod azt, amit a modell lát.
@function_tool(
name_override="search_crm",
description_override="Ügyfél keresése a CRM-ben e-mail, név vagy számlaszám alapján."
)
def search_customer(identifier: str) -> str:
"""Ügyfél keresése."""
# ...
return "Eredmény"
Támogatott paramétertípusok
A natív Python-típusokon túl az SDK elfogad Pydantic-modelleket is. Ha egy eszköz három vagy több paramétert vár, csoportosítsd őket: a séma így olvashatóbbá válik a modell számára, a validálás pedig megvéd a szélsőértékektől.
from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool
class SearchFilter(BaseModel):
category: str = Field(description="Termékkategória")
max_price: Optional[float] = Field(None, description="Maximális ár euróban")
in_stock: bool = Field(True, description="Csak raktáron lévő termékek")
@function_tool
def search_products(filter: SearchFilter) -> str:
"""Termékek keresése megadott kritériumok alapján."""
results = []
# Keresési logika a filter.category, filter.max_price stb. alapján
return f"{len(results)} termék található a(z) {filter.category} kategóriában"
A Pydantic-modellek automatikusan validálják a bemeneteket, és gazdag, mezőnkénti leírásokat biztosítanak a modell számára.
Strukturált eredmények visszaadása
Egy eszköz mindig sztringet ad vissza. Ha az adatod strukturált – több metrika, lista, vegyes típusok –, serializáld JSON-ként ahelyett, hogy mondatokat komponálnál: a modell sokkal megbízhatóbban olvassa a kulcsokat, mint a szabad szöveget.
import json
from agents import function_tool
@function_tool
def get_sales_stats(month: str, year: int) -> str:
"""Értékesítési statisztikák lekérése egy adott hónapra."""
stats = {
"month": month,
"year": year,
"revenue": 145000,
"sales_count": 342,
"avg_basket": 423.98,
"top_products": ["Laptop Pro", "Tablet Air", "Monitor 4K"]
}
return json.dumps(stats, ensure_ascii=False, indent=2)
OpenAI által hosztolt eszközök
Az egyedi függvényeid mellett az SDK hozzáférést biztosít az OpenAI által kezelt eszközökhöz is, amelyek a platform oldalán futnak.
from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool
agent = Agent(
name="Általános célú asszisztens",
instructions="Olyan asszisztens vagy, aki képes webes keresésre, fájlok elemzésére és kód végrehajtására.",
tools=[
WebSearchTool(),
FileSearchTool(
vector_store_ids=["vs_abc123"],
max_num_results=10,
),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
A WebSearchTool lehetővé teszi az ügynök számára, hogy valós időben keressen az interneten, és nem igényel konfigurációt. A FileSearchTool szemantikai keresést végez a fájljaid között, de előzetes beállítást feltételez: létre kell hoznod egy vektortárat az OpenAI API-n keresztül, és feltöltened rá a dokumentumaidat – ezért szükséges a vs_abc123 paraméterként való átadása. A CodeInterpreterTool lehetővé teszi az ügynök számára, hogy Python-kódot írjon és hajtson végre egy elszigetelt konténerben, így ez a legjobb választás adatelemzéshez és diagramok generálásához. Megkövetel egy tool_config objektumot, amely meghatározza ezt a konténert: a {"type": "auto"} érték igény szerint hozza létre azt (az openai-agents SDK elutasítja a CodeInterpreterTool() hívását ennek hiányában).
Egyedi és hosztolt eszközök kombinálása
Az igazi erő a kombinációban rejlik. Egy pénzügyi elemzőnek szüksége van a belső adataidra, számítási képességekre és piaci kontextusra: három forrásra, amelyet egyetlen eszköz sem fed le.
agent = Agent(
name="Pénzügyi elemző",
instructions="""Pénzügyi elemző vagy.
Használd a belső eszközöket az adatok lekérésére,
a kódértelmezőt az elemzésükre,
a webes keresést pedig a piaci kontextus biztosítására.""",
tools=[
get_sales_stats,
search_customer,
WebSearchTool(),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
Figyeld meg, hogyan határozzák meg az utasítások, hogy mire szolgál az egyes eszközcsoportok. Ezen egyértelműség nélkül a négy eszközzel rendelkező ügynök habozik, feleslegesen próbál ki kettőt is, és ok nélkül növeli a késleltetést.
Főbb megállapítások
- A
@function_toolPython-függvényt alakít át ügynök-eszközzé - A dokumentációs sztring és a típusjelölések automatikusan generálják a JSON-sémát
- Használj Pydanticot a komplex, validálást igénylő paraméterekhez
- Az eszközök mindig sztringet adnak vissza (strukturált adat esetén JSON-t)
- Kombináld az egyedi eszközeidet a
WebSearchTool,FileSearchToolésCodeInterpreterTooleszközökkel