Packages

codex_sdk

0.3.0
0.18.1 0.18.0 0.17.0 0.16.1 0.16.0 0.14.0 0.13.0 0.12.0 0.11.0 0.10.1 0.10.0 0.9.0 0.8.0 0.7.2 0.7.1 0.7.0 0.6.0 0.5.0 0.4.5 0.4.4 0.4.3 0.4.2 0.4.1 0.4.0 0.3.0 0.2.5 0.2.4 0.2.3 0.2.2 0.2.1 0.2.0 0.1.0

Idiomatic Elixir SDK for OpenAI's Codex agent. Provides a complete, production-ready interface with streaming support, comprehensive event handling, and robust testing utilities.

HexDocs

Current section

Files

Jump to
Readme
32 Versions
6 Dependencies
Dependants
Files
Activity
codex_sdk docs 20251202 adrs adr-001-agent-runner.md
Raw

docs/20251202/adrs/adr-001-agent-runner.md 

# ADR-001: Add Agent Abstraction and Multi-Turn Runner



Status: Proposed



Context

- Python: `src/agents/agent.py` defines Agent with instructions/prompt, handoffs, output_type, tool_use_behavior, guardrails, hooks; `src/agents/run.py` provides `Runner.run/run_sync/run_streamed`, `RunConfig`, max_turns enforcement, conversation resume.

- Elixir: `lib/codex/thread.ex` runs single codex turn (or auto-run retry) without Agent struct or RunConfig; no per-run hooks or reusable agent definitions.



Decision

- Introduce `Codex.Agent` struct and `Codex.RunConfig` mirroring Python semantics (instructions/prompt, model settings overrides, hooks, tool_use_behavior placeholder, guardrail lists, nest_handoff_history, call_model_input_filter later).

- Replace the one-shot `Thread.run/3` orchestration with a multi-turn runner that loops until final output or max_turns, including handoff/tool handling.

- Keep existing `Codex.Thread` as thin facade over the new runner for compatibility.



Consequences

- Benefits: unlocks feature parity (handoffs, guardrails, sessions), clearer public API, reusable agent templates.

- Risks: significant refactor of turn pipeline; needs careful backward compatibility and telemetry continuity; may expose codex binary limitations.

- Actions: design `Codex.Agent` and `Codex.RunConfig` structs; build runner loop with max_turns and error taxonomy; update docs/examples; add migration helpers to wrap old Thread calls.