Agents & behaviors
OmegaAgent is the home for side effects and domain reactions: HTTP, local DB, device APIs, analytics. It listens to the same OmegaChannel (or a namespace) as your flows.
The OmegaAgentBehaviorEngine turns incoming events / intents + agent state into an OmegaAgentReaction — a string action id and optional payload. The agent then executes onAction(String action, dynamic payload) with a switch (action) using string literals for each branch (see package lints — do not use enumCase.name in switch cases).
Why separate agent from flow?
| Flow | Agent |
|---|---|
| Orchestrates user-visible steps, expressions, navigation | Performs IO, retries, mapping to domain models |
| Answers “what happens next in the product story?” | Answers “how do we talk to the world?” |
Keeping widgets free of both keeps tests small: drive the channel and assert events / state.
Stateful agents
OmegaStatefulAgent exposes viewState / viewStateStream for UI that binds to typed state — use OmegaScopedAgentBuilder under OmegaAgentScope so pages do not thread the agent through every constructor.
Agent protocol (direct messaging)
OmegaAgentProtocol registers agents for point-to-point or broadcast messages — complementary to the global channel, not a replacement.
Contracts
Optional OmegaAgentContract lists events and intents the agent is prepared for — debug warnings when traffic does not match. See Contracts.
Reference implementation
Read example/lib/auth/auth_agent.dart and auth_behavior.dart in the repository line by line.