Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Tools declareren in de SDK

Les 6 van 25 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Tools declareren in de SDK
  2. De @function_tool-decorator
  3. Naam en beschrijving aanpassen
  4. Ondersteunde parametertypes
  5. Gestructureerde resultaten retourneren
  6. Door OpenAI gehoste tools
  7. Eigen en gehoste tools combineren
  8. Belangrijkste punten

Tools declareren in de SDK

Tools zijn de concrete mogelijkheden van uw agent. Zonder tools kan een agent alleen tekst genereren; met tools kan deze databases bevragen, API’s aanroepen en e-mails verzenden. U moet ze echter correct declareren, want de kwaliteit van een tool hangt niet alleen af van de code, maar ook van hoe goed het model deze begrijpt.

De @function_tool-decorator

De eenvoudigste manier om een tool te maken, is de @function_tool-decorator. Deze zet een standaard Python-functie om in een mogelijkheid die de agent kan aanroepen.

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

Er wordt niets dubbel gedeclareerd: de SDK gebruikt de naam van de functie als toolnaam, de docstring als beschrijving en de type hints om het JSON-schema voor de parameters te genereren. Uw docstring is dus niet langer slechts een commentaar voor uw collega’s; het is de tekst die het model leest om te beslissen of het deze functie moet aanroepen. Een vaag docstring leidt tot onnauwkeurige aanroepen.

Naam en beschrijving aanpassen

Wanneer uw functienaam interne conventies volgt in plaats van bedrijfslogica, kunt u overschrijven wat het model ziet.

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

Ondersteunde parametertypes

Naast native Python-types accepteert de SDK ook Pydantic-modellen. Zodra een tool drie of meer parameters heeft, groepeert u deze: het schema wordt dan beter leesbaar voor het model en validatie beschermt u tegen afwijkende waarden.

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-modellen valideren invoer automatisch en bieden het model gedetailleerde beschrijvingen per veld.

Gestructureerde resultaten retourneren

Een tool retourneert altijd een string. Wanneer uw data structuur heeft—meerdere metrics, een lijst, gemengde types—serializeert u deze als JSON in plaats van een zin samen te stellen: het model leest de sleutels veel betrouwbaarder dan vrije tekst.

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)

Door OpenAI gehoste tools

Naast uw eigen functies biedt de SDK toegang tot door OpenAI beheerde tools die aan de platformzijde draaien.

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

Met WebSearchTool kan de agent in realtime op internet zoeken; hiervoor is geen configuratie nodig. FileSearchTool voert semantisch zoeken uit in uw bestanden, maar veronderstelt voorafgaande setup: u moet een vectorstore maken via de OpenAI API en uw documenten daar naar uploaden—vandaar de vs_abc123 die als parameter wordt doorgegeven. CodeInterpreterTool stelt de agent in staat Python-code te schrijven en uit te voeren in een geïsoleerde container, waardoor dit de aangewezen keuze is voor data-analyse en het genereren van grafieken. Het vereist een tool_config die deze container specificeert: {"type": "auto"} maakt deze on-demand aan (de openai-agents SDK weigert CodeInterpreterTool() zonder deze configuratie).

Eigen en gehoste tools combineren

De echte kracht zit in de combinatie. Een financieel analist heeft uw interne data, rekenmogelijkheden en marktcontext nodig: drie bronnen die geen enkele tool alleen dekt.

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

Merk op hoe de instructies specificeren waar elke toolfamilie voor dient. Zonder deze duidelijkheid aarzelt een agent met vier tools, probeert er twee onnodig en verhoogt de latentie zonder reden.

Belangrijkste punten

  • @function_tool zet een Python-functie om in een agent-tool
  • De docstring en type hints genereren automatisch het JSON-schema
  • Gebruik Pydantic voor complexe parameters met validatie
  • Tools retourneren altijd strings (JSON bij gestructureerde data)
  • Combineer uw eigen tools met WebSearchTool, FileSearchTool en CodeInterpreterTool