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

Valvonta ja lokitus

Oppitunti 13 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Agenttisi tarkkailu tuotannossa
  2. Lokituksen kolme tasoa
  3. Seurattavat mittarit
  4. Valvontakojelauta
  5. Automaattiset hälytykset
  6. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n Computer use -oppaan ja Responses API -dokumentaation perusteella: lokitus lukee nyt toiminnot computer_call-objektista ja elementit response.output-rakenteesta (viestit phase-tietoineen, päättelyyhteenvetoineen ja kutsuineen) Anthropicin API:n tool_use-lohkojen sijaan; kovakoodattu Claude Sonnet -hinnoittelu on korvattu käytössä olevan mallin hinnoittelulla, ja vanhentunut datetime.utcnow() (Python 3.12:sta lähtien) on korvattu funktiolla datetime.now(timezone.utc). Lähteet: Computer use · Pricing.

Agenttisi tarkkailu tuotannossa

Tuotannossa oleva Computer Use -agentti on musta laatikko, ellei valvontaa ole asetettu kunnolla. Toisin kuin tavallisessa rajapinnassa, jossa lokitetaan vain pyynnöt ja vastaukset, täällä on jäljitettävä myös visuaalisia toimintoja, kuvakaappauksia ja mallin tekemiä päätöksiä. Ero on konkreettinen: kun työnkulku epäonnistuu kello 3 yöllä, oleellinen kysymys ei ole “mikä poikkeus heitettiin”, vaan “mitä agentti näki, ja miksi se napsautti tuohon?”. Loki, joka ei vastaa tähän kysymykseen, ei auta sinua seuraavana aamuna.

Lokituksen kolme tasoa

Instrumentointi rakentuu siis kolmelle toisiaan täydentävälle kerrokselle: mitä agentti teki, mitä se ajatteli ennen tekoa ja mitä se näki päätöstä tehdessään. Kukin kirjoittaa eri kanavalle, sillä neither volyymi eikä hyödyllinen elinkaari ole sama.

Taso 1: Toiminnot

Jokainen agentin suorittama toiminto on jäljitettävä. Alla oleva formaatti lisää järjestelmällisesti etuliitteeksi iterointinumeron ja nykyisen vaiheen nimen, jolloin voit suodattaa useiden tuhansien rivien lokista esiin sen ainoan sekvenssin, joka meni pieleen. Toiminnot saapuvat objekteina computer_call-rakenteesta, ja niissä on samat kentät kuin käsittelijässäsi (x, y, scroll_x, keys…). Huomaa type-toiminnon käsittely: kirjaamme ylös syötetyn tekstin pituuden, emme koskaan sen sisältöä. Agentti, joka täyttää kirjautumislomaketta, kirjoittaa salasanan, ja edellisen oppitunnin sääntöä sovelletaan tähän poikkeuksetta.

import logging

logger = logging.getLogger("computer_use")
logger.setLevel(logging.INFO)

handler = logging.FileHandler("agent.log")
handler.setFormatter(logging.Formatter("%(asctime)s | %(levelname)s | %(message)s"))
handler.addFilter(SensitiveFilter())  # suodatin oppitunnista 12
logger.addHandler(handler)


def log_action(action, iteration: int, step: str = ""):
    """Lokittaa toiminnon computer_call-objektista."""
    prefix = f"[iter={iteration}] [{step}]"
    match action.type:
        case "click" | "double_click" | "move":
            logger.info("%s %s at (%s, %s)", prefix, action.type.upper(), action.x, action.y)
        case "type":
            # Ei koskaan itse tekstiä: vain sen pituus
            logger.info("%s TYPE (%d chars)", prefix, len(action.text))
        case "scroll":
            logger.info("%s SCROLL dx=%s dy=%s", prefix, action.scroll_x, action.scroll_y)
        case "keypress":
            logger.info("%s KEYPRESS %s", prefix, "+".join(action.keys))
        case "drag":
            logger.info("%s DRAG (%d points)", prefix, len(action.path))
        case _:
            logger.info("%s %s", prefix, action.type.upper())

Taso 2: Mallin päätökset

Lokita, mitä malli sanoo valinnoistaan, ymmärtääksesi miksi se valitsi tietyn toiminnon. Napsautus odottamattomissa koordinaateissa ei itsessään merkitse mitään; yhdistettynä sitä edeltäneeseen lauseeseen – “lähetyspainike näyttää evästekätkön peittämänä” – siitä tulee diagnoosi. Teksti typistetään kahteensataan merkkiin, mikä riittää hyvin intention ymmärtämiseen ilman tiedostokoon räjähtämistä. Responses API -vastauksessa on kaksi tekstilähdettä. Väliviestit, jotka malli kirjoittaa ennen toimintaa, sisältävät phase: "commentary", kun taas lopullinen vastaus sisältää phase: "final_answer". Ja jos käytössä oleva malli tukee päättelyyhteenvetoja, saat ne pyytämällä niitä (reasoning={"summary": "auto"}): ne saapuvat reasoning-tyyppisinä elementteinä.

