Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Deklariraj alate u SDK-u

Lekcija 6 od 25 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Deklariraj alate u SDK-u
  2. Dekorator @function_tool
  3. Prilagodi ime i opis
  4. Podržani tipovi parametara
  5. Vrati strukturirane rezultate
  6. Alati koje hosta OpenAI
  7. Kombiniraj prilagođene i hostane alate
  8. Ključne točke

Deklariraj alate u SDK-u

Alati su konkretne sposobnosti tvog agenta. Bez alata, agent može samo generirati tekst; s alatima, može upitavati baze podataka, zvati API-je i slati e-mailove. Moraš ih ipak ispravno deklarirati jer kvaliteta alata ne ovisi samo o kodu – već i o tome koliko dobro model razumije taj alat.

Dekorator @function_tool

Najjednostavniji način stvaranja alata je dekorator @function_tool, koji pretvara standardnu Python funkciju u sposobnost koju agent može pozvati.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Pretraži kupca po e-mail adresi u bazi podataka.

    Args:
        email: E-mail adresa kupca koju treba pronaći.
    """
    # U produkciji: pozovi svoju bazu podataka
    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"Kupac pronađen: {customer['name']}, plan {customer['plan']}, kupac od {customer['since']}"
    return f"Nije pronađen kupac s e-mailom {email}"

Ništa se ne deklarira dvaput: SDK koristi ime funkcije kao ime alata, docstring kao opis, a tipove u hintovima za generiranje JSON sheme parametara. Drugim riječima, tvoj docstring više nije samo komentar za kolege; to je tekst koji model čita kako bi odlučio hoće li pozvati tu funkciju. Nejasan docstring vodi do nepreciznih poziva.

Prilagodi ime i opis

Kada ime tvoje funkcije slijedi interne konvencije umjesto poslovne logike, možeš nadjačati ono što model vidi.

@function_tool(
    name_override="search_crm",
    description_override="Pretraži kupca u CRM-u po e-mailu, imenu ili broju računa."
)
def search_customer(identifier: str) -> str:
    """Pretraži kupca."""
    # ...
    return "Rezultat"

Podržani tipovi parametara

Osim nativnih Python tipova, SDK prihvaća i Pydantic modele. Kada alat prima tri ili više parametara, grupiraj ih: shema postaje čitljivija modelu, a validacija te štiti od rubnih vrijednosti.

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

class SearchFilter(BaseModel):
    category: str = Field(description="Kategorija proizvoda")
    max_price: Optional[float] = Field(None, description="Maksimalna cijena u eurima")
    in_stock: bool = Field(True, description="Samo proizvodi na zalihama")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Pretraži proizvode na temelju zadanih kriterija."""
    results = []
    # Logika pretraživanja koristeći filter.category, filter.max_price, itd.
    return f"Pronađeno {len(results)} proizvoda u kategoriji {filter.category}"

Pydantic modeli automatski validiraju ulaze i modelu pružaju bogate opise polje po polje.

Vrati strukturirane rezultate

Alat uvijek vraća string. Kada tvoji podaci imaju strukturu – više metrika, lista, mješoviti tipovi – serijaliziraj ih kao JSON umjesto sastavljanja rečenice: model će puno pouzdanije čitati ključeve nego slobodan tekst.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Dohvati statistiku prodaje za određeni mjesec."""
    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)

Alati koje hosta OpenAI

Osim tvojih prilagođenih funkcija, SDK pruža pristup alatima kojima upravlja OpenAI, a koji se izvršavaju na strani platforme.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="Asistent opće namjene",
    instructions="Ti si asistent sposoban za pretraživanje weba, analizu datoteka i izvršavanje koda.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool omogućuje agentu pretraživanje interneta u stvarnom vremenu i ne zahtijeva konfiguraciju. FileSearchTool obavlja semantičko pretraživanje tvojih datoteka, ali podrazumijeva prethodnu postavku: moraš stvoriti vektorsku pohranu putem OpenAI API-ja i u nju učitati svoje dokumente – stoga se vs_abc123 prosljeđuje kao parametar. CodeInterpreterTool omogućuje agentu pisanje i izvršavanje Python koda u izoliranom kontejneru, što ga čini najboljim izborom za analizu podataka i generiranje grafikona. Zahtijeva tool_config koji specificira taj kontejner: {"type": "auto"} stvara ga po potrebi (SDK openai-agents odbija CodeInterpreterTool() bez toga).

Kombiniraj prilagođene i hostane alate

Prava snaga leži u kombinaciji. Financijskom analitičaru trebaju tvoji interni podaci, mogućnosti izračuna i tržišni kontekst: tri izvora koje nijedan pojedinačni alat ne pokriva.

agent = Agent(
    name="Financijski analitičar",
    instructions="""Ti si financijski analitičar.
    Koristi interne alate za dohvat podataka,
    interpreter koda za njihovu analizu,
    a web pretraživanje za tržišni kontekst.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Primijeti kako upute specificiraju čemu služi svaka obitelj alata. Bez ove jasnoće, agent s četiri alata oklijeva, nepotrebno isprobava dva od njih i povećava latenciju bez razloga.

Ključne točke

  • @function_tool pretvara Python funkciju u alat za agenta
  • Docstring i hintovi tipova automatski generiraju JSON shemu
  • Koristi Pydantic za kompleksne parametre s validacijom
  • Alati uvijek vraćaju stringove (JSON ako su strukturirani)
  • Kombiniraj svoje prilagođene alate s WebSearchTool, FileSearchTool i CodeInterpreterTool