Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Määritä työkalut SDK:ssa

Oppitunti 6 / 25 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Määritä työkalut SDK:ssa
  2. @function_tool-dekoraattori
  3. Nimen ja kuvauksen mukauttaminen
  4. Tuetut parametritypit
  5. Palauta jäsennellyt tulokset
  6. OpenAI:n isännöimät työkalut
  7. Yhdistä omat ja isännöidyt työkalut
  8. Keskeiset asiat

Määritä työkalut SDK:ssa

Työkalut ovat agenttisi konkreettisia kykyjä. Ilman työkaluja agentti osaa vain tuottaa tekstiä; työkalujen avulla se voi hakea tietokannoista, kutsua rajapintoja ja lähettää sähköposteja. Sinun on kuitenkin määritettävä ne oikein, sillä työkalun laatu ei riipu pelkästään koodista, vaan myös siitä, kuinka hyvin malli ymmärtää sitä.

@function_tool-dekoraattori

Yksinkertaisin tapa luoda työkalu on @function_tool-dekoraattori, joka muuttaa tavallisesta Python-funktiosta agentin kutsuttavan kyvyn.

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}"

Mitään ei määritetä kahteen kertaan: SDK käyttää funktion nimeä työkalun nimenä, dokumentaatiomerkkijonoa (docstring) kuvauksena ja tyypitysvihjeitä luodakseen parametrien JSON-skeeman. Toisin sanoen dokumentaatiomerkkijonosi ei ole enää pelkkä kommentti kollegoillesi; se on teksti, jonka malli lukee päättäessään, kutsutaanko tämä funktio. Epämääräinen dokumentaatio johtaa epätarkkoihin kutsuihin.

Nimen ja kuvauksen mukauttaminen

Kun funktionimi noudattaa sisäisiä käytäntöjä eikä liiketoimintalogiikkaa, voit ohittaa mallille näkyvät arvot.

@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"

Tuetut parametritypit

Natiivien Python-tyyppien lisäksi SDK hyväksyy Pydantic-malleja. Kun työkalu ottaa vastaan kolme tai useampia parametreja, ryhmitä ne: skeemasta tulee mallille luettavampi, ja validointi suojaa sinua poikkeavilta arvoilta.

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}"

Pydantic-mallit validoivat syötteet automaattisesti ja tarjoavat mallille rikkaat, kenttäkohtaiset kuvaukset.

Palauta jäsennellyt tulokset

Työkalu palauttaa aina merkkijonon. Kun datassasi on rakenne – useita mittareita, lista, sekatyyppejä – serialisoi se JSON-muotoon äläkä muodosta lausetta: malli lukee avaimet paljon luotettavammin kuin vapaan tekstin.

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)

OpenAI:n isännöimät työkalut

Omien funktioidesi lisäksi SDK tarjoaa pääsyn OpenAI:n hallinnoimiin työkaluihin, jotka suoritetaan alustan puolella.

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 antaa agentin hakea internetistä reaaliajassa eikä vaadi konfigurointia. FileSearchTool suorittaa semanttista hakua tiedostoistasi, mutta olettaa esiasennuksen: sinun on luotava vektorivarasto OpenAI API:n kautta ja ladattava dokumenttisi siihen – siksi parametrina annetaan vs_abc123. CodeInterpreterTool mahdollistaa sen, että agentti kirjoittaa ja suorittaa Python-koodia eristetyssä kontissa, mikä tekee siitä ensisijaisen valinnan data-analyysiin ja kaavioiden tuottamiseen. Se vaatii tool_config-asetuksen, joka määrittää tämän kontin: {"type": "auto"} luo sen tarvittaessa (openai-agents-SDK hylkää CodeInterpreterTool()-kutsun ilman tätä).

Yhdistä omat ja isännöidyt työkalut

Todellinen voima piilee yhdistelmissä. Rahoitusanalyytikko tarvitsee sisäistä dataasi, laskentakykyä ja markkinakontekstia: kolme lähdettä, joita yksikään työkalu ei kata yksinään.

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"}}),
    ],
)

Huomaa, kuinka ohjeistuksessa määritellään, mihin kukin työkaluryhmä on tarkoitettu. Ilman tätä selkeyttä neljän työkalun agentti epäröi, kokeilee kahta tarpeettomasti ja kasvattaa viivettä turhaan.

Keskeiset asiat

  • @function_tool muuttaa Python-funktion agentin työkaluksi
  • Dokumentaatiomerkkijono ja tyypitysvihjeet generoivat automaattisesti JSON-skeeman
  • Käytä Pydanticia monimutkaisiin parametreihin validoinnin kera
  • Työkalut palauttavat aina merkkijonoja (JSON, jos data on jäsenneltyä)
  • Yhdistä omat työkalusi WebSearchTool-, FileSearchTool- ja CodeInterpreterTool-työkaluihin