Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Asynkroniset ja rinnakkaiset työkalut

Oppitunti 8 / 25 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Asynkroniset ja rinnakkaiset työkalut
  2. Asynkroniset työkalut
  3. Automaattinen rinnakkaisuus
  4. Rinnakkaisuuden hallinta
  5. Malli: Rinnakkaisten tulosten kokoaminen
  6. Aikakatkokset ja vikasietoisuus
  7. Suorituskyky: Rinnakkaisuuden vaikutus
  8. Keskeiset asiat

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=False pakottaa peräkkäisen suorituksen tarvittaessa
  • Lisää aikakatkokset asyncio.timeout()-funktiolla vikasietoisuuden parantamiseksi
  • Rinnakkaisuus voi jakaa viiveen työkalujen lukumäärällä