Principles
Coevolved is designed to make agentic systems composable, observable, and testable without hiding control flow behind a “magic runtime”.Step-first design
The foundational unit isStep: a callable wrapper that can add:
- Input/output validation
- Structured tracing
- Stable step identity
Traceability by default
The runtime emits lifecycle events for steps and agent loops. This makes it possible to:- Debug failures without sprinkling print statements everywhere
- Measure runtime behavior over time
- Build your own sinks (console, files, dashboards)
State + schema validation
Coevolved assumes you’re passing around a “state” object (commonly adict).
Use Pydantic schemas when:
- You want to lock down state shape at module boundaries
- You want validation errors to be explicit and early
- You want better editor tooling and refactors
Composability over magic
Prefer explicit composition helpers (sequence, fallback, parallel, retry) over implicit orchestration.Coevolved intentionally keeps orchestration visible. You should be able to answer “what runs next?” by reading the code.
Prebuilt patterns vs custom agents
Use prebuilt patterns when they match your loop, then customize when you need:- Special termination logic
- Different tool execution behavior
- Richer checkpointing or HITL flows