Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Deklarér værktøjer i SDK'et

Lektion 6 af 25 Opdateret 2. november 2026 Udvikler
På denne side
  1. Deklarér værktøjer i SDK’et
  2. Dekoratoren @function_tool
  3. Tilpas navn og beskrivelse
  4. Understøttede parametertyper
  5. Returnér strukturerede resultater
  6. OpenAI-hostede værktøjer
  7. Kombinér egne og hostede værktøjer
  8. Vigtige pointer

Deklarér værktøjer i SDK’et

Værktøjer er din agents konkrete evner. Uden værktøjer kan en agent kun generere tekst; med værktøjer kan den spørge databaser, kalde API’er og sende e-mails. Du skal dog deklarere dem korrekt, for et værktøjs kvalitet afhænger ikke kun af koden – det afhænger også af, hvor godt modellen forstår det.

Dekoratoren @function_tool

Den nemmeste måde at oprette et værktøj på er dekoratoren @function_tool, som omdanner en almindelig Python-funktion til en evne, som agenten kan kalde.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Søg efter en kunde via e-mailadresse i databasen.

    Args:
        email: Kundens e-mailadresse, der skal søges efter.
    """
    # I produktion: kald din 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}"

Intet deklareres to gange: SDK’et bruger funktionens navn som værktøjsnavn, docstrengen som beskrivelse og type hints til at generere JSON-skemaet for parametrene. Med andre ord er din docstreng ikke længere bare en kommentar til dine kolleger; det er den tekst, modellen læser for at beslutte, om den skal kalde denne funktion. En vag docstreng fører til upræcise kald.

Tilpas navn og beskrivelse

Når dit funktionsnavn følger interne konventioner frem for forretningslogik, kan du overskrive det, modellen ser.

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

Understøttede parametertyper

Ud over native Python-typer accepterer SDK’et Pydantic-modeller. Når et værktøj tager tre eller flere parametre, bør du gruppere dem: skemaet bliver mere læsbart for modellen, og valideringen beskytter dig mod uregelmæssige værdier.

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-modeller validerer automatisk input og giver modellen rige, felt-for-felt-beskrivelser.

Returnér strukturerede resultater

Et værktøj returnerer altid en streng. Når dine data har struktur – flere målinger, en liste, blandede typer – skal du serialisere dem som JSON i stedet for at sammensætte en sætning: modellen vil læse nøglerne langt mere pålideligt end fri 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)

OpenAI-hostede værktøjer

Ud over dine egne funktioner giver SDK’et adgang til OpenAI-administrerede værktøjer, der kører på platformsiden.

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 lader agenten søge på internettet i realtid og kræver ingen konfiguration. FileSearchTool udfører semantisk søgning på tværs af dine filer, men forudsætter forudgående opsætning: du skal oprette et vector store via OpenAI API’en og uploade dine dokumenter dertil – heraf vs_abc123 sendt som parameter. CodeInterpreterTool giver agenten mulighed for at skrive og udføre Python-kode i en isoleret container, hvilket gør det til det foretrukne valg til dataanalyse og generering af diagrammer. Det kræver en tool_config, der specificerer denne container: {"type": "auto"} opretter den ved behov (SDK’et openai-agents afviser CodeInterpreterTool() uden denne).

Kombinér egne og hostede værktøjer

Den virkelige styrke ligger i kombinationen. En finansanalytiker har brug for dine interne data, beregningsevner og markedskontekst: tre kilder, som ét enkelt værktøj ikke dækker.

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

Bemærk, hvordan instruktionerne specificerer, hvad hver værktøjsfamilie er til. Uden denne klarhed tøver en agent med fire værktøjer, prøver to unødvendigt og øger ventetiden uden grund.

Vigtige pointer

  • @function_tool omdanner en Python-funktion til et agent-værktøj
  • Docstrengen og type hints genererer automatisk JSON-skemaet
  • Brug Pydantic til komplekse parametre med validering
  • Værktøjer returnerer altid strenge (JSON hvis struktureret)
  • Kombinér dine egne værktøjer med WebSearchTool, FileSearchTool og CodeInterpreterTool