Deklariraj alate u SDK-u
Na ovoj stranici
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_toolpretvara 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