Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Tööriistade deklareerimine SDK-s

Õppetund 6 / 25 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Tööriistade deklareerimine SDK-s
  2. Dekoraator @function_tool
  3. Nime ja kirjelduse kohandamine
  4. Toetatud parameetritüübid
  5. Tagasta struktureeritud tulemused
  6. OpenAI majutatud tööriistad
  7. Kombineeri kohandatud ja majutatud tööriistu
  8. Peamised punktid

Tööriistade deklareerimine SDK-s

Tööriistad on sinu agendi konkreetsed võimed. Ilma tööriistadeta suudab agent vaid teksti genereerida; koos nendega saab ta päringuid teha andmebaasidesse, kutsuda API-sid ja saata meile. Sa pead need siiski korrektselt deklareerima, sest tööriista kvaliteet ei sõltu ainult selle koodist – oluline on ka see, kui hästi mudel seda mõistab.

Dekoraator @function_tool

Lihtsaim viis tööriista loomiseks on dekoraator @function_tool, mis muudab tavalise Pythoni funktsiooni võimeks, mida agent saab kutsuda.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Otsi klienti e-posti aadressi järgi andmebaasist.

    Args:
        email: Kliendi e-posti aadress, mida otsida.
    """
    # Tootmises: helista oma andmebaasi
    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"Klient leitud: {customer['name']}, pakett {customer['plan']}, klient alates {customer['since']}"
    return f"Ühtegi klienti e-postiga {email} ei leitud"

Midagi ei deklareerita kaks korda: SDK kasutab funktsiooni nime tööriista nimena, dokumentatsioonistringi (docstring) kirjeldusena ja tüübiviiteid parameetrite JSON-skeemi genereerimiseks. Teisisõnu, sinu dokumentatsioonistring ei ole enam lihtalt kommentaar kolleegidele; see on tekst, mida mudel loeb, et otsustada, kas seda funktsiooni kutsuda. Ebamäärane dokumentatsioonistring viib ebatäpsete kutseteni.

Nime ja kirjelduse kohandamine

Kui sinu funktsiooni nimi järgib sisemisi kokkuleppeid mitte aga äriloogikat, saad üle kirjutada selle, mida mudel näeb.

@function_tool(
    name_override="search_crm",
    description_override="Otsi klienti CRM-ist e-posti, nime või kontonumbri järgi."
)
def search_customer(identifier: str) -> str:
    """Otsi klienti."""
    # ...
    return "Tulemus"

Toetatud parameetritüübid

Lisaks loomulikele Pythoni tüüpidele aktsepteerib SDK Pydanticu mudeleid. Kui tööriist võtab vastu kolm või enam parameetrit, rühmesta need: skeem muutub mudelile loetavamaks ja valideerimine kaitseb sind äärmuslike väärtuste eest.

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

class SearchFilter(BaseModel):
    category: str = Field(description="Toote kategooria")
    max_price: Optional[float] = Field(None, description="Maksimaalne hind eurodes")
    in_stock: bool = Field(True, description="Ainult laos olevad tooted")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Otsi tooteid määratud kriteeriumide põhjal."""
    results = []
    # Otsingu loogika kasutades filter.category, filter.max_price jne.
    return f"Leitud {len(results)} toodet kategoorias {filter.category}"

Pydanticu mudelid valideerivad sisendeid automaatselt ja pakuvad mudelile rikkalikku väljapõhist kirjeldust.

Tagasta struktureeritud tulemused

Tööriist tagastab alati stringi. Kui sinu andmetel on struktuur – mitu mõõdikut, loend, segatüübid – siis seerialiseeri need JSON-ina, mitte ära komponeeri lauset: mudel loeb võtmeid palju usaldusväärsemalt kui vaba teksti.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Too müügistatistika antud kuu kohta."""
    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 majutatud tööriistad

Lisaks sinu kohandatud funktsioonidele pakub SDK juurdepääsu OpenAI hallatavatele tööriistadele, mis jooksevad platvormi poolel.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="Üldotstarbeline assistent",
    instructions="Oled assistent, kes suudab otsida veebist, analüüsida faile ja käivitada koodi.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool võimaldagendil otsida internetist reaalajas ega vaja konfiguratsiooni. FileSearchTool teostab semantilist otsingut sinu failides, kuid eeldab eelnevat seadistamist: pead looma vektorpoe OpenAI API kaudu ja laadima sinna oma dokumendid – seetõttu antakse parameetrina edasi vs_abc123. CodeInterpreterTool võimaldab agendil kirjutada ja käivitada Pythoni koodi isoleeritud konteineris, muutes selle andmeanalüüsi ja diagrammide genereerimise esmavalikuks. See nõuab tool_config’i, mis määrab selle konteineri: {"type": "auto"} loob selle nõudmisel (SDK openai-agents lükkab CodeInterpreterTool() ilma selleta tagasi).

Kombineeri kohandatud ja majutatud tööriistu

Tegelik jõud peitub kombinatsioonis. Finantsanalüütik vajab sinu sisemisi andmeid, arvutusvõimet ja turukonteksti: kolm allikat, mida ükski ainus tööriist ei kata.

agent = Agent(
    name="Finantsanalüütik",
    instructions="""Oled finantsanalüütik.
    Kasuta sisemisi tööriistu andmete toomiseks,
    koodi interpretaatorit nende analüüsimiseks
    ja veebiotsingut turukonteksti jaoks.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Pane tähele, kuidas juhised täpsustavad, milleks iga tööriistade perekond mõeldud on. Ilma selle selguseta kõhkleb nelja tööriistaga agent, proovib kahte asjatult ja suurendab latentsust ilma igasuguse põhjuseta.

Peamised punktid

  • @function_tool muudab Pythoni funktsiooni agendi tööriistaks
  • Dokumentatsioonistring ja tüübiviited genereerivad automaatselt JSON-skeemi
  • Kasuta Pydanticut keerukate parameetrite jaoks koos valideerimisega
  • Tööriistad tagastavad alati stringe (struktureeritud andmete puhul JSON-i)
  • Kombineeri oma kohandatud tööriistu WebSearchTool, FileSearchTool ja CodeInterpreterTool-ga