Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Deklariraj orodja v SDK-ju

Lekcija 6 od 25 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Deklariraj orodja v SDK-ju
  2. Okrasnik @function_tool
  3. Prilagodi ime in opis
  4. Podprti tipi parametrov
  5. Vrni strukturirane rezultate
  6. Orodja, ki jih gostuje OpenAI
  7. Združi orodja po meri in gostovana orodja
  8. Ključne ugotovitve

Deklariraj orodja v SDK-ju

Orodja so konkretne zmožnosti tvojega agenta. Brez orodij lahko agent zgolj ustvarja besedilo; z orodji pa lahko poizveduje po bazah podatkov, kliče API-je in pošilja e-pošto. Vendar jih moraš pravilno deklarirati, saj kakovost orodja ni odvisna le od kode, temveč tudi od tega, kako dobro jo model razume.

Okrasnik @function_tool

Najpreprostejši način za ustvarjanje orodja je okrasnik @function_tool, ki standardno funkcijo Python pretvori v zmožnost, ki jo lahko agent pokliče.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Search for a customer by email address in the database.

    Args:
        email: The customer's email address to search for.
    """
    # In production: call your database
    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"Customer found: {customer['name']}, plan {customer['plan']}, customer since {customer['since']}"
    return f"No customer found with email {email}"

Ničesar ne deklariraš dvakrat: SDK uporabi ime funkcije kot ime orodja, docstring kot opis in namige za tipe za generiranje sheme JSON za parametre. Z drugimi besedami, tvoj docstring ni več le komentar za sodelavce; to je besedilo, ki ga model prebere, da se odloči, ali bo poklical to funkcijo. Nejasen docstring vodi do netočnih klicev.

Prilagodi ime in opis

Ko ime tvoje funkcije sledi internim konvencijam namesto poslovni logiki, lahko prepišeš tisto, kar vidi model.

@function_tool(
    name_override="search_crm",
    description_override="Search for a customer in the CRM by email, name, or account number."
)
def search_customer(identifier: str) -> str:
    """Search for a customer."""
    # ...
    return "Result"

Podprti tipi parametrov

Poleg izvornih tipov Python SDK sprejema tudi modele Pydantic. Ko orodje zahteva tri ali več parametrov, jih združi: shema postane za model bolj berljiva, validacija pa te zaščiti pred robnimi vrednostmi.

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

class SearchFilter(BaseModel):
    category: str = Field(description="Product category")
    max_price: Optional[float] = Field(None, description="Maximum price in euros")
    in_stock: bool = Field(True, description="Only products in stock")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Search for products based on specified criteria."""
    results = []
    # Search logic using filter.category, filter.max_price, etc.
    return f"Found {len(results)} products in {filter.category}"

Modeli Pydantic samodejno validirajo vnose in modelu zagotavljajo bogate opise za vsako polje posebej.

Vrni strukturirane rezultate

Orodje vedno vrne niz. Ko imajo tvoji podatki strukturo – več metrik, seznam, mešani tipi – jih serializiraj kot JSON namesto sestavljanja stavka: model bo ključe prebral veliko bolj zanesljivo kot prosto besedilo.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Retrieve sales statistics for a given month."""
    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)

Orodja, ki jih gostuje OpenAI

Poleg tvojih funkcij po meri SDK zagotavlja dostop do orodij, ki jih upravlja OpenAI in tečejo na strani platforme.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="General-purpose assistant",
    instructions="You are an assistant capable of searching the web, analyzing files, and executing code.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool omogoča agentu iskanje po internetu v realnem času in ne zahteva konfiguracije. FileSearchTool izvaja semantično iskanje po tvojih datotekah, vendar predpostavlja predhodno nastavitev: ustvariti moraš vektorsko trgovino prek API-ja OpenAI in vanjo naložiti svoje dokumente – zato parameter vs_abc123. CodeInterpreterTool omogoča agentu pisanje in izvajanje kode Python v izoliranem vsebniku, kar ga dela za prvo izbiro pri analizi podatkov in ustvarjanju grafikonov. Zahteva tool_config, ki določa ta vsebnik: {"type": "auto"} ga ustvari po potrebi (SDK openai-agents zavrne CodeInterpreterTool() brez tega).

Združi orodja po meri in gostovana orodja

Prava moč je v kombinaciji. Finančni analitik potrebuje tvoje interne podatke, zmožnosti izračunavanja in tržni kontekst: trije viri, ki jih nobeno posamezno orodje ne pokriva v celoti.

agent = Agent(
    name="Financial analyst",
    instructions="""You are a financial analyst.
    Use internal tools to retrieve data,
    the code interpreter to analyze it,
    and web search for market context.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Opazi, kako navodila določajo namen vsake družine orodij. Brez te jasnosti agent s štirimi orodji okleva, nepotrebno preizkusi dve in brez razloga poveča zakasnitev.

Ključne ugotovitve

  • @function_tool pretvori funkcijo Python v orodje agenta
  • Docstring in namigi za tipe samodejno generirajo shemo JSON
  • Za kompleksne parametre z validacijo uporabi Pydantic
  • Orodja vedno vračajo nize (JSON, če so strukturirani)
  • Svoja orodja po meri združi z WebSearchTool, FileSearchTool in CodeInterpreterTool