Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Iddikjara l-għodod fl-SDK

Lezzjoni 6 / 25 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Iddikjara l-għodod fl-SDK
  2. Id-dekoratur @function_tool
  3. Ippersonalizza l-isem u d-deskrizzjoni
  4. Tipi ta’ parametri appoġġjati
  5. Irritorna riżultati strutturati
  6. Għodod ospitati minn OpenAI
  7. Iggħaqqad għodod personalizzati u ospitati
  8. Punti Ewlenin

Iddikjara l-għodod fl-SDK

L-għodod huma l-kapaċitajiet konkreti tal-aġent tiegħek. Mingħajr għodod, aġent jista’ biss jiġġenera test; bl-għodod, jista’ jikkonsulta bażijiet tad-data, isejjaħ APIs, u jibgħat emails. Madankollu, trid tiddikjarahom sew, għax il-kwalità ta’ għodda ma tiddependix biss mill-kodiċi tagħha—tiddependi wkoll fuq kemm il-mudell jifhimha tajjeb.

Id-dekoratur @function_tool

L-aktar mod sempliċi biex toħloq għodda huwa d-dekoratur @function_tool, li jibdel funzjoni standard ta’ Python f’kapaċità li l-aġent jista’ jsejjaħ.

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

Xejn ma jiġi ddikjarat darbtejn: l-SDK juża l-isem tal-funzjoni bħala isem l-għodda, id-docstring bħala d-deskrizzjoni, u s-suggerimenti tat-tip (type hints) biex jiġġenera l-iskema JSON għall-parametri. Fi kliem ieħor, id-docstring tiegħek m’għadhiex sempliċiment kumment għall-kollegi tiegħek; hija t-test li l-mudell jaqra biex jiddeċiedi jekk isejjaħx din il-funzjoni. Docstring vaga twassal għal sejħiet mhux preċiżi.

Ippersonalizza l-isem u d-deskrizzjoni

Meta l-isem tal-funzjoni tiegħek isegwi konvenzjonijiet interni minflok loġika tan-negozju, tista’ tibdel dak li l-mudell jara.

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

Tipi ta’ parametri appoġġjati

Barra t-tipi nativi ta’ Python, l-SDK jaċċetta mudelli Pydantic. Meta għodda tieħu tliet parametri jew aktar, iggruppahom: l-iskema ssir aktar leġibbli għall-mudell, u l-validazzjoni tipproteġik minn valuri anomali.

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

Il-mudelli Pydantic jivvalidaw awtomatikament l-inputs u jipprovdu deskrizzjonijiet rikka, kamp b’kamp, lill-mudell.

Irritorna riżultati strutturati

Għodda dejjem tirritorna stringa. Meta d-data tiegħek ikollha struttura—diversi metriċi, lista, tipi mħallta—isserjalizzaha bħala JSON minflok ma tifforma sentenza: il-mudell jaqra l-klavijiet b’mod ferm aktar affidabbli milli jaqra test liberu.

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)

Għodod ospitati minn OpenAI

Barra l-funzjonijiet personalizzati tiegħek, l-SDK jipprovdi aċċess għal għodod immaniġġjati minn OpenAI li jaħdmu fuq in-naħa tal-pjattaforma.

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 jippermetti lill-aġent ifittex l-internet f’ħin reali u ma jeħtieġ l-ebda konfigurazzjoni. FileSearchTool iwettaq tiftix semantiku fil-fajls tiegħek iżda jassumi konfigurazzjoni minn qabel: trid toħloq maħżen vettur permezz tal-API ta’ OpenAI u ttella’ d-dokumenti tiegħek fih—għalhekk il-vs_abc123 mgħoddi bħala parametru. CodeInterpreterTool jippermetti lill-aġent jikteb u jesegwixxi kodiċi Python f’kontenitur iżolat, u jagħmluh l-għażla primarja għall-analiżi tad-data u l-ġenerazzjoni ta’ grafiċi. Jeħtieġ tool_config li jispeċifika dan il-kontenitur: {"type": "auto"} joħloqu meta jkun meħtieġ (l-SDK openai-agents jirrifjuta CodeInterpreterTool() mingħajru).

Iggħaqqad għodod personalizzati u ospitati

Il-qawwa reali tinsab fil-kombinazzjoni. Analiżista finanzjarju jeħtieġ id-data interna tiegħek, il-kapaċitajiet tal-kalkolu, u l-kuntest tas-suq: tliet sorsi li l-ebda għodda waħda ma tkopri.

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

Innota kif l-istruzzjonijiet jispeċifikaw għal xiex tintuża kull familja ta’ għodod. Mingħajr din iċ-ċarezza, aġent b’erba’ għodod jibqa’ dubjuż, jipprova żewġ mingħajr bżonn, u jżid il-latency mingħajr raġuni.

Punti Ewlenin

  • @function_tool ibiddel funzjoni Python f’għodda tal-aġent
  • Id-docstring u s-suggerimenti tat-tip jiġġeneraw awtomatikament l-iskema JSON
  • Uża Pydantic għal parametri kumplessi bil-validazzjoni
  • L-għodod dejjem jirritornaw stringi (JSON jekk ikunu strutturati)
  • Iggħaqqad l-għodod personalizzati tiegħek ma’ WebSearchTool, FileSearchTool, u CodeInterpreterTool