Asynchrónne a paralelné nástroje
Na tejto strane
Asynchrónne a paralelné nástroje
V produkčnom prostredí tvoje nástroje volajú externé API, dopytujú databázy alebo vykonávajú operácie vstupu/výstupu (I/O). Tieto operácie trvajú určitý čas a tento čas sa sčítava: agent, ktorý zreťazí päť jednosekundových volaní, odpovedá až po piatich sekundách. Práve použitie asynchrónnych nástrojov a využitie natívneho paralelizmu SDK oddeľuje jednoduché demo od použiteľnej služby.
Asynchrónne nástroje
Dekorátor @function_tool natívne podporuje funkcie async. Nie je potrebná žiadna konfigurácia: stačí deklarovat async def, použiť asynchrónneho HTTP klienta a SDK sa postará o zvyšok.
import httpx
from agents import function_tool
@function_tool
async def search_company(name: str) -> str:
"""Vyhľadáva informácie o spoločnosti cez API 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"Spoločnosť: {data['name']}, SIREN: {data['siren']}, Tržby: {data['revenue']}"
return f"Žiadne výsledky pre '{name}'"
@function_tool
async def verify_solvency(siren: str) -> str:
"""Overuje bonitu spoločnosti podľa jej čísla 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"Skóre bonity: {data['score']}/100, riziko: {data['risk_level']}"
Keď Runner vykoná asynchrónny nástroj, neblokuje slučku udalostí (event loop). V serveri FastAPI to znamená, že ostatné požiadavky sa spracúvajú ďalej, zatiaľ čo tvoj agent čaká na odpoveď z API Societe.com.
Automatický paralelizmus
Dva nezávislé asynchrónne nástroje sa môžu spustiť súčasne. Rozhoduje o tom model a tvoje inštrukcie ho môžu k tomuto správaniu explicitne povzbudiť.
from agents import Agent, Runner
agent = Agent(
name="B2B Analytik",
instructions="""Analyzuješ spoločnosti pre obchodné rozhodnutia.
Keď ťa požiadajú o analýzu spoločnosti, získaj jej informácie
A ZÁROVEŇ over jej bonitu.""",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
)
# Model spustí oba nástroje paralelne
result = await Runner.run(
agent,
"Analyzuj spoločnosť Acme Corp (SIREN 123456789)"
)
Keďže číslo SIREN je uvedené priamo v dotaze, kontrola bonity nečaká na vyhľadanie spoločnosti: SDK vykoná obe volania súčasne. Celkový čas sa rovná trvaniu najpomalšieho nástroja, nie súčtu oboch.
Riadenie paralelizmu
Paralelizmus nie je vždy žiaduci. Ak tvoje nástroje zapisujú do toho istého záznamu alebo ak je pre konzistenciu dát dôležité poradie, vynúť si sekvenčné vykonávanie.
from agents import Agent
agent = Agent(
name="Opatrný agent",
instructions="Vykonávaj nástroje jeden po druhom, aby sa zabezpečila konzistencia dát.",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
parallel_tool_calls=False, # Vynúti sekvenčné vykonávanie
)
Parameter parallel_tool_calls=False prinúti model volať vždy len jeden nástroj naraz. Vymieňaš latenciu za predvídateľnosť.
Vzorec: Agregácia paralelných výsledkov
Najbežnejším praktickým prípadom je zhromažďovanie údajov z viacerých zdrojov pre tú istú entitu. Počasie v meste a jeho kultúrny program spolu síce nesúvisia, ale odpoveď potrebuje obe tieto informácie.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def get_weather(city: str) -> str:
"""Získava aktuálne počasie pre mesto."""
# Simulácia - v produkcii: volanie weather API
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:
"""Získava nadchádzajúce podujatia v meste."""
events = {
"Paris": ["Koncert na Stade de France", "Výstava v Louvri"],
"Lyon": ["Svetlo festival", "Gastronomický veľtrh"],
"Marseille": ["Stredomorská regata"],
}
return json.dumps({
"city": city,
"events": events.get(city, [])
}, ensure_ascii=False)
agent = Agent(
name="Cestovný agent",
instructions="""Si cestovný agent. Keď ťa požiadajú
o odporúčania pre mesto, získaj počasie A podujatia
súčasne, aby si poskytol kompletné rady.""",
tools=[get_weather, get_events],
model="gpt-5.6-terra",
)
# Model zavolá oba nástroje paralelne pre každé mesto
result = await Runner.run(
agent,
"Chcem tento víkend navštíviť Paríž. Čo odporúčaš?"
)
print(result.final_output)
Oba nástroje vracajú JSON, čo modelu uľahčuje opätovné skombinovanie údajov. Všimni si formuláciu inštrukcie: fráza „A … súčasne“ spustí paralelné volanie namiesto lenivého reťazenia.
Časové limity a odolnosť
API, ktoré nikdy neodpovie, zablokuje tvojho agenta rovnako isto ako synchronný nástroj. Každé pomalé volanie ohranič časovým limitom a zlyhania premeň na zrozumiteľné správy.
import asyncio
from agents import function_tool
@function_tool
async def slow_api_call(query: str) -> str:
"""Volá API, ktoré môže byť pomalé."""
try:
async with asyncio.timeout(5): # 5-sekundový časový limit
# Tvoje volanie API tu
await asyncio.sleep(0.1) # Simulácia
return f"Výsledok pre '{query}'"
except asyncio.TimeoutError:
return "API neodpovedalo včas. Skús to prosím znova."
Výkon: Vplyv paralelizmu
Uveďme si to do perspektívy. Tri nástroje s dobou behu 500 ms vykonané sekvenčne stoja 1500 ms; tie isté tri nástroje vykonané paralelne stoja približne 500 ms – čo je doba trvania toho najpomalšieho. Pri agentovi využívajúcom mnoho nástrojov je tento rozdiel v praxi okamžite badateľný.
Kľúčové poznatky
- Používaj
asyncpre nástroje, ktoré vykonávajú sieťové alebo I/O operácie - SDK automaticky vykonáva nezávislé nástroje paralelne
parallel_tool_calls=Falsevynúti sekvenčné vykonávanie, keď je to potrebné- Pre odolnosť pridávaj časové limity pomocou
asyncio.timeout() - Paralelizmus môže znížiť latenciu úmerne počtu nástrojov