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

Instrumente asincrone și paralele

Lecția 8 din 25 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Instrumente asincrone și paralele
  2. Instrumente asincrone
  3. Paralelism automat
  4. Controlul paralelismului
  5. Model: Agregarea rezultatelor paralele
  6. Timeout-uri și reziliență
  7. Performanță: Impactul paralelismului
  8. Puncte cheie

Instrumente asincrone și paralele

În producție, instrumentele dumneavoastră apelează API-uri externe, interoghează baze de date sau efectuează operațiuni de I/O. Aceste operațiuni necesită timp, iar acest timp se acumulează: un agent care înlănțuie cinci apeluri de câte o secundă va răspunde în cinci secunde. Transformarea instrumentelor în versiuni asincrone și valorificarea paralelismului nativ al SDK-ului fac diferența dintre un demo și un serviciu utilizabil.

Instrumente asincrone

Decoratorul @function_tool suportă nativ funcțiile async. Nu este necesară nicio configurare: declarați async def, utilizați un client HTTP asincron, iar SDK-ul se ocupă de rest.

import httpx
from agents import function_tool

@function_tool
async def search_company(name: str) -> str:
    """Caută informații despre companie prin API-ul Societe.com."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.societe.com/v1/search",
            params={"q": name},
            timeout=10,
        )
        if response.status_code == 200:
            data = response.json()
            return f"Companie: {data['name']}, SIREN: {data['siren']}, Venit: {data['revenue']}"
        return f"Niciun rezultat pentru '{name}'"

@function_tool
async def verify_solvency(siren: str) -> str:
    """Verifică solvabilitatea unei companii pe baza numărului său SIREN."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://api.credit-scoring.com/v1/{siren}",
            timeout=10,
        )
        data = response.json()
        return f"Scor de solvabilitate: {data['score']}/100, risc: {data['risk_level']}"

Când Runner execută un instrument asincron, acesta nu blochează bucla de evenimente. Într-un server FastAPI, acest lucru înseamnă că alte cereri continuă să fie procesate în timp ce agentul dumneavoastră așteaptă răspunsul de la API-ul Societe.com.

Paralelism automat

Două instrumente asincrone independente pot rula simultan. Modelul decide acest lucru, iar instrucțiunile dumneavoastră pot încuraja explicit acest comportament.

from agents import Agent, Runner

agent = Agent(
    name="Analist B2B",
    instructions="""Analizați companiile pentru decizii de afaceri.
    Când vi se cere să analizați o companie, preluați informațiile despre aceasta
    ȘI verificați-i solvabilitatea în același timp.""",
    tools=[search_company, verify_solvency],
    model="gpt-5.6-terra",
)

# Modelul va lansa ambele instrumente în paralel
result = await Runner.run(
    agent,
    "Analizează compania Acme Corp (SIREN 123456789)"
)

Deoarece SIREN este furnizat în interogare, verificarea solvabilității nu așteaptă căutarea companiei: SDK-ul execută ambele apeluri simultan. Timpul total este egal cu durata celui mai lent instrument, nu suma ambelor.

Controlul paralelismului

Paralelismul nu este întotdeauna de dorit. Dacă instrumentele dumneavoastră scriu în aceeași înregistrare sau dacă ordinea contează pentru consistența datelor, forțați execuția secvențială.

from agents import Agent

agent = Agent(
    name="Agent Prudent",
    instructions="Executați instrumentele unul câte unul pentru a asigura consistența datelor.",
    tools=[search_company, verify_solvency],
    model="gpt-5.6-terra",
    parallel_tool_calls=False,  # Forțează execuția secvențială
)

Parametrul parallel_tool_calls=False forțează modelul să apeleze un singur instrument la un moment dat. Sacrificați latența în favoarea predictibilității.

Model: Agregarea rezultatelor paralele

Cel mai frecvent caz practic implică colectarea datelor din mai multe surse pentru aceeași entitate. Aici, vremea și agenda culturală ale unui oraș nu au nicio legătură între ele, dar răspunsul are nevoie de ambele.

import json
from agents import Agent, Runner, function_tool

@function_tool
async def get_weather(city: str) -> str:
    """Obține vremea curentă pentru un oraș."""
    # Simulare - în producție: apel către API meteo
    weather_data = {
        "Paris": {"temp": 22, "conditions": "sunny"},
        "Lyon": {"temp": 19, "conditions": "cloudy"},
        "Marseille": {"temp": 26, "conditions": "sunny"},
    }
    data = weather_data.get(city, {"temp": 0, "conditions": "unknown"})
    return json.dumps({"city": city, **data}, ensure_ascii=False)

@function_tool
async def get_events(city: str) -> str:
    """Obține evenimentele viitoare dintr-un oraș."""
    events = {
        "Paris": ["Concert la Stade de France", "Expoziție la Luvru"],
        "Lyon": ["Festivalul Luminilor", "Târgul Gastronomic"],
        "Marseille": ["Regata Mediteraneană"],
    }
    return json.dumps({
        "city": city,
        "events": events.get(city, [])
    }, ensure_ascii=False)

agent = Agent(
    name="Agent de Turism",
    instructions="""Sunteți un agent de turism. Când vi se cer
    recomandări pentru un oraș, preluați vremea ȘI evenimentele
    simultan pentru a oferi sfaturi complete.""",
    tools=[get_weather, get_events],
    model="gpt-5.6-terra",
)

# Modelul va apela ambele instrumente în paralel pentru fiecare oraș
result = await Runner.run(
    agent,
    "Vreau să vizitez Parisul în acest weekend. Ce recomandați?"
)
print(result.final_output)

Ambele instrumente returnează JSON, ceea ce facilitează recombinarea datelor de către model. Observați formularea instrucțiunii: expresia „ȘI … simultan“ declanșează apelul paralel, nu un lanț leneș.

Timeout-uri și reziliență

Un API care nu răspunde niciodată vă blochează agentul la fel de sigur ca un instrument sincron. Limitați fiecare apel lent cu un timeout și transformați erorile în mesaje inteligibile.

import asyncio
from agents import function_tool

@function_tool
async def slow_api_call(query: str) -> str:
    """Apelează un API care ar putea fi lent."""
    try:
        async with asyncio.timeout(5):  # timeout de 5 secunde
            # Apelul dumneavoastră către API aici
            await asyncio.sleep(0.1)  # Simulare
            return f"Rezultat pentru '{query}'"
    except asyncio.TimeoutError:
        return "API-ul nu a răspuns la timp. Vă rugăm să încercați din nou."

Performanță: Impactul paralelismului

Să punem lucrurile în perspectivă. Trei instrumente de 500 ms executate secvențial costă 1500 ms; aceleași trei instrumente în paralel costă aproximativ 500 ms – durata celui mai lent dintre ele. Pentru un agent care utilizează multe instrumente, diferența este imediat observabilă în practică.

Puncte cheie

  • Utilizați async pentru instrumentele care efectuează apeluri de rețea sau I/O
  • SDK-ul execută automat instrumentele independente în paralel
  • parallel_tool_calls=False forțează execuția secvențială atunci când este necesar
  • Adăugați timeout-uri cu asyncio.timeout() pentru reziliență
  • Paralelismul poate reduce latența proporțional cu numărul de instrumente