Tokenien kulutus lokitetaan samaan tahtiin, ja se ansaitsee tarkkaa huomiota: vaikka käytettäisiin previous_response_id:tä, ketjun aiempien vastausten kaikki syöttötokenit laskutetaan uudelleen syötteinä, kuvakaappaukset mukaan lukien. Kierroksen kustannus kasvaa siis istunnon pituuden myötä.

def log_model_response(response, iteration: int):
    """Lokittaa huomautukset, yhteenvedot ja kutsut vastauksesta (kuvia lukuun ottamatta)."""
    for item in response.output:
        if item.type == "reasoning":
            for summary in item.summary:
                logger.info("[iter=%d] REASONING: %s", iteration, summary.text[:200])
        elif item.type == "message":
            text = "".join(c.text for c in item.content if c.type == "output_text")
            logger.info("[iter=%d] MESSAGE (%s): %s", iteration, item.phase or "-", text[:200])
        elif item.type == "computer_call":
            actions = ", ".join(a.type for a in item.actions or [])
            logger.info("[iter=%d] COMPUTER_CALL %s: %s", iteration, item.call_id, actions)
        elif item.type == "function_call":
            logger.info("[iter=%d] FUNCTION_CALL %s", iteration, item.name)

    # Kulutetut tokenit
    logger.info(
        "[iter=%d] TOKENS: in=%d out=%d",
        iteration, response.usage.input_tokens, response.usage.output_tokens,
    )

Taso 3: Kuvakaappaukset

Tallenna kuvakaappaukset jälkikäteistä vianetsintää varten, mutta pidä silmällä levytilaa: PNG-kaappaus painaa usein useita satoja kilotavuja, ja pitkä työnkulku tuottaa satoja niitä. Alla oleva luokka ratkaisee tämän yksinkertaisella rotaatiolla. Tiedostonimi alkaa aikaleimalla, jolloin aakkosjärjestys vastaa kronologista järjestystä; lajittelu metodissa _cleanup riittää tunnistamaan vanhimmat kaappaukset ja poistamaan ne, kunnes määrä putoaa sadan tiedoston katon alle. Kenttä label antaa mahdollisuuden merkitä kiinnostavia hetkiä, esimerkiksi error tai before_validation, jotta ne erottaa kansiossa silmäyksellä.

from datetime import datetime, timezone
from pathlib import Path

class ScreenshotLogger:
    """Tallentaa kuvakaappaukset rotaatiolla."""

    def __init__(self, base_dir: str = "logs/screenshots", max_files: int = 100):
        self.base_dir = Path(base_dir)
        self.base_dir.mkdir(parents=True, exist_ok=True)
        self.max_files = max_files
        self.counter = 0

    def save(self, screenshot_bytes: bytes, iteration: int, label: str = ""):
        """Tallentaa kuvakaappauksen kuvaavalla nimellä."""
        ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
        filename = f"{ts}_iter{iteration:03d}_{label}.png"
        filepath = self.base_dir / filename

        with open(filepath, "wb") as f:
            f.write(screenshot_bytes)

        self.counter += 1
        self._cleanup()

        return filepath

    def _cleanup(self):
        """Poistaa vanhat kuvakaappaukset."""
        files = sorted(self.base_dir.glob("*.png"))
        while len(files) > self.max_files:
            files[0].unlink()
            files.pop(0)

Seurattavat mittarit

Onnistumis-
aste työnkulkua kohden
Keskimääräinen
kesto vaihetta kohden
Kustannus
tokeneina suoritusta kohden
Virheet
tyypin ja tiheyden mukaan

Nämä neljä indikaattoria ovat arvokkaita vain verrattuna niiden omaan historiaan: työnkulun onnistumisasteen lasku yhdeksästäkymmenestäviidestä kahdeksaankaymmeneen prosenttiin kertoo käyttöliittymän siirtyneen, kauan ennen kuin ensimmäinen käyttäjä valittaa. Toteuta siis mittareiden kerääjä, joka liitetään jokaiseen suoritukseen. WorkflowMetrics-dataclass kerryttää tokeneita kierros kierrokselta, pitää kirjaa virheistä niiden vaiheineen ja aikaleimoineen, ja tarjoaa kaksi laskettua ominaisuutta: keston, joka toimii vaikka työnkulku ei olisi vielä valmis, ja kustannusarvion, joka perustuu käytössä olevan mallin hinnoitteluun. Hae hinnat OpenAI:n hinnoittelusivulta äläkä kovakoodaa niitä. Metodi summary tuottaa tiiviin sanakirjan, jonka arkistoit jokaisen suorituksen yhteydessä.

from dataclasses import dataclass, field
from datetime import datetime, timezone

def now() -> datetime:
    return datetime.now(timezone.utc)

