Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Eszközök deklarálása az SDK-ban

6. lecke 25 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Eszközök deklarálása az SDK-ban
  2. A @function_tool dekorátor
  3. Név és leírás testreszabása
  4. Támogatott paramétertípusok
  5. Strukturált eredmények visszaadása
  6. OpenAI által hosztolt eszközök
  7. Egyedi és hosztolt eszközök kombinálása
  8. Főbb megállapítások

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_tool Python-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 és CodeInterpreterTool eszközökkel