Introduction
Tirea is an immutable state-driven agent framework built in Rust. It combines typed JSON state management with an agent loop, providing full traceability of state changes, replay capability, and component isolation.
Crate Overview
| Crate | Description |
|---|---|
tirea-state | Core library: typed state, JSON patches, apply, conflict detection |
tirea-state-derive | Proc-macro for #[derive(State)] |
tirea-contract | Shared contracts: thread/events/tools/plugins/runtime/storage/protocol |
tirea-agentos | Agent runtime: inference engine, tool execution, orchestration, plugin composition |
tirea-extension-* | Plugins: permission, reminder, observability, skills, MCP, A2UI |
tirea-protocol-ag-ui | AG-UI protocol adapters |
tirea-protocol-ai-sdk-v6 | Vercel AI SDK v6 protocol adapters |
tirea-store-adapters | Storage adapters: memory/file/postgres/nats-buffered |
tirea-agentos-server | HTTP/SSE/NATS gateway server |
tirea | Umbrella crate that re-exports core modules |
Architecture
┌─────────────────────────────────────────────────────┐
│ Application Layer │
│ - Register tools, define agents, call run_stream │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ AgentOs │
│ - Prepare run, execute phases, emit events │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Thread + State Engine │
│ - Thread history, RunContext delta, apply_patch │
└─────────────────────────────────────────────────────┘
Core Principle
All state transitions follow a deterministic, pure-function model:
State' = apply_patch(State, Patch)
- Same
(State, Patch)always produces the sameState' apply_patchnever mutates its input- Full history enables replay to any point in time
What’s in This Book
- Tutorials — Learn by building a first agent and first tool
- How-to — Task-focused implementation guides for integration and operations
- Reference — API, protocol, config, and schema lookup pages
- Explanation — Architecture and design rationale
Recommended Reading Path
If you are new to the repository, use this order:
- Read First Agent to see the smallest runnable flow.
- Read First Tool to understand state reads and writes.
- Read Typed Tool Reference before writing production tools.
- Use Build an Agent and Add a Tool as implementation checklists.
- Return to Architecture and Run Lifecycle and Phases when you need the full execution model.
Repository Map
These paths matter most when you move from docs into code:
| Path | Purpose |
|---|---|
crates/tirea-contract/ | Core runtime contracts: tools, events, state/runtime interfaces |
crates/tirea-agentos/ | Agent runtime: inference engine, tool execution, orchestration, extensions |
crates/tirea-agentos-server/ | HTTP/SSE/NATS server surfaces |
crates/tirea-state/ | Immutable state patch/apply/conflict engine |
examples/src/ | Small backend examples for tools, agents, and state |
examples/ai-sdk-starter/ | Shortest browser-facing end-to-end example |
examples/copilotkit-starter/ | Richer end-to-end UI example with approvals and persistence |
docs/book/src/ | This documentation source |
For the full Rust API documentation, see the API Reference.