Migrating from 0.4.x to 0.5.0¶
0.5.0 fixes defects found in a full audit of the 0.4.0 line and adds tool timeouts, tool replay, loop detection, provider fallback, and support for the MCP Python SDK 2.x. New API is additive, but several fixes change behaviour you may have relied on. Read this list before upgrading.
Three defaults to check first¶
- Unknown roles are denied.
default_allow_unknown_rolesnow defaults toFalse, so a role with no config can no longer use any tool. Add a config for each role, or passdefault_allow_unknown_roles=Trueto keep the old behaviour. - Timeouts count as circuit-breaker failures. A turn that hits its
timeoutnow moves the breaker towards opening. Reviewfailure_thresholdif your timeouts are tight enough to fire in normal operation. - New
audit_fail_closedoption, off by default. With it on, a failed audit write makes the session refuse further actions withAuditWriteError.
Sessions¶
- Usage without a
modelnow counts.run_turn(fn, usage=...)used to discard the usage, which silently disabledUsageLimits. It now reaches the tracker, so a limit that never fired before may fire. - A paid turn is booked before limits run. After a
BudgetExceededErrorthe governance plane and the checkpoint both include that turn, and when both a budget and a governance limit are crossed,GovernanceBreachErrorwins. - Hard limits are checked before a turn too. With
enforce_budget=Trueorusage_limits, a session already over its limit raises before calling the model. Code that caughtBudgetExceededErrorand carried on now gets it again before paying. - A replayed turn counts towards the budget of the session that replays it.
- Rate-limit tokens are taken later. The iteration cap, governance, and
before_modelhooks now run first, so a rejected turn spends no token. - New
agent.turn.completedandagent.turn.failedevents. Sinks and audit logs see more records. Code that compares a whole event list needs updating. - Tool events carry more data.
tool_completedand tool-failure events addduration_seconds, and failures adderror_type. Compare keys, not whole dicts. complete(),fail(), andcancel()emit only when the state changes. An exception afterhandoff_tois logged but no longer emitsagent.failed.- A
TimeoutErrorraised by your own code stays aTimeoutError. Only the session's deadline becomesTurnTimeoutError.
Streaming¶
timeoutcovers waiting on upstream, and can no longer cancel the consumer's task.- A limit crossed after the stream ends now yields
error+final("failed"). - A stream that ends early books its usage if
usageorestimate_usageprovides it and at least one chunk arrived. - Leaving a stream on purpose no longer counts as a failure, and its span and metric
carry no
error.type. - A chunk that is not a
strraisesTypeErrorthrough the terminal events.
Reliability primitives¶
- Circuit breaker: a probe silent for longer than
recovery_timeout_secondsis abandoned, and the result of any call admitted before the circuit last opened is ignored. A success from an abandoned probe can still close the circuit, so a downstream slower than the recovery window can recover; one new probe per window may run abovehalf_open_max_probesuntil then.half_open_max_probesnow limits probes per cycle, not just at once.record_success()closes a circuit that reports HALF_OPEN. - Rate limiter:
acquire_usageno longer rejects an amount above capacity, because it has already been spent. The balance goes negative and the call waits for it to refill, which can block for longer whentimeout=None. Debt is capped at 24 hours of refill, and amounts above1e15raiseValueError. - Failure classification: digits inside identifiers such as
req_84010no longer count as HTTP status codes, and context-overflow messages win over a stray429.prompt is too longis a context overflow, andToo many tokens, please waitis a rate limit. - Checkpoints:
getandlistorder by insertion rather than timestamp, so a clock step can no longer hide the latest checkpoint. A lone surrogate in a thread id or step key raisesValueError, onInMemorySavertoo.
Pricing and output parsing¶
- Pricing prefixes need a separator.
model-astill pricesmodel-a-20260514, but no longer pricesmodel-alpha, which now costs $0 and logs the usual warning. Register such models explicitly. UsageLimitExceededErrorforcost_usdreports dollars rather than micro-dollars.- A cache write on a model with only 5m and 1h tiers is charged at the higher tier rather than $0.
JsonOutputSpecrejectsNaNandInfinity, and rejectstrueforrequire_type=int.- Compaction always keeps the newest message, even if that exceeds the limit, and the
kept window never starts on a
toolmessage.
Guards and compliance¶
- A role that only resembles a configured role is denied. With
adminconfigured,ADMINoradminplus an invisible character is refused whateverdefault_allow_unknown_rolessays. Exact matches behave as before, andwriterandWRITERmay be configured separately. tool_requirementskeys that collide after folding, and tool names that fold to nothing, raiseValueErrorat construction.- A guardrail a sync session cannot enforce is refused before the tool runs, rather
than skipping the check. A fully async guardrail is still skipped with a warning. A
guardrail with no post check passes that stage, and one with no checks raises
TypeError. - Role configs whose names differ only by surrounding whitespace raise
ValueError. evaluate()raisesTypeErrorfor an async policy condition rather than treating it as true. Useevaluate_async.- Human oversight rejects a repeated
decision_id, a stale or future decision, a queue posing as the system reviewer, and an unknown outcome. The gate enforces its own timeout on a queue that hangs. verify_chainon a live sink detects a deleted tail. See the audit log guide fortip(),expected_tip, and the limit after a restart.purge_expiredrefuses a naivenowand only deletes a contiguous oldest prefix. It records a marker in a newaudit_log_purge_markertable, and the chain continues after a full purge rather than restarting from genesis.SqliteAuditBackendwaits up tobusy_timeout_seconds=30for a lock (about 5 before), so a write can block longer under heavy contention. Lower it for event-loop callers.- Audit payloads are cut at depth 100 or 100,000 nodes, with a marker, rather than dropping the event. A value that cannot be represented is replaced on its own.
InputSanitizationHookandOutputIntegrityGuardrailno longer reject binary such asb"\x00\x00\x00\x01", scan text-like bytes for escape sequences, and walk mappings and re-iterable containers.- With a signing key,
verify_chainreports a purge marker with a missing or wrong signature as invalid, including one left by a directbackend.purge_beforecall or a sink without the key. - Sets and frozensets in event data are recorded as lists, and tuple keys as JSON.
- A
decision_idwith surrounding whitespace raisesValueError. - Redacted dict keys that collide get a suffix (
[REDACTED]#2) rather than losing an entry. - The conformity self-check reports Article 12 as not met for an in-memory log, or when the purge floor is under 183 days.
Telemetry¶
- The agent span is named
invoke_agentfrom the start, notcreate_agent, and nests under its phase span. Update trace filters that match on the old name. OpenTelemetryUsageSinkalso emits thegen_ai.client.inference.usage.*counters.gen_ai.client.token.usageis no longer in the semantic conventions; it stays on for now andemit_legacy_token_metric=Falseturns it off.- New
OpenTelemetryMetricsSinkrecordsgen_ai.client.inference.durationandgen_ai.execute_tool.duration.
MCP¶
The [mcp] extra now accepts mcp>=1.10,<3. The floor moved because versions before
1.10 lack structuredContent. MCPToolAdapter accepts a 1.x or 2.x ClientSession
or a 2.x Client, and tool() takes a timeout.