English | 中文

Tirea

Type-safe AI agents that handle concurrent state without locks. One binary serves React, Next.js, and other agents over four protocols.

Define agents, tools, and state in Rust — then serve them to any frontend over AG-UI, AI SDK v6, A2A, and ACP from a single binary. Connect to external tool servers via MCP.

30-second mental model

1. Tools — typed functions your agent can call; JSON schema is generated from the struct
2. Agents — each agent has a system prompt and a set of allowed tools/sub-agents; the LLM drives all orchestration through natural language — no predefined graphs or state machines
3. State — typed, scoped (thread / run / tool_call), with CRDT fields for safe concurrent writes
4. Plugins — lifecycle hooks for permissions, observability, context window, reminders, and more

Your agent picks tools, calls them, reads and updates state, and repeats — all orchestrated by the runtime. Every state change is an immutable patch you can replay.

Why Tirea

Feature comparison

✅ = native ◐ = partial ❌ = not available

What does "Tool delegation" mean? Tirea follows the Claude Code orchestration pattern: the LLM manages sub-agents through tool calls (agent_run, agent_stop, agent_output) instead of hand-coded graphs or one-way handoffs.

	Tool delegation (Tirea)	Handoffs + as_tool (OpenAI)	Conversational (AG2)
Mechanism	LLM calls tools to spawn, stop, and read sub-agents	Handoffs transfer control; as_tool() calls agent and returns result	Agents converse in a group chat with speaker selection
Parallel execution	✅ background mode, multiple sub-agents	◐ as_tool() via async; handoffs are sequential	❌ sequential turns
Bidirectional	✅ parent reads child output, can stop	◐ as_tool() returns results; handoffs are one-way	✅ all agents see shared conversation
Status awareness	✅ auto-injected reminder each turn	❌ no automatic status injection	✅ via shared chat history
Agent discovery	Dynamic catalog rendered in system prompt	Hard-coded handoffs=[] in code	Predefined participants=[]

Quick start

Prerequisites

• Rust toolchain from rust-toolchain.toml
• For frontend demos: Node.js 20+ and npm
• One model provider key (OpenAI, DeepSeek, Anthropic, etc.)

Full-stack demo in 60 seconds

React + AI SDK v6:

git clone https://github.com/tirea-ai/tirea.git && cd tirea
cd examples/ai-sdk-starter && npm install
DEEPSEEK_API_KEY=<your-key> npm run dev
# First run compiles the Rust agent (~1-2 min), then opens http://localhost:3001

Next.js + CopilotKit:

cd examples/copilotkit-starter && npm install
cp .env.example .env.local
DEEPSEEK_API_KEY=<your-key> npm run setup:agent && npm run dev
# Open http://localhost:3000

Server only

export OPENAI_API_KEY=<your-key>
cargo run --package tirea-agentos-server -- --http-addr 127.0.0.1:8080

Usage

Architecture

graph LR
    subgraph "Your frontends"
        A["React app\n(AI SDK v6)"]
        B["Next.js app\n(CopilotKit / AG-UI)"]
        C["Another agent\n(A2A)"]
    end

    subgraph "tirea server (one binary)"
        GW["Protocol gateway\nUI: AG-UI · AI SDK\nAgent: A2A · ACP"]
        RT["Agent runtime\nLLM streaming · tool dispatch\nplugin lifecycle · context mgmt"]
        EXT["Extensions\npermission · skills · MCP\nreminder · observability"]
    end

    subgraph "Storage (pick one)"
        S1[(File)]
        S2[(PostgreSQL)]
    end

    A & B --> GW
    C --> GW
    GW --> RT
    RT --> EXT
    RT --> S1 & S2

Define tools, agents, and assemble

// 1. Build tools — define args as a struct, schema is generated automatically
#[derive(Deserialize, JsonSchema)]
struct SearchFlightsArgs {
    from: String,
    to: String,
    date: String,
}

struct SearchFlightsTool;

#[async_trait]
impl TypedTool for SearchFlightsTool {
    type Args = SearchFlightsArgs;
    fn tool_id(&self) -> &str { "search_flights" }
    fn name(&self) -> &str { "Search Flights" }
    fn description(&self) -> &str { "Find flights between two cities." }

