Narzędzia asynchroniczne i równoległe
Na tej stronie
Narzędzia asynchroniczne i równoległe
W środowisku produkcyjnym Twoje narzędzia wywołują zewnętrzne API, odpytują bazy danych lub wykonują operacje wejścia/wyjścia (I/O). Operacje te zajmują czas, który się sumuje: agent łączący pięć wywołań trwających po jednej sekundzie potrzebuje pięciu sekund na odpowiedź. To, co odróżnia demo od użytecznego serwisu, to uczynienie narzędzi asynchronicznymi i wykorzystanie natywnego równoleglenia oferowanego przez SDK.
Narzędzia asynchroniczne
Dekorator @function_tool natywnie obsługuje funkcje async. Nie wymaga żadnej konfiguracji: zadeklaruj async def, użyj asynchronicznego klienta HTTP, a SDK zajmie się resztą.
import httpx
from agents import function_tool
@function_tool
async def search_company(name: str) -> str:
"""Wyszukuje informacje o firmie poprzez 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"Company: {data['name']}, SIREN: {data['siren']}, Revenue: {data['revenue']}"
return f"No results for '{name}'"
@function_tool
async def verify_solvency(siren: str) -> str:
"""Weryfikuje wypłacalność firmy na podstawie numeru 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"Solvency score: {data['score']}/100, risk: {data['risk_level']}"
Gdy Runner wykonuje narzędzie asynchroniczne, nie blokuje pętli zdarzeń. W serwerze FastAPI oznacza to, że inne żądania są nadal przetwarzane, podczas gdy Twój agent czeka na odpowiedź z API Societe.com.
Automatyczne równoleglenie
Dwa niezależne narzędzia asynchroniczne mogą działać jednocześnie. Decyduje o tym model, a Twoje instrukcje mogą to działanie wyraźnie wspierać.
from agents import Agent, Runner
agent = Agent(
name="B2B Analyst",
instructions="""Analizujesz firmy pod kątem decyzji biznesowych.
Gdy zostaniesz poproszony o analizę firmy, pobierz jej informacje
ORAZ zweryfikuj jej wypłacalność w tym samym czasie.""",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
)
# Model uruchomi oba narzędzia równolegle
result = await Runner.run(
agent,
"Analyze the company Acme Corp (SIREN 123456789)"
)
Ponieważ numer SIREN jest podany w zapytaniu, sprawdzenie wypłacalności nie czeka na wyszukiwanie firmy: SDK wykonuje oba wywołania jednocześnie. Całkowity czas równa się czasowi trwania najwolniejszego narzędzia, a nie sumie czasów obu.
Kontrolowanie równoleglenia
Równoleglenie nie zawsze jest pożądane. Jeśli Twoje narzędzia zapisują dane w tym samym rekordzie lub jeśli kolejność ma znaczenie dla spójności danych, wymuś wykonanie sekwencyjne.
from agents import Agent
agent = Agent(
name="Cautious Agent",
instructions="Wykonuj narzędzia jedno po drugim, aby zapewnić spójność danych.",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
parallel_tool_calls=False, # Wymusza wykonanie sekwencyjne
)
Parametr parallel_tool_calls=False wymusza na modelu wywoływanie tylko jednego narzędzia w danym momencie. Zamieniasz tu opóźnienie na przewidywalność.
Wzorzec: Agregacja wyników równoległych
Najczęstszym przypadkiem praktycznym jest gromadzenie danych z wielu źródeł dotyczących tego samego podmiotu. Tutaj pogoda w mieście i jego agenda kulturalna nie mają ze sobą nic wspólnego, ale odpowiedź musi zawierać obie informacje.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def get_weather(city: str) -> str:
"""Pobiera aktualną pogodę dla miasta."""
# Symulacja - w produkcji: wywołanie API pogodowego
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:
"""Pobiera nadchodzące wydarzenia w mieście."""
events = {
"Paris": ["Concert at Stade de France", "Exhibition at the Louvre"],
"Lyon": ["Festival of Lights", "Gastronomy Fair"],
"Marseille": ["Mediterranean Regatta"],
}
return json.dumps({
"city": city,
"events": events.get(city, [])
}, ensure_ascii=False)
agent = Agent(
name="Travel Agent",
instructions="""Jesteś agentem podróżnym. Gdy zostaniesz poproszony
o rekomendacje dla miasta, pobierz pogodę ORAZ wydarzenia
jednocześnie, aby udzielić kompletnych porad.""",
tools=[get_weather, get_events],
model="gpt-5.6-terra",
)
# Model wywoła oba narzędzia równolegle dla każdego miasta
result = await Runner.run(
agent,
"I want to visit Paris this weekend. What do you recommend?"
)
print(result.final_output)
Oba narzędzia zwracają JSON, co ułatwia modelowi ponowne połączenie danych. Zwróć uwagę na sformułowanie instrukcji: fraza „ORAZ … jednocześnie“ wyzwala wywołanie równoległe, zamiast leniwego łańcucha.
Limit czasu i odporność na błędy
API, które nigdy nie odpowiada, blokuje Twojego agenta tak samo skutecznie jak narzędzie synchroniczne. Każde wolne wywołanie ogranicz limitem czasu (timeout) i zamieniaj awarie na zrozumiałe komunikaty.
import asyncio
from agents import function_tool
@function_tool
async def slow_api_call(query: str) -> str:
"""Wywołuje API, które może być wolne."""
try:
async with asyncio.timeout(5): # Limit 5 sekund
# Twoje wywołanie API tutaj
await asyncio.sleep(0.1) # Symulacja
return f"Result for '{query}'"
except asyncio.TimeoutError:
return "The API did not respond in time. Please try again."
Wydajność: Wpływ równoleglenia
Spójrzmy na skalę zjawiska. Trzy narzędzia działające po 500 ms wykonane sekwencyjnie kosztują 1500 ms; te same trzy narzędzia uruchomione równolegle kosztują około 500 ms – czyli czas trwania najwolniejszego z nich. Dla agenta korzystającego z wielu narzędzi różnica ta jest natychmiast zauważalna w praktyce.
Kluczowe wnioski
- Używaj
asyncdla narzędzi wykonujących połączenia sieciowe lub operacje I/O - SDK automatycznie wykonuje niezależne narzędzia równolegle
parallel_tool_calls=Falsewymusza wykonanie sekwencyjne, gdy jest to konieczne- Dodawaj limity czasu za pomocą
asyncio.timeout()dla zwiększenia odporności na błędy - Równoleglenie może zmniejszyć opóźnienie proporcjonalnie do liczby narzędzi