Salt la conținutul principal
Română— Alege o limbă
Meniu

Declararea instrumentelor în SDK

Lecția 6 din 25 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Declararea instrumentelor în SDK
  2. Decoratorul @function_tool
  3. Personalizarea numelui și a descrierii
  4. Tipuri de parametri acceptați
  5. Returnarea rezultatelor structurate
  6. Instrumente găzduite de OpenAI
  7. Combinarea instrumentelor personalizate cu cele găzduite
  8. Puncte cheie

Declararea instrumentelor în SDK

Instrumentele reprezintă capacitățile concrete ale agentului dumneavoastră. Fără instrumente, un agent poate genera doar text; cu instrumente, acesta poate interoga baze de date, poate apela API-uri și poate trimite e-mailuri. Trebuie însă să le declarați corect, deoarece calitatea unui instrument nu depinde doar de codul său, ci și de modul în care modelul îl înțelege.

Decoratorul @function_tool

Cea mai simplă metodă de a crea un instrument este decoratorul @function_tool, care transformă o funcție Python standard într-o capacitate pe care agentul o poate apela.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Caută un client după adresa de e-mail în baza de date.

    Args:
        email: Adresa de e-mail a clientului pe care doriți să o căutați.
    """
    # În producție: apelați baza de date
    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"Client găsit: {customer['name']}, plan {customer['plan']}, client din {customer['since']}"
    return f"Niciun client găsit cu e-mailul {email}"

Nimic nu este declarat de două ori: SDK-ul utilizează numele funcției ca nume al instrumentului, docstring-ul ca descriere și indicatiile de tip (type hints) pentru a genera schema JSON a parametrilor. Cu alte cuvinte, docstring-ul dumneavoastră nu mai este doar un comentariu pentru colegi; este textul pe care modelul îl citește pentru a decide dacă să apeleze această funcție. Un docstring vag duce la apeluri imprecise.

Personalizarea numelui și a descrierii

Când numele funcției dumneavoastră respectă convenții interne și nu logica de afaceri, puteți suprascrie ceea ce vede modelul.

@function_tool(
    name_override="search_crm",
    description_override="Caută un client în CRM după e-mail, nume sau număr de cont."
)
def search_customer(identifier: str) -> str:
    """Caută un client."""
    # ...
    return "Rezultat"

Tipuri de parametri acceptați

Dincolo de tipurile native Python, SDK-ul acceptă modele Pydantic. Atunci când un instrument primește trei sau mai mulți parametri, grupați-i: schema devine mai lizibilă pentru model, iar validarea vă protejează de valori aberante.

from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool

class SearchFilter(BaseModel):
    category: str = Field(description="Categoria produsului")
    max_price: Optional[float] = Field(None, description="Prețul maxim în euro")
    in_stock: bool = Field(True, description="Doar produsele aflate în stoc")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Caută produse pe baza criteriilor specificate."""
    results = []
    # Logica de căutare folosind filter.category, filter.max_price, etc.
    return f"Au fost găsite {len(results)} produse în categoria {filter.category}"

Modelele Pydantic validează automat intrările și oferă modelului descrieri detaliate, câmp cu câmp.

Returnarea rezultatelor structurate

Un instrument returnează întotdeauna un șir de caractere (string). Când datele dumneavoastră au o structură—mai multe metrici, o listă, tipuri mixte—serializați-le ca JSON în loc să compuneți o propoziție: modelul va citi cheile mult mai fiabil decât textul liber.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Obține statisticile de vânzări pentru o lună dată."""
    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)

Instrumente găzduite de OpenAI

Pe lângă funcțiile personalizate, SDK-ul oferă acces la instrumente gestionate de OpenAI, care rulează din partea platformei.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="Asistent cu scop general",
    instructions="Sunteți un asistent capabil să caute pe web, să analizeze fișiere și să execute cod.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool permite agentului să caute pe internet în timp real și nu necesită nicio configurare. FileSearchTool efectuează o căutare semantică în fișierele dumneavoastră, dar presupune o configurare prealabilă: trebuie să creați un stoc vectorial prin API-ul OpenAI și să încărcați documentele în acesta—de aici parametrul vs_abc123. CodeInterpreterTool permite agentului să scrie și să execute cod Python într-un container izolat, fiind alegerea ideală pentru analiza datelor și generarea de grafice. Acesta necesită un tool_config care specifică containerul: {"type": "auto"} îl creează la cerere (SDK-ul openai-agents respinge CodeInterpreterTool() fără acesta).

Combinarea instrumentelor personalizate cu cele găzduite

Adevărata putere rezidă în combinare. Un analist financiar are nevoie de datele interne, de capacitățile de calcul și de contextul pieței: trei surse pe care niciun singur instrument nu le acoperă.

agent = Agent(
    name="Analist financiar",
    instructions="""Sunteți un analist financiar.
    Utilizați instrumentele interne pentru a prelua date,
    interpretul de cod pentru a le analiza
    și căutarea pe web pentru contextul pieței.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Observați cum instrucțiunile specifică scopul fiecărei familii de instrumente. Fără această claritate, un agent cu patru instrumente ezită, încearcă două în mod inutil și mărește latența fără motiv.

Puncte cheie

  • @function_tool transformă o funcție Python într-un instrument pentru agent
  • Docstring-ul și indicatiile de tip generează automat schema JSON
  • Utilizați Pydantic pentru parametri complecși cu validare
  • Instrumentele returnează întotdeauna șiruri de caractere (JSON dacă sunt structurate)
  • Combinați instrumentele personalizate cu WebSearchTool, FileSearchTool și CodeInterpreterTool