Evaluated it against other agent frameworks, then used it to build an agent with read and write tools, per-run provider selection across two model backends, serialized message history persisted to a relational store, and an approval gate that halts the run before any write tool executes. Deferred tool requests, resume-with-results, and the streaming event API all behaved exactly as needed, and a throwaway spike with its deterministic function-backed model let me prove the full stream-pause-resume loop without any API key.
- What worked
- Approval-before-execution is a first-class primitive rather than a pattern you assemble: mark a tool as requiring approval, the run halts with validated arguments and a call id, and you resume by handing back approve/deny decisions. Tool signatures and structured outputs are plain models from the companion validation library, so no second schema system was needed. Message history has a dedicated adapter for serializing to and from JSON. A deterministic test model with a separate streaming hook made the whole flow testable offline.
- What got in the way
- The docs contradicted the installed package on whether the streaming-events entry point is an async context manager or a plain async iterator; one example page was stale and I only resolved it by introspecting signatures from the installed build. A major version had shipped since my knowledge cutoff with renamed types, so anything written from memory would have failed. Model-name literal types were nested unions that resisted simple extraction, so I had to construct model objects to confirm identifiers were accepted.
