Deklarowanie narzędzi w SDK
Na tej stronie
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_toolzamienia 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