Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Deklarera verktyg i SDK:t

Lektion 6 av 25 Uppdaterad 2 november 2026 Utvecklare
På denna sida
  1. Deklarera verktyg i SDK:t
  2. Dekoratorn @function_tool
  3. Anpassa namn och beskrivning
  4. Parametertyper som stöds
  5. Returnera strukturerade resultat
  6. OpenAI-hostade verktyg
  7. Kombinera anpassade och hostade verktyg
  8. Viktiga punkter

Deklarera verktyg i SDK:t

Verktyg är din agents konkreta förmågor. Utan verktyg kan en agent bara generera text; med verktyg kan den fråga databaser, anropa API:er och skicka e-post. Du måste dock deklarera dem korrekt, eftersom ett verktygs kvalitet inte bara handlar om koden – det beror också på hur väl modellen förstår det.

Dekoratorn @function_tool

Det enklaste sättet att skapa ett verktyg är dekoratorn @function_tool, som omvandlar en vanlig Python-funktion till en förmåga som agenten kan anropa.

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

Inget deklareras två gånger: SDK:t använder funktionens namn som verktygsnamn, docstringen som beskrivning och typannoteringarna för att generera JSON-schemat för parametrarna. Med andra ord är din docstring inte längre bara en kommentar för dina kollegor; det är texten modellen läser för att avgöra om den ska anropa denna funktion. En otydlig docstring leder till felaktiga anrop.

Anpassa namn och beskrivning

När ditt funktionsnamn följer interna konventioner snarare än affärslogik kan du åsidosätta vad 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"

Parametertyper som stöds

Utöver inbyggda Python-typer accepterar SDK:t Pydantic-modeller. När ett verktyg tar tre eller fler parametrar bör du gruppera dem: schemat blir mer läsbart för modellen, och valideringen skyddar dig från avvikande värden.

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 validerar automatiskt indata och ger modellen detaljerade beskrivningar fält för fält.

Returnera strukturerade resultat

Ett verktyg returnerar alltid en sträng. När din data har struktur – flera mätvärden, en lista, blandade typer – ska du serialisera den som JSON istället för att komponera en mening: modellen läser nycklarna betydligt mer tillförlitligt än fri text.

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-hostade verktyg

Utöver dina egna funktioner ger SDK:t tillgång till OpenAI-hanterade verktyg som körs på plattformssidan.

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 låter agenten söka på internet i realtid och kräver ingen konfiguration. FileSearchTool utför semantisk sökning i dina filer men förutsätter förberedelser: du måste skapa en vektorlagring via OpenAI API och ladda upp dina dokument dit – därav vs_abc123 som skickas som parameter. CodeInterpreterTool låter agenten skriva och köra Python-kod i en isolerad container, vilket gör det till det självklara valet för dataanalys och diagramgenerering. Det kräver en tool_config som specificerar denna container: {"type": "auto"} skapar den vid behov (SDK:t openai-agents avvisar CodeInterpreterTool() utan detta).

Kombinera anpassade och hostade verktyg

Den verkliga kraften ligger i kombinationen. En finansanalytiker behöver dina interna data, beräkningsförmåga och marknadskontext: tre källor som inget enskilt verktyg täcker.

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

Lägg märke till hur instruktionerna specificerar vad varje verktygsfamilj är till för. Utan denna tydlighet tvekar en agent med fyra verktyg, provar två i onödan och ökar latensen utan anledning.

Viktiga punkter

  • @function_tool omvandlar en Python-funktion till ett agentverktyg
  • Docstringen och typannoteringarna genererar automatiskt JSON-schemat
  • Använd Pydantic för komplexa parametrar med validering
  • Verktyg returnerar alltid strängar (JSON om strukturerat)
  • Kombinera dina anpassade verktyg med WebSearchTool, FileSearchTool och CodeInterpreterTool