Agent Events

techrevati.runtime.agent_events

Agent Events — Typed lifecycle events with a failure taxonomy.

Provides a structured event schema for agent execution. Events are JSON-serializable and carry both an 'event' (full path) and a legacy 'type' (short tail) field. Route on 'event': 'type' is kept for backward compatibility and is ambiguous ('failed' is both agent.failed and agent.recovery.failed).

AgentEventName

Bases: str, Enum

Typed event names for agent and phase lifecycle.

AgentEventStatus

Bases: str, Enum

Current status at time of event emission.

AgentFailureClass

Bases: str, Enum

Failure taxonomy for structured error classification.

AgentEvent dataclass

AgentEvent(
    event,
    status,
    emitted_at=_now_iso(),
    role=None,
    phase=None,
    project_id=None,
    failure_class=None,
    detail=None,
    data=None,
)

A typed lifecycle event for agent orchestration.

turn_completed classmethod

turn_completed(
    role, phase, *, model, duration_seconds, data=None
)

One model turn finished; model may be empty when not supplied.

turn_failed classmethod

turn_failed(
    role,
    phase,
    *,
    model,
    duration_seconds,
    error_type,
    data=None,
)

One model turn failed; the agent itself may still recover and continue.

oversight_review_requested classmethod

oversight_review_requested(
    role, phase, *, decision_id, reviewer_id=None
)

Article 14 — a turn paused awaiting a human review decision.

oversight_review_resolved classmethod

oversight_review_resolved(
    role, phase, *, decision_id, decision, reviewer_id=None
)

Article 14 — a human reviewer resolved (or the timeout decided) a pause.

to_dict

to_dict()

JSON-serializable dict. Includes 'type' for backward compat.

to_json

to_json()

Strict JSON; non-finite floats in data become strings ("nan", "inf").

from_dict classmethod

from_dict(data)

Reconstruct AgentEvent from dict. Handles enum conversions.

from_json classmethod

from_json(s)

Reconstruct AgentEvent from JSON string.

to_otel_attributes

to_otel_attributes()

Convert to semantic-convention-style telemetry attributes.