Deklaruoti įrankius SDK
Šiame puslapyje
Deklaruoti įrankius SDK
Įrankiai yra konkretūs tavo agento gebėjimai. Be įrankių agentas gali tik generuoti tekstą; turėdamas įrankių jis gali užklausti duomenų bazes, kviesti API ir siųsti el. laiškus. Tačiau juos reikia tinkamai deklaruoti, nes įrankio kokybė priklauso ne tik nuo kodo – ji taip pat lemia, kaip gerai modelis jį supranta.
Dekoratorius @function_tool
Paprastiausias būdas sukurti įrankį – naudoti dekoratorių @function_tool, kuris standartinę Python funkciją paverčia gebėjimu, kurį agentas gali iškviesti.
from agents import function_tool
@function_tool
def search_customer(email: str) -> str:
"""Ieškoti kliento pagal el. pašto adresą duomenų bazėje.
Args:
email: Kliento el. pašto adresas, pagal kurį ieškoma.
"""
# Gamyboje: kvieskite savo duomenų bazę
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"Klientas rastas: {customer['name']}, planas {customer['plan']}, klientas nuo {customer['since']}"
return f"Nerasta kliento su el. paštu {email}"
Nieko nereikia deklaruoti dukart: SDK naudoja funkcijos pavadinimą kaip įrankio pavadinimą, dokumentacijos eilutę (docstring) kaip aprašymą, o tipų užuominas (type hints) – JSON schemai parametrams sugeneruoti. Kitaip tariant, tavo dokumentacijos eilutė nebėra tik komentaras kolegoms; tai tekstas, kurį modelis skaito spręsdamas, ar kviesti šią funkciją. Neaiški dokumentacijos eilutė lemia netikslius kvietimus.
Tinkinti pavadinimą ir aprašymą
Kai tavo funkcijos pavadinimas atitinka vidines konvencijas, o ne verslo logiką, gali perrašyti tai, ką mato modelis.
@function_tool(
name_override="search_crm",
description_override="Ieškoti kliento CRM sistemoje pagal el. paštą, vardą arba sąskaitos numerį."
)
def search_customer(identifier: str) -> str:
"""Ieškoti kliento."""
# ...
return "Rezultatas"
Palaikomi parametrų tipai
Be natūralių Python tipų, SDK priima Pydantic modelius. Kai įrankis turi tris ar daugiau parametrų, sugrupuok juos: schema tampa modelui skaitomesnė, o validavimas apsaugo nuo netipiškų reikšmių.
from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool
class SearchFilter(BaseModel):
category: str = Field(description="Produkto kategorija")
max_price: Optional[float] = Field(None, description="Maksimali kaina eurais")
in_stock: bool = Field(True, description="Tik sandėlyje esantys produktai")
@function_tool
def search_products(filter: SearchFilter) -> str:
"""Ieškoti produktų pagal nurodytus kriterijus."""
results = []
# Paieškos logika naudojant filter.category, filter.max_price ir kt.
return f"Rasta {len(results)} produktų kategorijoje {filter.category}"
Pydantic modeliai automatiškai validuoja įvestis ir pateikia modeliui išsamius kiekvieno lauko aprašymus.
Grąžinti struktūrizuotus rezultatus
Įrankis visada grąžina eilutę. Kai tavo duomenys turi struktūrą – keli rodikliai, sąrašas, mišrūs tipai – serializuok juos kaip JSON, o ne kurk sakinius: modelis raktus nuskaitys daug patikimiau nei laisvą tekstą.
import json
from agents import function_tool
@function_tool
def get_sales_stats(month: str, year: int) -> str:
"""Gauti pardavimų statistiką nurodytam mėnesiui."""
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)
„OpenAI“ talpinami įrankiai
Be tavo custom funkcijų, SDK suteikia prieigą prie „OpenAI“ valdomų įrankių, kurie vykdomi platformos pusėje.
from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool
agent = Agent(
name="Universalus asistentas",
instructions="Esi asistentas, gebantis ieškoti internete, analizuoti failus ir vykdyti kodą.",
tools=[
WebSearchTool(),
FileSearchTool(
vector_store_ids=["vs_abc123"],
max_num_results=10,
),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
WebSearchTool leidžia agentui realiuoju laiku ieškoti internete ir nereikalauja jokios konfigūracijos. FileSearchTool atlieka semantinę paiešką tarp tavo failų, tačiau daro prielaidą, kad jau atlikai pirminį nustatymą: turi sukurti vektorių saugyklą per „OpenAI“ API ir į ją įkelti dokumentus – todėl parametru perduodamas vs_abc123. CodeInterpreterTool leidžia agentui rašyti ir vykdyti Python kodą izoliuotame konteineryje, todėl tai yra pagrindinis pasirinkimas duomenų analizei ir grafikų generavimui. Jam reikia tool_config, kuris nurodo šį konteinerį: {"type": "auto"} jį sukuria pagal poreikį (be jo openai-agents SDK atmeta CodeInterpreterTool()).
Derinti custom ir talpinamus įrankius
Tikroji galia slypi derinyje. Finansų analitikui reikia tavo vidinių duomenų, skaičiavimo galimybių ir rinkos konteksto: trijų šaltinių, kurių vienas įrankis neapima.
agent = Agent(
name="Finansų analitikas",
instructions="""Esi finansų analitikas.
Naudok vidinius įrankius duomenims gauti,
kodo interpretatorių jiems analizuoti,
o interneto paiešką – rinkos kontekstui."""
tools=[
get_sales_stats,
search_customer,
WebSearchTool(),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
Atkreipk dėmesį, kaip instrukcijose nurodyta, kam skirta kiekviena įrankių šeima. Be šio aiškumo agentas su keturiais įrankiais dvejos, be reikalo bandys du iš jų ir be priežasties padidins delsą.
Svarbiausi punktai
@function_toolpaverčia Python funkciją agento įrankiu- Dokumentacijos eilutė ir tipų užuominos automatiškai sugeneruoja JSON schemą
- Sudėtingiems parametrams su validavimu naudok Pydantic
- Įrankiai visada grąžina eilutes (struktūrizuotiems duomenims – JSON)
- Derink savo custom įrankius su
WebSearchTool,FileSearchToolirCodeInterpreterTool