Expand description
§layer0 — Protocol traits for composable agentic AI systems
This crate defines the four protocol boundaries and two cross-cutting interfaces that compose to form any agentic AI system.
§The Protocols
| Protocol | Trait | What it does |
|---|---|---|
| ① Operator | Operator | What one agent does per cycle |
| ② Orchestration | Orchestrator | How agents compose + durability |
| ③ State | StateStore | How data persists across turns |
| ④ Environment | Environment | Isolation, credentials, resources |
§The Interfaces
| Interface | Types | What it does |
|---|---|---|
| ⑤ Hooks | Hook, HookPoint, HookAction | Observation + intervention |
| ⑥ Lifecycle | BudgetEvent, CompactionEvent | Cross-layer coordination |
§Design Principle
Every protocol trait is operation-defined, not mechanism-defined.
Operator::execute means “cause this agent to process one cycle” —
not “make an API call” or “run a subprocess.” This is what makes
implementations swappable: a Temporal workflow, a function call,
and a future system that doesn’t exist yet all implement the same trait.
§Companion Documents
- Agentic Decision Map: enumerates all 23 architectural decisions
- Composable Agentic Architecture: the 4+2 protocol boundary design
§Dependency Notes
This crate depends on serde_json::Value for extension data fields
(metadata, tool inputs, custom payloads). This is an intentional choice:
JSON is the universal interchange format for agentic systems, and
serde_json::Value is the de facto standard in the Rust ecosystem.
The alternative (generic T: Serialize) would complicate trait object
safety without practical benefit.
§Future: Native Async Traits
Protocol traits currently use async-trait (heap-allocated futures).
When Rust stabilizes async fn in dyn Trait with Send bounds,
these traits will migrate to native async. This will be a breaking
change in a minor version bump before v1.0.
Re-exports§
pub use content::Content;pub use content::ContentBlock;pub use duration::DurationMs;pub use effect::Effect;pub use effect::Scope;pub use effect::SignalPayload;pub use environment::Environment;pub use environment::EnvironmentSpec;pub use error::EnvError;pub use error::HookError;pub use error::OperatorError;pub use error::OrchError;pub use error::StateError;pub use hook::Hook;pub use hook::HookAction;pub use hook::HookContext;pub use hook::HookPoint;pub use id::AgentId;pub use id::ScopeId;pub use id::SessionId;pub use id::WorkflowId;pub use lifecycle::BudgetEvent;pub use lifecycle::CompactionEvent;pub use lifecycle::ObservableEvent;pub use operator::ExitReason;pub use operator::Operator;pub use operator::OperatorConfig;pub use operator::OperatorInput;pub use operator::OperatorMetadata;pub use operator::OperatorOutput;pub use operator::ToolCallRecord;pub use orchestrator::Orchestrator;pub use orchestrator::QueryPayload;pub use secret::SecretAccessEvent;pub use secret::SecretAccessOutcome;pub use secret::SecretSource;pub use state::SearchResult;pub use state::StateReader;pub use state::StateStore;
Modules§
- content
- Universal content types that cross every protocol boundary.
- duration
- Stable duration type for protocol wire format.
- effect
- Effect system — side-effects declared by operators for external execution.
- environment
- The Environment protocol — isolation, credentials, and resource constraints.
- error
- Error types for each protocol.
- hook
- The Hook interface — observation and intervention in the turn’s inner loop.
- id
- Typed ID wrappers for agent, session, workflow, and scope identifiers.
- lifecycle
- Lifecycle events — cross-protocol coordination vocabulary.
- operator
- The Operator protocol — what one agent does per cycle.
- orchestrator
- The Orchestrator protocol — how operators from different agents compose.
- secret
- Secret management data types — the stability contract for credential resolution.
- state
- The State protocol — how data persists and is retrieved across turns.