Alati asinkroni i paralelni
Na ovoj stranici
Alati asinkroni i paralelni
U produkcijskom okruženju tvoji alati pozivaju vanjske API-je, upituju baze podataka ili izvode operacije ulaza/izlaza (I/O). Te operacije traže vrijeme, a to se vrijeme zbraja: agent koji lančano izvrši pet poziva od po jednu sekundu odgovara tek nakon pet sekundi. Upravo asinkronost alata i iskorištavanje nativne paralelizacije SDK-a razlikuju demonstracijski projekt od upotrebljivog servisa.
Asinkroni alati
Dekorator @function_tool nativno podržava async funkcije. Nije potrebna nikakva konfiguracija: deklariraj async def, koristi asinkroni HTTP klijent, a SDK će se pobrinuti za ostalo.
import httpx
from agents import function_tool
@function_tool
async def search_company(name: str) -> str:
"""Pretražuje informacije o tvrtki putem Societe.com API-ja."""
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"Tvrtka: {data['name']}, SIREN: {data['siren']}, Prihod: {data['revenue']}"
return f"Nema rezultata za '{name}'"
@function_tool
async def verify_solvency(siren: str) -> str:
"""Provjerava solventnost tvrtke na temelju njezinog SIREN broja."""
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"Ocjena solventnosti: {data['score']}/100, rizik: {data['risk_level']}"
Kada Runner izvrši asinkroni alat, ne blokira petlju događaja (event loop). U FastAPI poslužitelju to znači da se ostali zahtjevi nastavljaju obrađivati dok tvoj agent čeka odgovor Societe.com API-ja.
Automatska paralelizacija
Dva neovisna asinkrona alata mogu se izvršavati istovremeno. Model to odlučuje, a tvoje upute mogu to izričito potaknuti.
from agents import Agent, Runner
agent = Agent(
name="B2B Analitičar",
instructions="""Analiziraš tvrtke radi poslovnih odluka.
Kada te se zamoli da analiziraš tvrtku, dohvati njezine informacije
I istovremeno provjeri njezinu solventnost.""",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
)
# Model će pokrenuti oba alata paralelno
result = await Runner.run(
agent,
"Analiziraj tvrtku Acme Corp (SIREN 123456789)"
)
Budući da je SIREN broj naveden u upitu, provjera solventnosti ne čeka pretraživanje tvrtke: SDK izvršava oba poziva istovremeno. Ukupno vrijeme jednako je trajanju najsporijeg alata, a ne zbroju obaju.
Upravljanje paralelizacijom
Paralelizacija nije uvijek poželjna. Ako tvoji alati pišu u isti zapis ili ako je redoslijed bitan za dosljednost podataka, prisili sekvencijalno izvršavanje.
from agents import Agent
agent = Agent(
name="Oprezni agent",
instructions="Izvršavaj alate jedan po jedan kako bi se osigurala dosljednost podataka.",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
parallel_tool_calls=False, # Prisiljava sekvencijalno izvršavanje
)
Parametar parallel_tool_calls=False prisiljava model da poziva samo jedan alat u jednom trenutku. Žrtvuješ kašnjenje zarad predvidljivosti.
Uzorak: Agregiranje paralelnih rezultata
Najčešći praktični slučaj uključuje prikupljanje podataka iz više izvora za isti entitet. Ovdje vremenska prognoza i kulturni program grada nemaju nikakve veze jedno s drugim, ali odgovor zahtijeva oboje.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def get_weather(city: str) -> str:
"""Dohvaća trenutnu vremensku prognozu za grad."""
# Simulacija - u produkciji: poziv weather API-ju
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:
"""Dohvaća nadolazeće događaje u gradu."""
events = {
"Paris": ["Koncert na Stade de Franceu", "Izložba u Louvreu"],
"Lyon": ["Festival svjetlosti", "Sajam gastronomije"],
"Marseille": ["Mediteranska regata"],
}
return json.dumps({
"city": city,
"events": events.get(city, [])
}, ensure_ascii=False)
agent = Agent(
name="Putnički agent",
instructions="""Ti si putnički agent. Kada te se zamoli
za preporuke za neki grad, istovremeno dohvati vremensku prognozu I događaje
kako bi pružio/la kompletan savjet.""",
tools=[get_weather, get_events],
model="gpt-5.6-terra",
)
# Model će za svaki grad pozvati oba alata paralelno
result = await Runner.run(
agent,
"Želim posjetiti Pariz ovaj vikend. Što preporučuješ?"
)
print(result.final_output)
Oba alata vraćaju JSON, što modelu olakšava ponovno kombiniranje podataka. Obrati pažnju na formulaciju upute: fraza „I … istovremeno“ pokreće paralelni poziv umjesto lijenog lančanja.
Isteci vremena i otpornost
API koji nikada ne odgovara blokira tvog agenta jednako sigurno kao i sinkroni alat. Svaki spor poziv ograniči istekom vremena (timeout) i pretvori neuspjehe u razumljive poruke.
import asyncio
from agents import function_tool
@function_tool
async def slow_api_call(query: str) -> str:
"""Poziva API koji može biti spor."""
try:
async with asyncio.timeout(5): # Istek od 5 sekundi
# Tvoj poziv API-ju ovdje
await asyncio.sleep(0.1) # Simulacija
return f"Rezultat za '{query}'"
except asyncio.TimeoutError:
return "API nije odgovorio na vrijeme. Pokušaj ponovno."
Performanse: Utjecaj paralelizacije
Stavimo ovo u perspektivu. Tri alata od po 500 ms izvršena sekvencijalno koštaju 1500 ms; ta ista tri alata paralelno koštaju oko 500 ms – trajanje najsporijeg od njih. Za agenta koji koristi mnogo alata, razlika je u praksi odmah vidljiva.
Ključne točke
- Koristi
asyncza alate koji obavljaju mrežne ili I/O pozive - SDK automatski izvršava neovisne alate paralelno
parallel_tool_calls=Falseprisiljava sekvencijalno izvršavanje kada je potrebno- Dodaj isteke vremena s
asyncio.timeout()radi otpornosti - Paralelizacija može smanjiti kašnjenje za faktor jednak broju alata