@dataclass
class WorkflowMetrics:
    """Kerää mittareita työnkululle."""
    workflow_id: str
    input_price_per_million: float  # käytössä olevan mallin hinnoittelu
    output_price_per_million: float
    start_time: datetime = field(default_factory=now)
    end_time: datetime | None = None
    iterations: int = 0
    total_input_tokens: int = 0
    total_output_tokens: int = 0
    errors: list = field(default_factory=list)
    steps_completed: int = 0
    steps_total: int = 0

    def record_iteration(self, response):
        self.iterations += 1
        self.total_input_tokens += response.usage.input_tokens
        self.total_output_tokens += response.usage.output_tokens

    def record_error(self, error: str, step: str):
        self.errors.append({
            "step": step,
            "error": error,
            "timestamp": now().isoformat(),
        })

    def finalize(self):
        self.end_time = now()

    @property
    def duration_seconds(self) -> float:
        end = self.end_time or now()
        return (end - self.start_time).total_seconds()

    @property
    def estimated_cost_usd(self) -> float:
        # Arvio: kehystenvälimuistia ja hostattua ympäristöä ei lasketa
        input_cost = self.total_input_tokens / 1_000_000 * self.input_price_per_million
        output_cost = self.total_output_tokens / 1_000_000 * self.output_price_per_million
        return input_cost + output_cost

    def summary(self) -> dict:
        return {
            "workflow_id": self.workflow_id,
            "duration_s": round(self.duration_seconds, 1),
            "iterations": self.iterations,
            "tokens": self.total_input_tokens + self.total_output_tokens,
            "cost_usd": round(self.estimated_cost_usd, 4),
            "success": len(self.errors) == 0,
            "errors": len(self.errors),
            "steps": f"{self.steps_completed}/{self.steps_total}",
        }

Valvontakojelauta

Reaaliaikaista valvontaa varten lähetä mittarit valvontapalveluun äläkä anna niiden nukkua tiedostossa. Alla oleva funktio lähettää aikaleimatun yhteenvedon HTTP-päätepisteeseen kahdella varotoimella, jotka ovat yhtä tärkeitä kuin itse lähetys: enimmäisviive on viisi sekuntia, ja poikkeus siepataan tyytyen varoitukseen. Käyttämätön mittareiden kerääjä ei saa koskaan kaataa työnkulkua, jota se tarkkailee – päinvastainen olisi määritelmällisesti vastatuottavaa valvontaa.

import requests  # pip install requests

def push_metrics(metrics: WorkflowMetrics, endpoint: str):
    """Lähettää mittarit valvontapalveluun."""
    payload = metrics.summary()
    payload["timestamp"] = now().isoformat()

    try:
        requests.post(
            endpoint,
            json=payload,  # requests asettaa JSON-otsikon itse
            timeout=5,
        )
    except requests.RequestException as e:
        logger.warning(f"Metrics push error: {e}")

Automaattiset hälytykset

Kojelauta, jota kukaan ei katso, on vain arkisto. Määritä siis hälytykset kynnysarvojen perusteella, jotta poikkeama tulee luoksesi. Tässä säilytetyt neljä ehtoa kattavat klassiset ajautumat: kustannus yli kaksi dollaria, kesto yli kolme minuuttia, yli kolmekymmentä iteraatiota tai yli kaksi virhettä samassa suorituksessa. Nämä arvot ovat lähtökohtia, eivät totuuksia: kalibroi ne omien onnistuneiden suoritustesi mittausten perusteella asettamalla kynnys hyvin havaitun mediaanin yläpuolelle. Hälytys, joka laukeaa joka päivä, jätetään huomiotta toisella viikolla.

def check_alerts(metrics: WorkflowMetrics):
    """Tarkistaa kynnysarvot ja laukaisee hälytykset."""
    alerts = []

    if metrics.estimated_cost_usd > 2.0:
        alerts.append(f"High cost: ${metrics.estimated_cost_usd:.2f}")

    if metrics.duration_seconds > 180:
        alerts.append(f"Excessive duration: {metrics.duration_seconds:.0f}s")

    if metrics.iterations > 30:
        alerts.append(f"Too many iterations: {metrics.iterations}")

    if len(metrics.errors) > 2:
        alerts.append(f"Multiple errors: {len(metrics.errors)}")

    for alert in alerts:
        logger.warning(f"ALERT: {alert}")
        # Lähetä ilmoitus (sähköposti, Slack jne.)

    return alerts

Tee tavaksi kutsua check_alerts heti finalize-metodin jälkeen ja sen jälkeen push_metrics: saat arkistoidun jäljen jokaisesta suorituksesta, signaalin kojelaudalle ja ilmoituksen vain silloin, kun jokin ansaitsee huomiosi.

Keskeiset asiat

  • Lokita toiminnot, mallin viestit ja yhteenvedot sekä kaappaukset kolmelle erilliselle tasolle
  • Valvo onnistumisastetta, kestoa, token-kustannuksia ja virheitä; ketjutettu historia laskutetaan syötteinä joka kierroksella
  • Toteuta kuvakaappausten rotaatio välttääksesi levyn täyttymisen
  • Aseta automaattiset hälytykset kriittisille kynnysarvoille
  • Älä koskaan lokita arkaluonteisia tietoja (salasanoja, tokeneita, henkilötietoja)