Instrumente asincrone și paralele
Pe această pagină
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
asyncpentru instrumentele care efectuează apeluri de rețea sau I/O - SDK-ul execută automat instrumentele independente în paralel
parallel_tool_calls=Falseforț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