Deklarácia nástrojov v SDK
Na tejto strane
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_toolmení 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