本文档为中文翻译版本，英文原版请参阅 Introduction

简介

Tirea 是一个用 Rust 构建的不可变状态驱动 Agent 框架。它将类型化 JSON 状态管理与 Agent 循环相结合，提供对状态变更的完整可追溯性、回放能力以及组件隔离。

Crate 概览

架构

┌─────────────────────────────────────────────────────┐
│  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     │
└─────────────────────────────────────────────────────┘

核心原则

所有状态转换均遵循确定性纯函数模型：

State' = apply_patch(State, Patch)

• 相同的 (State, Patch) 始终产生相同的 State'
• apply_patch 不会修改其输入
• 完整的历史记录支持回放到任意时间点

本书内容

• 教程 — 通过构建第一个 Agent 和第一个工具来学习
• 操作指南 — 面向具体任务的集成与运维实现指南
• 参考手册 — API、协议、配置及 Schema 查询页面
• 原理解析 — 架构与设计决策说明

推荐阅读路径

如果您是首次接触本代码库，建议按以下顺序阅读：

1. 阅读 First Agent，了解最小可运行流程。
2. 阅读 First Tool，理解状态读写机制。
3. 在编写生产级工具前，阅读 Typed Tool Reference。
4. 将 Build an Agent 和 Add a Tool 作为实现检查清单使用。
5. 需要了解完整执行模型时，回头阅读 Architecture 和 Run Lifecycle and Phases。

代码库目录结构

从文档转入代码时，以下路径最为重要：

完整的 Rust API 文档请参阅 API Reference。