Deklarace nástrojů v SDK
Na této stránce
Deklarace nástrojů v SDK
Nástroje představují konkrétní schopnosti tvého agenta. Bez nich umí agent pouze generovat text; s nástroji může dotazovat databáze, volat API a odesílat e-maily. Musíš je však správně deklarovat, protože kvalita nástroje nespočívá jen v kódu – záleží také na tom, jak dobře mu model rozumí.
Dekorátor @function_tool
Nejjednodušší způsob, jak vytvořit nástroj, je použít dekorátor @function_tool, který změní běžnou funkci Pythonu na schopnost, kterou může agent vyvolat.
from agents import function_tool
@function_tool
def search_customer(email: str) -> str:
"""Vyhledá zákazníka podle e-mailové adresy v databázi.
Args:
email: E-mailová adresa zákazníka, kterou chceš vyhledat.
"""
# V produkci: zavolej svou databázi
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 nalezen: {customer['name']}, plán {customer['plan']}, zákazník od {customer['since']}"
return f"Žádný zákazník s e-mailem {email} nebyl nalezen"
Nic se nedeklaruje dvakrát: SDK používá název funkce jako název nástroje, docstring jako popis a typové nápovědy (type hints) k vygenerování schématu JSON pro parametry. Jinými slovy, tvůj docstring už není jen komentářem pro kolegy; je to text, který model čte, aby se rozhodl, zda tuto funkci zavolat. Nejasný docstring vede k nepřesným voláním.
Přizpůsobení názvu a popisu
Pokud název tvé funkce následuje interní konvence místo obchodní logiky, můžeš přepsat to, co model vidí.
@function_tool(
name_override="search_crm",
description_override="Vyhledá zákazníka v CRM podle e-mailu, jména nebo čísla účtu."
)
def search_customer(identifier: str) -> str:
"""Vyhledá zákazníka."""
# ...
return "Výsledek"
Podporované typy parametrů
Kromě nativních typů Pythonu přijímá SDK také modely Pydantic. Jakmile nástroj přijímá tři nebo více parametrů, seskup je: schéma se stane pro model čitelnějším a validace tě ochrání před extrémními hodnotami.
from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool
class SearchFilter(BaseModel):
category: str = Field(description="Kategorie produktu")
max_price: Optional[float] = Field(None, description="Maximální cena v eurech")
in_stock: bool = Field(True, description="Pouze produkty skladem")
@function_tool
def search_products(filter: SearchFilter) -> str:
"""Vyhledá produkty na základě zadaných kritérií."""
results = []
# Logika vyhledávání pomocí filter.category, filter.max_price atd.
return f"Nalezeno {len(results)} produktů v kategorii {filter.category}"
Modely Pydantic automaticky validují vstupy a poskytují modelu bohaté popisy pole po poli.
Návrat strukturovaných výsledků
Nástroj vždy vrací řetězec. Když mají tvá data strukturu – více metrik, seznam, smíšené typy – serializuj je jako JSON místo skládání věty: model bude číst klíče mnohem spolehlivěji než volný text.
import json
from agents import function_tool
@function_tool
def get_sales_stats(month: str, year: int) -> str:
"""Získá statistiky prodejů pro daný měsíc."""
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é společností OpenAI
Kromě tvých vlastních funkcí poskytuje SDK přístup k nástrojům spravovaným společností OpenAI, které běží na straně platformy.
from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool
agent = Agent(
name="Univerzální asistent",
instructions="Jsi asistent schopný vyhledávat na webu, analyzovat soubory a spouštět 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 vyhledávat na internetu v reálném čase a nevyžaduje žádnou konfiguraci. FileSearchTool provádí sémantické vyhledávání napříč tvými soubory, ale předpokládá předchozí nastavení: musíš vytvořit úložiště vektorů prostřednictvím API OpenAI a nahrát do něj své dokumenty – proto je jako parametr předáno vs_abc123. CodeInterpreterTool umožňuje agentovi psát a spouštět kód Pythonu v izolovaném kontejneru, což z něj činí nejlepší volbu pro analýzu dat a generování grafů. Vyžaduje tool_config, který specifikuje tento kontejner: {"type": "auto"} jej vytvoří na vyžádání (SDK openai-agents odmítne CodeInterpreterTool() bez něj).
Kombinace vlastních a hostovaných nástrojů
Skutečná síla spočívá v kombinaci. Finanční analytik potřebuje tvá interní data, výpočetní schopnosti a kontext trhu: tři zdroje, které žádný jediný nástroj nepokrývá.
agent = Agent(
name="Finanční analytik",
instructions="""Jsi finanční analytik.
Použij interní nástroje k získání dat,
interpret kódu k jejich analýze
a vyhledávání na webu pro kontext trhu.""",
tools=[
get_sales_stats,
search_customer,
WebSearchTool(),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
Všimni si, jak pokyny specifikují, k čemu slouží každá rodina nástrojů. Bez této jasnosti agent se čtyřmi nástroji váhá, zbytečně zkouší dva z nich a bezdůvodně zvyšuje latenci.
Klíčové poznatky
@function_toolmění funkci Pythonu na nástroj agenta- Docstring a typové nápovědy automaticky generují schéma JSON
- Pro složité parametry s validací použij Pydantic
- Nástroje vždy vracejí řetězce (JSON, pokud jsou strukturované)
- Kombinuj své vlastní nástroje s WebSearchTool, FileSearchTool a CodeInterpreterTool