Design Philosophy

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 is Step: a callable wrapper that can add:

• Input/output validation
• Structured tracing
• Stable step identity

Once everything is a Step (including “agents”), composition becomes straightforward.

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 a dict).

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

Next steps

Composition

Learn how to build workflows from reusable building blocks.

Tracing

Understand the event model and how to observe runs.