Przejdź do głównej treści
Polski— Wybierz język
Menu

Deklarowanie narzędzi w SDK

Lekcja 6 z 25 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Deklarowanie narzędzi w SDK
  2. Dekorator @function_tool
  3. Dostosowanie nazwy i opisu
  4. Obsługiwane typy parametrów
  5. Zwracanie strukturalnych wyników
  6. Narzędzia hostowane przez OpenAI
  7. Łączenie narzędzi własnych i hostowanych
  8. Kluczowe wnioski

Deklarowanie narzędzi w SDK

Narzędzia to konkretne możliwości Twojego agenta. Bez nich agent potrafi jedynie generować tekst; z narzędziami może odpytywać bazy danych, wywoływać API i wysyłać e-maile. Musisz jednak zadeklarować je poprawnie, ponieważ jakość narzędzia zależy nie tylko od samego kodu, ale także od tego, jak dobrze model je zrozumie.

Dekorator @function_tool

Najprostszym sposobem na utworzenie narzędzia jest dekorator @function_tool, który zamienia standardową funkcję Pythona w możliwość dostępną dla agenta.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Wyszukaj klienta po adresie e-mail w bazie danych.

    Args:
        email: Adres e-mail klienta, którego należy wyszukać.
    """
    # W środowisku produkcyjnym: wywołaj swoją bazę danych
    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"Znaleziono klienta: {customer['name']}, plan {customer['plan']}, klient od {customer['since']}"
    return f"Nie znaleziono klienta o adresie e-mail {email}"

Nic nie jest deklarowane dwukrotnie: SDK używa nazwy funkcji jako nazwy narzędzia, docstringa jako opisu, a wskazówek typów do wygenerowania schematu JSON dla parametrów. Innymi słowy, Twój docstring nie jest już tylko komentarzem dla współpracowników; to tekst, który model odczytuje, aby zdecydować, czy wywołać tę funkcję. Niejasny docstring prowadzi do niedokładnych wywołań.

Dostosowanie nazwy i opisu

Gdy nazwa Twojej funkcji wynika z wewnętrznych konwencji, a nie z logiki biznesowej, możesz nadpisać to, co widzi model.

@function_tool(
    name_override="search_crm",
    description_override="Wyszukaj klienta w systemie CRM po e-mailu, nazwisku lub numerze konta."
)
def search_customer(identifier: str) -> str:
    """Wyszukaj klienta."""
    # ...
    return "Wynik"

Obsługiwane typy parametrów

Poza natywnymi typami Pythona, SDK akceptuje modele Pydantic. Gdy narzędzie przyjmuje trzy lub więcej parametrów, zgrupuj je: schemat staje się wtedy bardziej czytelny dla modelu, a walidacja chroni Cię przed wartościami odstającymi.

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

class SearchFilter(BaseModel):
    category: str = Field(description="Kategoria produktu")
    max_price: Optional[float] = Field(None, description="Maksymalna cena w euro")
    in_stock: bool = Field(True, description="Tylko produkty dostępne w magazynie")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Wyszukaj produkty na podstawie określonych kryteriów."""
    results = []
    # Logika wyszukiwania wykorzystująca filter.category, filter.max_price itp.
    return f"Znaleziono {len(results)} produktów w kategorii {filter.category}"

Modele Pydantic automatycznie walidują dane wejściowe i dostarczają modelowi bogate, szczegółowe opisy dla każdego pola.

Zwracanie strukturalnych wyników

Narzędzie zawsze zwraca ciąg znaków (string). Gdy Twoje dane mają strukturę – wiele metryk, lista, mieszane typy – serializuj je jako JSON, zamiast komponować zdanie: model odczyta klucze znacznie可靠niej niż swobodny tekst.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Pobierz statystyki sprzedaży dla danego miesiąca."""
    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)

Narzędzia hostowane przez OpenAI

Oprócz własnych funkcji, SDK zapewnia dostęp do narzędzi zarządzanych przez OpenAI, które działają po stronie platformy.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="Asystent ogólnego przeznaczenia",
    instructions="Jesteś asystentem zdolnym do przeszukiwania sieci, analizowania plików i wykonywania kodu.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool pozwala agentowi przeszukiwać internet w czasie rzeczywistym i nie wymaga żadnej konfiguracji. FileSearchTool przeprowadza wyszukiwanie semantyczne w Twoich plikach, ale zakłada wcześniejszą konfigurację: musisz utworzyć magazyn wektorów poprzez API OpenAI i przesłać do niego swoje dokumenty – stąd parametr vs_abc123. CodeInterpreterTool umożliwia agentowi pisanie i wykonywanie kodu Python w izolowanym kontenerze, co czyni go najlepszym wyborem do analizy danych i generowania wykresów. Wymaga on parametru tool_config, który określa ten kontener: {"type": "auto"} tworzy go na żądanie (SDK openai-agents odrzuci wywołanie CodeInterpreterTool() bez tego parametru).

Łączenie narzędzi własnych i hostowanych

Prawdziwa moc tkwi w kombinacji. Analityk finansowy potrzebuje Twoich danych wewnętrznych, możliwości obliczeniowych i kontekstu rynkowego: trzech źródeł, których żadne pojedyncze narzędzie nie pokrywa.

agent = Agent(
    name="Analityk finansowy",
    instructions="""Jesteś analitykiem finansowym.
    Używaj narzędzi wewnętrznych do pobierania danych,
    interpretera kodu do ich analizy,
    a wyszukiwania w sieci do uzyskania kontekstu rynkowego.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Zauważ, jak instrukcje precyzują przeznaczenie każdej rodziny narzędzi. Bez tej jasności agent mający cztery narzędzia będzie się wahał, niepotrzebnie wypróbuje dwa z nich i zwiększy opóźnienia bez żadnego powodu.

Kluczowe wnioski

  • @function_tool zamienia funkcję Pythona w narzędzie agenta
  • Docstring i wskazówki typów automatycznie generują schemat JSON
  • Używaj Pydantic do złożonych parametrów z walidacją
  • Narzędzia zawsze zwracają ciągi znaków (JSON, jeśli dane są strukturalne)
  • Łącz swoje własne narzędzia z WebSearchTool, FileSearchTool i CodeInterpreterTool