Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Deklarácia nástrojov v SDK

Lekcia 6 z 25 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Deklarácia nástrojov v SDK
  2. Dekorátor @function_tool
  3. Prispôsobenie názvu a popisu
  4. Podporované typy parametrov
  5. Návrat štruktúrovaných výsledkov
  6. Nástroje hostované spoločnosťou OpenAI
  7. Kombinácia vlastných a hostovaných nástrojov
  8. Kľúčové poznatky

Deklarácia nástrojov v SDK

Nástroje predstavujú konkrétne schopnosti tvojho agenta. Bez nich dokáže agent iba generovať text; s nástrojmi môže vyhľadávať v databázach, volať API a odosielať e-maily. Musíš ich však správne deklarovať, pretože kvalita nástroja nezávisí len od kódu, ale aj od toho, ako dobre ho model pochopí.

Dekorátor @function_tool

Najjednoduchší spôsob, ako vytvoriť nástroj, je použitie dekorátora @function_tool, ktorý premení štandardnú funkciu Python na schopnosť, ktorú môže agent zavolať.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Vyhľadanie zákazníka podľa e-mailovej adresy v databáze.

    Args:
        email: E-mailová adresa zákazníka, ktorú treba vyhľadať.
    """
    # V produkcii: volanie vašej databázy
    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"Zákazník nájdený: {customer['name']}, plán {customer['plan']}, zákazník od {customer['since']}"
    return f"Žiadny zákazník s e-mailom {email} nebol nájdený"

Nič sa nedeklaruje dvakrát: SDK používa názov funkcie ako názov nástroja, docstring ako popis a typové nápovedy (type hints) na generovanie schémy JSON pre parametre. Inými slovami, tvoj docstring už nie je len komentárom pre kolegov; je to text, ktorý model číta, aby sa rozhodol, či túto funkciu zavolať. Nejasný docstring vedie k nepresným volaniam.

Prispôsobenie názvu a popisu

Ak názov tvojej funkcie nasleduje interné konvencie namiesto obchodnej logiky, môžeš prepísať to, čo vidí model.

@function_tool(
    name_override="search_crm",
    description_override="Vyhľadanie zákazníka v CRM systéme podľa e-mailu, mena alebo čísla účtu."
)
def search_customer(identifier: str) -> str:
    """Vyhľadanie zákazníka."""
    # ...
    return "Výsledok"

Podporované typy parametrov

Okrem natívnych typov Python akceptuje SDK aj modely Pydantic. Ak nástroj prijíma tri alebo viac parametrov, zgrupuj ich: schéma sa stane pre model čitateľnejšou a validácia ťa ochráni pred extrémnymi hodnotami.

from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool

class SearchFilter(BaseModel):
    category: str = Field(description="Kategória produktu")
    max_price: Optional[float] = Field(None, description="Maximálna cena v eurách")
    in_stock: bool = Field(True, description="Iba produkty na sklade")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Vyhľadanie produktov na základe zadaných kritérií."""
    results = []
    # Logika vyhľadávania pomocou filter.category, filter.max_price atď.
    return f"Nájdených {len(results)} produktov v kategórii {filter.category}"

Modely Pydantic automaticky validujú vstupy a poskytujú modelu bohaté popisy po jednotlivých poliach.

Návrat štruktúrovaných výsledkov

Nástroj vždy vracia reťazec. Keď majú tvoje dáta štruktúru – viacero metrík, zoznam, zmiešané typy – serializuj ich ako JSON namiesto zostavovania vety: model bude čítať kľúče oveľa spoľahlivejšie ako voľný text.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Získanie štatistík predaja za daný mesiac."""
    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)

Nástroje hostované spoločnosťou OpenAI

Okrem tvojich vlastných funkcií poskytuje SDK prístup k nástrojom spravovaným spoločnosťou OpenAI, ktoré bežia na strane platformy.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="Všeobecný asistent",
    instructions="Si asistent schopný vyhľadávať na webe, analyzovať súbory a spúšťať kód.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool umožňuje agentovi vyhľadávať na internete v reálnom čase a nevyžaduje žiadnu konfiguráciu. FileSearchTool vykonáva sémantické vyhľadávanie v tvojich súboroch, ale predpokladá predchádzajúce nastavenie: musíš vytvoriť úložisko vektorov prostredníctvom API OpenAI a nahrať doň svoje dokumenty – preto sa ako parameter odovzdáva vs_abc123. CodeInterpreterTool umožňuje agentu písať a spúšťať kód Python v izolovanom kontajneri, čo z neho robí ideálnu voľbu pre analýzu dát a generovanie grafov. Vyžaduje tool_config, ktorý špecifikuje tento kontajner: {"type": "auto"} ho vytvorí na požiadanie (SDK openai-agents odmietne CodeInterpreterTool() bez neho).

Kombinácia vlastných a hostovaných nástrojov

Skutočná sila spočíva v kombinácii. Finančný analytik potrebuje tvoje interné dáta, výpočtové schopnosti a kontext trhu: tri zdroje, ktoré žiadny jednotlivý nástroj nepokryje.

agent = Agent(
    name="Finančný analytik",
    instructions="""Si finančný analytik.
    Použi interné nástroje na získanie dát,
    interpretátor kódu na ich analýzu
    a vyhľadávanie na webe pre kontext trhu.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Všimni si, ako inštrukcie špecifikujú, na čo slúži každá rodina nástrojov. Bez tejto jasnosti agent so štyrmi nástrojmi váha, zbytočne skúša dva z nich a zbytočne zvyšuje latenciu.

Kľúčové poznatky

  • @function_tool mení funkciu Python na nástroj agenta
  • Docstring a typové nápovede automaticky generujú schému JSON
  • Pre komplexné parametre s validáciou použij Pydantic
  • Nástroje vždy vracajú reťazce (JSON, ak sú štruktúrované)
  • Kombinuj svoje vlastné nástroje s WebSearchTool, FileSearchTool a CodeInterpreterTool