Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Deklarace nástrojů v SDK

Lekce 6 z 25 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Deklarace nástrojů v SDK
  2. Dekorátor @function_tool
  3. Přizpůsobení názvu a popisu
  4. Podporované typy parametrů
  5. Návrat strukturovaných výsledků
  6. Nástroje hostované společností OpenAI
  7. Kombinace vlastních a hostovaných nástrojů
  8. Klíčové poznatky

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_tool mě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