    async fn execute(&self, args: SearchFlightsArgs, _ctx: &ToolCallContext<'_>)
        -> Result<ToolResult, ToolError>
    {
        // ... call your flight API ...
        Ok(ToolResult::success("search_flights", json!({
            "flights": [{"airline": "UA", "price": 342, "from": args.from, "to": args.to}]
        })))
    }
}

// 2. Define agents — each agent selects which tools/skills/sub-agents it can use
let planner = AgentDefinition::with_id("planner", "deepseek-chat")
    .with_system_prompt("You are a travel planner. Use search tools to find options.")
    .with_max_rounds(8)
    .with_allowed_tools(vec!["search_flights".into(), "search_hotels".into()])
    .with_allowed_agents(vec!["researcher".into()]);

let researcher = AgentDefinition::with_id("researcher", "deepseek-chat")
    .with_system_prompt("You research destinations and provide summaries.")
    .with_max_rounds(4)
    .with_excluded_tools(vec!["delete_account".into()]);

// 3. Assemble into AgentOs — the container for all components
let os = AgentOsBuilder::new()
    .with_tools(tool_map_from_arc(vec![
        Arc::new(SearchFlightsTool),
        Arc::new(SearchHotelsTool),
    ]))
    .with_agent_spec(AgentDefinitionSpec::local(planner))
    .with_agent_spec(AgentDefinitionSpec::local(researcher))
    .with_agent_state_store(Arc::new(FileStore::new("./sessions")))
    .build()?;

Tools are registered globally. Each agent controls its own access via allowed_* / excluded_* lists — the runtime filters the tool pool at resolve time.

Connect to any frontend

Start the server, then connect from React, Next.js, or another agent — no code changes between them:

cargo run --package tirea-agentos-server -- --http-addr 127.0.0.1:8080

React + AI SDK v6:

import { useChat } from "ai/react";

const { messages, input, handleSubmit } = useChat({
  api: "http://localhost:8080/v1/ai-sdk/agents/assistant/runs",
});

Next.js + CopilotKit:

import { CopilotKit } from "@copilotkit/react-core";

<CopilotKit runtimeUrl="http://localhost:8080/v1/ag-ui/agents/assistant/runs">
  <YourApp />
</CopilotKit>

Built-in tools

Tirea ships with tools for sub-agents, background tasks, skills, UI rendering, and MCP integration. They're auto-registered when you enable the corresponding feature:

Require approval before dangerous actions

The built-in PermissionPlugin gates tool execution via Allow/Deny/Ask policies per tool. When a tool requires approval, the runtime suspends execution and sends the pending call to the frontend. When the user approves, the runtime replays the original tool call. See the human-in-the-loop guide for details.

Multi-agent collaboration

Tirea agents delegate through natural-language orchestration. You define each agent's identity and access policy, then register them in the agent registry; the LLM decides when to delegate, to whom, and how to combine results — no DAGs, no hand-coded state machines, no explicit routing logic.

The runtime makes this work:

• Agent registry — register agents at build time; the runtime renders the registry into the system prompt so the LLM always knows who it can delegate to
• Background execution with completion notifications — sub-agents and tasks run in the background; the runtime injects their status after each tool call, so the LLM stays aware of what's running, what's finished, and what failed
• Foreground and background modes — block until a sub-agent finishes, or run multiple sub-agents concurrently in the background and receive completion notifications when each one finishes
• Thread isolation — each sub-agent runs in its own thread with independent state
• Orphan recovery — if the parent process crashes, orphaned sub-agents are detected and resumed on restart
• Local + remote transparency — in-process agents and remote A2A agents use the same agent_run interface; the orchestrator doesn't need to know the difference

Register agents at build time:

let orchestrator = AgentDefinition::with_id("orchestrator", "deepseek-chat")
    .with_system_prompt("Route tasks to the right agent.")
    .with_allowed_agents(vec!["researcher".into(), "writer".into()]);

let researcher = AgentDefinition::with_id("researcher", "deepseek-chat")
    .with_system_prompt("Research topics and return summaries.")
    .with_excluded_tools(vec!["agent_run".into()]); // no further delegation

let os = AgentOsBuilder::new()
    .with_agent_spec(AgentDefinitionSpec::local(orchestrator))
    .with_agent_spec(AgentDefinitionSpec::local(researcher))
    // Remote agents via A2A protocol
    .with_agent_spec(AgentDefinitionSpec::a2a_with_id(
        "writer",
        A2aAgentBinding::new("https://writer-service.example.com/v1/a2a", "writer-v2"),
    ))
    .build()?;

See the multi-agent design patterns guide for coordinator, pipeline, fan-out, and other patterns.

Manage state across conversations

State is typed and scoped to its intended lifetime:

#[derive(State)]
#[tirea(scope = "thread")]   // persists across all runs in this conversation
struct UserPreferences { /* ... */ }

#[derive(State)]
#[tirea(scope = "run")]      // reset at the start of each agent run
struct SearchProgress { /* ... */ }

#[derive(State)]
#[tirea(scope = "tool_call")] // exists only during a single tool execution
struct ToolWorkspace { /* ... */ }

Fields marked #[tirea(lattice)] use CRDT types (conflict-free replicated data types) that merge automatically when parallel tool calls write concurrently — no locks needed. Non-CRDT fields are guarded by conflict detection.

Persist conversations

Swap storage backends without changing agent code:

Extend with plugins

Plugins hook into 8 lifecycle phases. Use built-in plugins or write your own:

Use any LLM provider

Powered by genai — works with OpenAI, Anthropic, DeepSeek, Google, Mistral, Groq, Ollama, and more. Switch providers by changing one string:

model: "gpt-4o".into(),        // OpenAI
model: "deepseek-chat".into(), // DeepSeek
model: "claude-sonnet-4-20250514".into(), // Anthropic

When to use Tirea

• You want a Rust backend for AI agents with compile-time safety
• You need to serve multiple frontend protocols from one server
• Your tools need to safely share state during concurrent execution
• You need auditable state history and replay
• You're building for production — low memory, no GC, thousands of concurrent agents

When NOT to use Tirea

• You need built-in file/shell/web tools out of the box — consider Dify, CrewAI
• You want a visual workflow builder — consider Dify, LangGraph Studio
• You want Python and rapid prototyping — consider LangGraph, AG2, PydanticAI
• You need LLM-managed memory (agent decides what to remember) — consider Letta

Design inspirations

Tirea's architecture draws from ideas across several projects:

• Claude Code — natural-language multi-agent orchestration, mailbox-based message passing, persistent reminders across turns
• ag2 / FastAgency — NATS JetStream as a durable transport layer for agent event streaming and crash recovery
• LangGraph — typed state with reducers and checkpoint persistence (Tirea extends this with patch-based immutability and replay)

Learning paths

Examples

Documentation

Full book: https://tirea-ai.github.io/tirea/ · API reference · Book source

Contributing

See CONTRIBUTING.md. Contributions welcome — especially:

• Built-in tool implementations (file read/write, search, shell execution)
• Tool-level concurrency safety flags
• Model fallback/degradation chains
• Token cost tracking
• Additional storage backends

License

Dual-licensed under MIT or Apache-2.0.

SECURITY.md · CODE_OF_CONDUCT.md