Core Concepts Overview

Learn about the three primitives that power AgentOS - Worker, Function, and Trigger

AgentOS is built on three simple primitives that work together to create a powerful, polyglot agent operating system.

The Three Primitives

Every component in AgentOS is built using these three fundamental concepts:

Worker

A process that connects to the iii-engine and registers functions

Function

A callable unit of work with a unique ID and description

Trigger

An event that invokes a function (HTTP, queue, cron, etc.)

How It Works

Every component is a Worker that registers Functions and binds them to Triggers. Functions call each other via trigger() regardless of programming language.

1. Workers Connect

   Each worker connects to the iii-engine over WebSocket at ws://localhost:49134

   let iii = III::new("ws://localhost:49134");
   
2. Functions Register

   Workers register functions with unique IDs and descriptions

   iii.register_function_with_description(
       "agent::chat",
       "Process a message through the agent loop",
       move |input: Value| { /* handler */ },
   );
   
3. Triggers Bind

   Functions are bound to triggers (HTTP, queue, cron, etc.)

   iii.register_trigger("queue", "agent::chat", json!({
       "topic": "agent.inbox"
   }))?;
   
4. Functions Communicate

   Functions call each other using trigger() across languages

   let result = iii.trigger("memory::recall", json!({
       "agentId": &agent_id,
       "query": &message,
       "limit": 20,
   })).await?;
   

Real-World Example: Chat Flow

Here’s how a complete chat request flows through the system:

Actual Code Example

Here’s the real code from the agent-core worker showing the complete flow:

Rust Agent Loop

// From crates/agent-core/src/main.rs:103-169
async fn agent_chat(iii: &III, req: ChatRequest) -> Result<Value, IIIError> {
    // 1. Recall memories
    let memories: Value = iii
        .trigger("memory::recall", json!({
            "agentId": &req.agent_id,
            "query": &req.message,
            "limit": 20,
        }))
        .await
        .unwrap_or(json!([]));

    // 2. Get available tools
    let tools: Value = iii
        .trigger("agent::list_tools", json!({ "agentId": &req.agent_id }))
        .await
        .unwrap_or(json!([]));

    // 3. Route to appropriate model
    let model: Value = iii
        .trigger("llm::route", json!({
            "message": &req.message,
            "toolCount": tools.as_array().map(|a| a.len()).unwrap_or(0),
        }))
        .await
        .map_err(|e| IIIError::Handler(e.to_string()))?;

    // 4. Security scan
    let scan_result = iii
        .trigger("security::scan_injection", json!({ "text": &req.message }))
        .await
        .unwrap_or(json!({ "safe": true, "riskScore": 0.0 }));

    // 5. Call LLM
    let response: Value = iii
        .trigger("llm::complete", json!({
            "model": model,
            "systemPrompt": system_prompt,
            "messages": messages,
            "tools": tools,
        }))
        .await
        .map_err(|e| IIIError::Handler(e.to_string()))?;

    // 6. Execute tool calls and iterate
    while let Some(tool_calls) = response.get("toolCalls") {
        // Execute each tool via trigger()
        let result = iii.trigger(&tc.id, tc.arguments.clone()).await?;
    }

    Ok(response)
}

Key Benefits

No Vendor Lock-in

Every capability is a plain function. No frameworks, no magic.

Polyglot by Design

Write workers in Rust, TypeScript, or Python. They all communicate seamlessly.

Hot-Swappable

Replace any function without touching other components.

Testable

Every function can be tested independently. 2,506 tests across all languages.

Architecture Layers

AgentOS is structured in layers, each implemented as workers:

Every layer connects to the same iii-engine bus. There’s no special hierarchy - just functions calling functions.

Layer	Languages	Purpose	Example Workers
Hot Path	Rust	Performance-critical operations	agent-core, memory, llm-router, security, wasm-sandbox
Control Plane	Rust	Multi-tenant orchestration	realm, hierarchy, directive, mission, ledger, council, pulse, bridge
Application	TypeScript	Iteration speed, integrations	api, tools, workflows, swarm, knowledge-graph, session-replay
ML	Python	Machine learning workloads	embedding (SentenceTransformers)

Next Steps

Workers

Learn how to create workers in Rust, TypeScript, and Python

Functions

Deep dive into function registration and invocation

Triggers

Explore HTTP, queue, cron, and pubsub triggers