Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Deklaruoti įrankius SDK

Paskaita 6 iš 25 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Deklaruoti įrankius SDK
  2. Dekoratorius @function_tool
  3. Tinkinti pavadinimą ir aprašymą
  4. Palaikomi parametrų tipai
  5. Grąžinti struktūrizuotus rezultatus
  6. „OpenAI“ talpinami įrankiai
  7. Derinti custom ir talpinamus įrankius
  8. Svarbiausi punktai

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_tool paverč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, FileSearchTool ir CodeInterpreterTool