Valvonta ja lokitus
Tällä sivulla
Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n Computer use -oppaan ja Responses API -dokumentaation perusteella: lokitus lukee nyt toiminnot
computer_call-objektista ja elementitresponse.output-rakenteesta (viestitphase-tietoineen, päättelyyhteenvetoineen ja kutsuineen) Anthropicin API:ntool_use-lohkojen sijaan; kovakoodattu Claude Sonnet -hinnoittelu on korvattu käytössä olevan mallin hinnoittelulla, ja vanhentunutdatetime.utcnow()(Python 3.12:sta lähtien) on korvattu funktiolladatetime.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
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)