runcycles/cycles-openai-agents

cycles-openai-agents is a focused and useful integration layer for a very specific problem: bringing budget and action governance into the OpenAI Agents SDK without forcing users to decorate every tool or rewrite agent logic. The best design choice is that it plugs into the SDK’s native RunHooks and InputGuardrail surfaces. That makes the package feel like part of the agent runtime rather than a generic wrapper sitting off to the side.

The README explains the value clearly. It shows the practical failure modes: runaway LLM calls, uncontrolled tools like send_email, missing tenant budgets, and no audit trail. Then it maps those to concrete hooks: on_llm_start reserves, on_llm_end commits actual usage, on_tool_start reserves from the tool estimate map, on_tool_end commits, and on_handoff records an audit event. The pre-run cycles_budget_guardrail is also a good fit because it can deny before any tokens are spent. I especially like the tool estimate map design: being able to set "search_knowledge": 0 while charging risk points for higher-impact tools is a clean policy model.

The implementation signals are solid for a young project. It has 72 commits, four releases, Apache-2.0 licensing, CI, PyPI publish automation, Scorecard, strict mypy, Ruff, pytest coverage with a 95% threshold, typed package marker support, and examples for basic budget enforcement, tool governance, and multi-agent handoff. The AUDIT.md is unusually helpful: it checks all 7 OpenAI Agents hook signatures, guardrail integration, Cycles reserve/commit/release/decide/event calls, heartbeat behavior, fail-open/fail-closed handling, and reports 97 tests with 100% coverage.

The main thing I’d improve is production guidance around failure behavior. The README does mention fail_open=True by default and release_pending() after failed runs, but those choices are important enough to deserve a small “production checklist”: when to use fail-closed, how to size TTLs, how to choose tool estimates, what happens on process crash, and how to monitor denied runs. I’d also add one short architecture diagram or lifecycle sequence because hooks, guardrails, reservations, commits, and handoffs are a lot for new users to hold at once. Overall, this is a well-scoped integration with strong docs and test discipline; the next step is making operational adoption as clear as the API.