Asynkroniset ja rinnakkaiset työkalut
Tällä sivulla
Asynkroniset ja rinnakkaiset työkalut
Tuotantoympäristössä työkalusi kutsuvat ulkoisia rajapintoja, hakevat tietoja tietokannoista tai suorittavat I/O-operaatioita. Nämä toiminnot vievät aikaa, ja aika kertyy nopeasti: viisi peräkkäistä yhden sekunnin kestävää kutsua saa agentin vastaamaan viiden sekunnin viiveellä. Työkalujen tekeminen asynkronisiksi ja SDK:n natiivin rinnakkaisuuden hyödyntäminen on se, mikä erottaa demon toimivasta palvelusta.
Asynkroniset työkalut
@function_tool-dekoraattori tukee natiivisti async-funktioita. Erillistä konfiguraatiota ei tarvita: määritä funktio avainsanalla async def, käytä asynkronista HTTP-asiakasta, ja SDK hoitaa loput.
import httpx
from agents import function_tool
@function_tool
async def search_company(name: str) -> str:
"""Hakee yritystietoja Societe.com-rajapinnan kautta."""
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"Yritys: {data['name']}, SIREN: {data['siren']}, Liikevaihto: {data['revenue']}"
return f"Ei tuloksia haulle '{name}'"
@function_tool
async def verify_solvency(siren: str) -> str:
"""Tarkistaa yrityksen maksukyvyn SIREN-numeron perusteella."""
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"Maksukykyarvio: {data['score']}/100, riski: {data['risk_level']}"
Kun Runner suorittaa asynkronisen työkalun, se ei estä tapahtumasilmukkaa. FastAPI-palvelimella tämä tarkoittaa, että muut pyynnöt jatkavat käsittelyä agentin odottaessa vastausta Societe.com-rajapinnalta.
Automaattinen rinnakkaisuus
Kaksi toisistaan riippumatonta asynkronista työkalua voi suorittaa samanaikaisesti. Malli päättää tämän, ja ohjeistuksellasi voit kannustaa sitä tähän nimenomaisesti.
from agents import Agent, Runner
agent = Agent(
name="B2B-analyytikko",
instructions="""Analysoit yrityksiä liiketoimintapäätöksiä varten.
Kun sinua pyydetään analysoimaan yritystä, hae sen tiedot
JA tarkista sen maksukyky samanaikaisesti.""",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
)
# Malli käynnistää molemmat työkalut rinnakkain
result = await Runner.run(
agent,
"Analysoi yritys Acme Corp (SIREN 123456789)"
)
Koska SIREN-numero annetaan kyselyssä, maksukyvyn tarkistus ei odota yrityshaun valmistumista: SDK suorittaa molemmat kutsut samanaikaisesti. Kokonaisaika vastaa hitaimman työkalun kestoa, ei molempien summaa.
Rinnakkaisuuden hallinta
Rinnakkaisuus ei ole aina toivottavaa. Jos työkalusi kirjoittavat samaan tietueeseen tai jos tietojen eheyden kannalta järjestys on tärkeä, pakota suoritus peräkkäiseksi.
from agents import Agent
agent = Agent(
name="Varovainen agentti",
instructions="Suorita työkalut yksi kerrallaan tietojen eheyden varmistamiseksi.",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
parallel_tool_calls=False, # Pakottaa peräkkäisen suorituksen
)
Parametri parallel_tool_calls=False pakottaa mallin kutsumaan vain yhtä työkalua kerrallaan. Vaihdat viiveen ennustettavuuteen.
Malli: Rinnakkaisten tulosten kokoaminen
Yleisin käytännön tilanne liittyy tietojen keräämiseen useista lähteistä samaa kohdetta varten. Tässä esimerkissä kaupungin sää ja kulttuuritarjonta eivät liity toisiinsa, mutta vastaus tarvitsee molemmat.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def get_weather(city: str) -> str:
"""Hakee kaupungin nykyisen sään."""
# Simulaatio – tuotannossa: säärajapintakutsu
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:
"""Hakee kaupungin tulevat tapahtumat."""
events = {
"Paris": ["Konsertti Stade de Francessa", "Näyttely Louvressa"],
"Lyon": ["Valofestivaali", "Gastronomiamessut"],
"Marseille": ["Välimeren regatta"],
}
return json.dumps({
"city": city,
"events": events.get(city, [])
}, ensure_ascii=False)
agent = Agent(
name="Matka-agentti",
instructions="""Olet matka-agentti. Kun sinua pyydetään
antamaan suosituksia kaupunkiin, hae sää JA tapahtumat
samanaikaisesti tarjotaksesi täydellisiä neuvoja.""",
tools=[get_weather, get_events],
model="gpt-5.6-terra",
)
# Malli kutsuu molemmat työkalut rinnakkain jokaista kaupunkia kohden
result = await Runner.run(
agent,
"Haluan vierailla Pariisissa tänä viikonloppuna. Mitä suosittelet?"
)
print(result.final_output)
Molemmat työkalut palauttavat JSON-muotoista dataa, mikä helpottaa mallia yhdistämään tiedot. Huomaa ohjeistuksen muotoilu: ilmaisu “JA … samanaikaisesti” laukaisee rinnakkaiskutsun laiskan ketjutuksen sijaan.
Aikakatkokset ja vikasietoisuus
Rajapinta, joka ei koskaan vastaa, estää agenttisi yhtä varmasti kuin synkroninen työkalu. Rajoita jokainen hidas kutsu aikakatkokseen ja muuta virheet ymmärrettäviksi viesteiksi.
import asyncio
from agents import function_tool
@function_tool
async def slow_api_call(query: str) -> str:
"""Kutsuu rajapintaa, joka voi olla hidas."""
try:
async with asyncio.timeout(5): # 5 sekunnin aikakatkaisu
# Rajapintakutsusi tähän
await asyncio.sleep(0.1) # Simulaatio
return f"Tulos haulle '{query}'"
except asyncio.TimeoutError:
return "Rajapinta ei vastannut ajoissa. Yritä uudelleen."
Suorituskyky: Rinnakkaisuuden vaikutus
Asetetaan asia mittakaavaan. Kolme 500 ms kestävää työkalua suoritettuna peräkkäin maksaa 1500 ms; samat kolme työkalua rinnakkain maksavat noin 500 ms – eli hitaimman keston. Agentille, joka käyttää monia työkaluja, ero on käytännössä välittömästi havaittavissa.
Keskeiset asiat
- Käytä
async-avainsanaa työkaluille, jotka tekevät verkko- tai I/O-kutsuja - SDK suorittaa riippumattomat työkalut automaattisesti rinnakkain
parallel_tool_calls=Falsepakottaa peräkkäisen suorituksen tarvittaessa- Lisää aikakatkokset
asyncio.timeout()-funktiolla vikasietoisuuden parantamiseksi - Rinnakkaisuus voi jakaa viiveen työkalujen lukumäärällä