Architecture on Yarang's Tech Lair

MCP Integration Guide: Integrating Discord MCP with ZeroClaw Runtime

Sun, 28 Jun 2026 09:00:35 +0900

With the recent release of ZeroClaw, a high-performance Rust agent runtime, we’ve been deeply contemplating ways to maximize the efficiency of multi-agent systems. In particular, the complexity of communication protocols encountered during the design of the [Discord Decision MCP] architecture was a decisive factor in adopting MCP (Model Context Protocol) as a standard interface.

In this post, we will explain how to actually integrate Discord MCP within the ZeroClaw environment, detailing the process of agents receiving and processing Discord messages with concrete code examples.

1. Architecture Design: Dual Communication on a Single Channel

In the previous [Discord MCP] Gateway architecture, the gateway played the role of filtering events and delivering them to agents. However, by directly implementing the MCP client within ZeroClaw, we’ve altered the design to eliminate the intermediate layer and reduce latency.

The core idea is a flow where the MCP Client transmits Discord events to the ZeroClaw process via stdio, and then sends the agent’s responses back to Discord.

2. Essential Dependencies and Setup (Rust)

As ZeroClaw is written in Rust, it utilizes the asynchronous runtime tokio for high concurrency processing and serde for JSON handling. Communication with the MCP server is assumed to involve exchanging JSON-RPC messages via standard input/output (stdio).

# Cargo.toml
[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
async-trait = "0.1"

3. MCP Client Implementation

We define a simple client structure to control the Discord MCP server within ZeroClaw. This client uses the tools/call method, which adheres to the MCP standard, to execute Discord bot functionalities.

use serde::{Deserialize, Serialize};
use std::process::{Command, Stdio};
use std::io::{BufReader, BufWriter, Write};

#[derive(Debug, Serialize, Deserialize)]
struct MCPRequest {
 jsonrpc: String,
 id: u64,
 method: String,
 params: serde_json::Value,
}

#[derive(Debug, Serialize, Deserialize)]
struct MCPResponse {
 jsonrpc: String,
 id: u64,
 result: Option<serde_json::Value>,
}

pub struct DiscordMCPClient {
 id: u64,
}

impl DiscordMCPClient {
 pub fn new() -> Self {
 Self { id: 0 }
 }

 /// Executes an MCP tool to send a message to a Discord channel
 pub async fn send_message(&mut self, channel_id: &str, content: &str) -> Result<(), Box<dyn std::error::Error>> {
 self.id += 1;
 
 // Execute MCP server process (e.g., Python-based Discord MCP server)
 let mut child = Command::new("python3")
 .arg("discord_mcp_server.py")
 .stdin(Stdio::piped())
 .stdout(Stdio::piped())
 .spawn()?;

 let stdin = child.stdin.as_mut().ok("Failed to open stdin")?;
 let mut stdout = BufReader::new(child.stdout.as_mut().ok("Failed to open stdout")?);

 let request = MCPRequest {
 jsonrpc: "2.0".to_string(),
 id: self.id,
 method: "tools/call".to_string(),
 params: serde_json::json!({
 "name": "send_message",
 "arguments": {
 "channel_id": channel_id,
 "content": content
 }
 }),
 };

 // Send request
 let request_json = serde_json::to_string(&request)?;
 writeln!(stdin, "{}", request_json)?;

 // (In a real implementation, logic to parse the response from an asynchronous reader is needed)
 // Omitted here for simplicity.
 
 Ok(())
 }
}

4. Integration with ZeroClaw Agents

Now, let’s use the DiscordMCPClient created above within ZeroClaw’s agent loop. This scenario demonstrates an agent notifying Discord upon completing a specific task.

struct ZeroClawAgent {
 discord_client: DiscordMCPClient,
}

impl ZeroClawAgent {
 async fn run_task(&mut self, task: &str) {
 println!("[Agent] Starting task: {}", task);
 
 // Complex reasoning or file processing logic (omitted)
 // ...

 let result = format!("Task '{}' completed.", task);

 // Send result to Discord
 match self.discord_client.send_message("123456789", &result).await {
 Ok(_) => println!("[Agent] Successfully sent Discord notification"),
 Err(e) => eprintln!("[Agent] Sending failed: {}", e),
 }
 }
}

#[tokio::main]
async fn main() {
 let mut agent = ZeroClawAgent {
 discord_client: DiscordMCPClient::new(),
 };

 agent.run_task("Analyze server logs").await;
}

5. Efficiency and Security Considerations (Architecture Insights)

Resource Management: Similar to the trending ‘Adrafinil’ on [Hacker News], applying speculative decoding by disconnecting the Discord MCP connection when the agent is idle and only establishing it when a task is active can save resources.
Security: As highlighted in issues related to [Anonymous GitHub accounts], parameters passed to the MCP server (e.g., API tokens) should be managed via environment variables or fetched from a separate secure storage (Vault). Hardcoding secrets in code is critical.
Error Handling: As discussed in communication platform design considerations, it’s important to include retry logic in the MCP client, taking into account Discord API’s Rate Limits.

Conclusion

Integrating ZeroClaw and Discord MCP goes beyond simply creating a bot; it’s a process of building a standardized interface for agents to interact with the external world. Leveraging our experience in building [MCP] blog automation systems, we plan to further develop more sophisticated multi-agent collaboration systems.

ZeroClaw Agent Runtime: Implementing a TCP/IP Architecture for High-Performance Multi-Agent Communication

Fri, 26 Jun 2026 09:01:09 +0900

Hello! As the open-source AI and agent ecosystem rapidly expands, there’s a growing interest in “multi-agent systems” where multiple agents collaborate beyond a single LLM. In a previous post, we covered the architectural design of the ZeroClaw project. This time, we aim to introduce the specific implementation details of how the actual ZeroClaw runtime internally handles inter-agent communication and achieves high performance by leveraging Rust’s powerful asynchronous runtime.

Challenges with Existing Communication and ZeroClaw’s Approach

Typical MCP (Model Context Protocol) or basic agent systems primarily handle communication through in-memory sharing within a single process or simple local function calls. However, as systems become more complex and agents become distributed, the following problems arise:

Scalability Limitations: Single-process memory buffers are finite, and bottlenecks occur when hundreds of agents send and receive messages simultaneously.
Increased Coupling: Communication between agents is tightly coupled with logic, making it difficult to replace or update specific agents.
Network Separation: If the communication methods differ between local development environments and cloud deployment environments, code modifications are required.

To address these issues, ZeroClaw adopts a hybrid approach that combines “file-based architecture design” with a “TCP/IP networking layer.” Agents declaratively record their state in the file system, and actual message transmission is handled via asynchronous TCP sockets.

Asynchronous Server Structure Using Rust Tokio

The core of ZeroClaw is its high-performance networking layer built on Rust’s tokio runtime. Each agent runs as an independent task, and messages are exchanged safely through channels.

Here’s a simplified example of the message broker, which is central to the ZeroClaw runtime.

1. Defining Basic Message Structures

First, we define the data structures for messages exchanged between agents. serde is used to automate serialization.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentMessage {
 pub source: String, // Sender agent ID
 pub target: String, // Receiver agent ID (or "broadcast")
 pub payload: PayloadType,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum PayloadType {
 Text(String),
 Data(HashMap<String, String>), // Map for flexible data transfer
 Control(ControlSignal),
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ControlSignal {
 Start,
 Stop,
 HeartBeat,
}

2. Implementing Asynchronous TCP Handlers

Actual communication occurs through tokio::net::TcpListener. Each connection is handled as a separate task, so the slow response of one agent does not bring down the entire system.

use tokio::net::{TcpListener, TcpStream};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::sync::mpsc;

#[derive(Clone)]
struct AgentConfig {
 id: String,
}

pub async fn run_agent_server(config: AgentConfig) -> Result<(), Box<dyn std::error::Error>> {
 let listener = TcpListener::bind("127.0.0.1:8080").await?;
 println!("[{}] Agent Server listening on 127.0.0.1:8080", config.id);

 // Channel for message routing (a more complex router would be used in actual implementation)
 let (tx, mut rx) = mpsc::channel::<AgentMessage>(1000);

 // Receiving task (spawned)
 let config_clone = config.clone();
 tokio::spawn(async move {
 while let Ok((mut socket, addr)) = listener.accept().await {
 println!("[{}] Connection from {}", config_clone.id, addr);
 let tx_clone = tx.clone();
 tokio::spawn(async move {
 let mut buf = [0; 1024];
 loop {
 let n = match socket.read(&mut buf).await {
 Ok(n) if n == 0 => return, // Connection closed
 Ok(n) => n,
 Err(e) => {
 eprintln!("Failed to read from socket; err = {:?}", e);
 return;
 }
 };

 // Message parsing (simplified logic)
 let received_data = &buf[..n];
 // Deserialization would be performed here in reality
 println!("Received: {:?}", String::from_utf8_lossy(received_data));
 
 // ... (Business logic processing) ...
 }
 });
 }
 });

 // Example sending task (periodic heartbeat)
 tokio::spawn(async move {
 let mut interval = tokio::time::interval(tokio::time::Duration::from_secs(5));
 loop {
 interval.tick().await {
 let hb = AgentMessage {
 source: config.id.clone(),
 target: "broadcast".to_string(),
 payload: PayloadType::Control(ControlSignal::HeartBeat),
 };
 // Would actually write to a socket or send externally
 println!("[{}] Sending Heartbeat...", config.id);
 }
 }
 });

 Ok(())
}

This code demonstrates the basic framework for a ZeroClaw agent to asynchronously receive requests from other agents and periodically report its status. Since each connection is executed independently via tokio::spawn, thousands of concurrent connections can be handled efficiently.

Team Agent Communication and Protocol Design

Beyond simple 1:1 communication, ZeroClaw aims for team-level communication. This connects with the previously discussed “Team Agent Communication Architecture.”

Pub/Sub Pattern: Messages are delivered in bulk to a group of agents subscribed to a specific topic.
Peer-to-Peer (P2P): Minimizes latency by enabling direct communication between agents without going through a central server.

ZeroClaw’s protocol is encapsulated and transmitted over the TCP layer using JSON or binary formats (like MessagePack for performance-critical scenarios). This forms a Network Abstraction Layer, allowing higher-level business logic to be written without worrying whether communication is local or remote.

Conclusion: Towards Scalable Agent Systems

ZeroClaw is being designed as a true distributed system, going beyond a simple LLM wrapper. By combining Rust’s memory safety and zero-cost abstractions with tokio’s powerful asynchronous processing capabilities, we are building a stable and fast agent runtime.

In the next post, we will debug the flow of how an LLM makes decisions and performs actual actions through MCP tools on top of this communication architecture.

Reference Code and Resources

ZeroClaw GitHub Repository (preparing for open-source)
The Garbage Collection Handbook: The Art of Automatic Memory Management (2nd Ed) - A classic and authoritative text on memory management, recently mentioned in the news.

Thank you for reading!

Designing MCP Authentication Architecture for Zero-Touch OAuth Implementation

Fri, 19 Jun 2026 09:00:58 +0900

Recently, I encountered an interesting technological trend called ‘Zero-Touch OAuth for MCP’. During the integration of MCP (Model Context Protocol) with our ZeroClaw runtime and blog-api-server that we are developing, ensuring security without compromising user experience is an essential task. In this post, we will design a ‘Zero-Touch’ authentication flow that helps users connect to MCP clients without any complex separate configurations, and explore how to implement it in actual code.

Why Zero-Touch?

Traditional OAuth 2.0 flows often require users to obtain a ‘Client ID’ and ‘Client Secret’ and enter them into a configuration file. However, for general users or developers, this presents a significant barrier to entry. Zero-Touch OAuth aims for a flow where the client automatically attempts authentication through pre-registered metadata, and users simply need to click an ‘Allow’ button.

Architecture Design

We will configure blog-api-server as the MCP Provider and Claude Code or custom clients as MCP Consumers. The core idea is to build a Public Client environment that does not store Secrets by using the PKCE (Proof Key for Code Exchange) extension.

Core Components:

MCP Client (Consumer): An agent running in the user’s local environment.
Auth Server: The OAuth2 authentication server implemented within blog-api-server.
Resource Server: The actual blog API.

Implementation Step 1: Server Side (blog-api-server)

First, we need to add a simple authentication endpoint to the Rust-based blog-api-server. We will extend the architecture mentioned in the previous post, ’[blog-api-server] Adding Language Parameter to MCP Blog Client’, to make the Auth module independent.

Here, we will show the core logic: the Verification logic. This is the process of verifying the code_verifier received from the client.

// blog-api-server/src/auth/handler.rs
use axum::{extract::State, Json};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use base64::Engine as _;

#[derive(Deserialize)]
pub struct TokenRequest {
 pub code: String,
 pub code_verifier: String, // Random string generated by the client via PKCE
 pub redirect_uri: String,
}

#[derive(Serialize)]
pub struct TokenResponse {
 pub access_token: String,
 pub token_type: String,
 pub expires_in: u64,
}

pub async fn exchange_token(
 State(state): State<AppState>,
 Json(payload): Json<TokenRequest>,
) -> Result<Json<TokenResponse>, String> {
 // 1. Retrieve Authorization Code from DB
 let auth_record = state.db.get_auth_code(&payload.code)
 .await
 .map_err(|_| "Invalid code".to_string())?;

 // 2. PKCE Challenge Verification (Core Security Logic)
 let mut hasher = Sha256::new();
 hasher.update(payload.code_verifier.as_bytes());
 let hashed_verifier = hasher.finalize();
 let encoded_verifier = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(hashed_verifier);

 if encoded_verifier != auth_record.code_challenge {
 return Err("Code verifier mismatch".to_string());
 }

 // 3. Issue Access Token
 let access_token = generate_jwt(&state.secrets, &auth_record.user_id);

 Ok(Json(TokenResponse {
 access_token,
 token_type: "Bearer".to_string(),
 expires_in: 3600,
 }))
}

This code hashes the code_verifier sent by the client and checks if it matches the code_challenge generated when the initial authentication request was sent. This process is the core that makes ‘Zero-Touch’ secure.

Implementation Step 2: Client Side (MCP Client)

Now, the client can obtain a token without user intervention (or with minimal intervention). Let’s write an example MCP client using Python.

import hashlib
import base64
import requests
from urllib.parse import urlencode
import os # Import os module

# Zero-Touch Configuration (Hardcoded or Environment Variables)
CLIENT_ID = "zeroclaw-mcp-client"
AUTH_URL = "https://api.myblog.com/oauth/authorize"
TOKEN_URL = "https://api.myblog.com/oauth/token"
REDIRECT_URI = "http://localhost:3000/callback"

# Generate PKCE Code Verifier
random_bytes = os.urandom(32)
code_verifier = base64.urlsafe_b64encode(random_bytes).rstrip(b'=').decode('utf-8')

# Generate Code Challenge
challenge_digest = hashlib.sha256(code_verifier.encode('utf-8')).digest()
code_challenge = base64.urlsafe_b64encode(challenge_digest).rstrip(b'=').decode('utf-8')

def get_auth_url():
 params = {
 "response_type": "code",
 "client_id": CLIENT_ID,
 "redirect_uri": REDIRECT_URI,
 "scope": "mcp:read mcp:write",
 "code_challenge": code_challenge,
 "code_challenge_method": "S256"
 }
 return f"{AUTH_URL}?{urlencode(params)}"

def exchange_code_for_token(auth_code):
 data = {
 "grant_type": "authorization_code",
 "code": auth_code,
 "redirect_uri": REDIRECT_URI,
 "client_id": CLIENT_ID,
 "code_verifier": code_verifier # Sent to the server for verification
 }
 response = requests.post(TOKEN_URL, data=data)
 return response.json()

# Usage Example
# 1. User authenticates in the browser via get_auth_url() (first time)
# 2. Extract 'code' from the redirected query parameters
# 3. token = exchange_code_for_token(code)

Considerations for ZeroClaw Runtime Integration

As mentioned in our previous retrospective, ’[ZeroClaw] Q1 2026 Development Direction Meeting Minutes’, our agent runtime must prioritize security and scalability. If we integrate the OAuth flow implemented above into ZeroClaw’s Multi-Agent architecture, each agent can have an independent identity.

In particular, as discussed in ’[ZeroClaw] Multi-Agent Communication Protocol Design’, this Access Token can be used to securely access resources (APIs) of other agents during inter-agent communication, laying the foundation for secure access. This goes beyond simple blog automation and marks the first step towards a distributed system where agents trust and delegate tasks to each other.

Conclusion

Zero-Touch OAuth is an excellent approach that achieves both user convenience and security. We plan to start with small projects like blog-api-server and gradually evolve it into a core authentication module for ZeroClaw. The code above provides a basic framework, and for actual operational environments, logic such as state verification and refresh token rotation should be added.

In the next post, we will debug the ‘Handshake’ process of actually exchanging data with the MCP server using the tokens secured in this way.

Stop Using JWTs: The Practicality and Implementation of Session-Based Authentication

Wed, 17 Jun 2026 09:00:39 +0900

Stop Using JWTs: The Practicality and Implementation of Session-Based Authentication

Recently, the topic “Stop Using JWTs” has resurfaced as a hot potato in communities like Hacker News. When JWTs (JSON Web Tokens) first emerged, they were considered the standard for Microservice Architectures (MSA) thanks to the magic word “stateless.” However, in the reality of operating web services, we often fall into the trap of statelessness.

This article will explore why many developers are abandoning JWTs and returning to traditional session-based authentication (or database-based tokens), and how to implement it in practice.

The Sweet Trap of JWTs

The biggest advantage of JWTs is that they don’t require storing user state on the server. Since all information is contained within the token itself, only the signature needs to be verified without a database lookup. Theoretically, this offers excellent scalability.

However, this “advantage” quickly becomes a “disadvantage.”

1. Revocation Problem

Once issued, JWTs are valid until their expiration date. What if a user logs out, or an administrator needs to force them to log out?

Option 1: Let the token remain valid until it expires, as it cannot be immediately revoked. (Impossible as a safety measure)
Option 2: Introduce a blacklist. (Ultimately requires a DB/Redis lookup -> loss of stateless advantage)

The moment you introduce a blacklist, you need to check it for every JWT verification, thus losing the advantage of “without database lookup.”

2. Token Size and Overhead

JWTs, including headers, payloads, and signatures, are significantly larger than typical session IDs. The more claims (Roles, permissions, etc.) you include per user, the larger the token becomes. This wastes network bandwidth with every request.

Returning to Session-Based Authentication

In conclusion, it’s better to accept the fact that “state is managed on the server-side.” Using an in-memory database like Redis allows for very fast session management, and immediate logout or forced logout is possible.

In this section, we will build a simple yet robust session-based authentication system using Go and Redis.

Prerequisites

We assume Redis is installed and running locally.

Implementation Code (Go)

The following code is a simple HTTP server that provides /login, /protected, and /logout endpoints.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/go-redis/redis/v8"
	"github.com/google/uuid"
	"github.com/gorilla/mux"
	"golang.org/x/crypto/bcrypt"
)

var ctx = context.Background()
var rdb *redis.Client

// User information (in a real application, this would be fetched from a DB)
var userDB = map[string]string{
	"user1": "$2a$14$ajq8Q7fbnFR0nXf8bA7HcuiJ/6V.Z.yzX1lYh8g8h5x6z7x8x9x0x", // password: "password"
}

type Credentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

func main() {
	// Initialize Redis client
	rdb = redis.NewClient(&redis.Options{
		Addr: "localhost:6379",
		Password: "", // no password set
		DB: 0, // use default DB
	})

	r := mux.NewRouter()
	r.HandleFunc("/login", loginHandler).Methods("POST")
	r.HandleFunc("/protected", authMiddleware(protectedHandler)).Methods("GET")
	r.HandleFunc("/logout", authMiddleware(logoutHandler)).Methods("POST")

	fmt.Println("Server starting on port 8000...")
	log.Fatal(http.ListenAndServe(":8000", r))
}

// Login handler
func loginHandler(w http.ResponseWriter, r *http.Request) {
	var creds Credentials
	err := json.NewDecoder(r.Body).Decode(&creds)
	if err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}

	// Check if user exists and verify password
	hashedPassword, exists := userDB[creds.Username]
	if !exists {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}

	if err := bcrypt.CompareHashAndPassword([]byte(hashedPassword), []byte(creds.Password)); err != nil {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}

	// Generate a new session ID
	sessionToken := uuid.NewString()

	// Store session in Redis (expires in 24 hours)
	err = rdb.Set(ctx, sessionToken, creds.Username, 24*time.Hour).Err()
	if err != nil {
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	// Set cookie (HttpOnly, Secure recommended)
	http.SetCookie(w, &http.Cookie{
		Name: "session_token",
		Value: sessionToken,
		Expires: time.Now().Add(24 * time.Hour),
		HttpOnly: true,
		Secure: true, // Only in HTTPS environment
		Path: "/",
		SameSite: http.SameSiteStrictMode,
	})

	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(map[string]string{"message": "Login successful"})
}

// Authentication middleware
func authMiddleware(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		c, err := r.Cookie("session_token")
		if err != nil {
			if err == http.ErrNoCookie {
				w.WriteHeader(http.StatusUnauthorized)
				return
			}
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		sessionToken := c.Value

		// Retrieve session from Redis
		response, err := rdb.Get(ctx, sessionToken).Result()
		if err != nil {
			if err == redis.Nil {
				w.WriteHeader(http.StatusUnauthorized)
				return
			}
			w.WriteHeader(http.StatusInternalServerError)
			return
		}

		// Optionally, store username in request context
		// r = r.WithContext(context.WithValue(r.Context(), "username", response))

		next(w, r)
	}
}

// Protected resource handler
func protectedHandler(w http.ResponseWriter, r *http.Request) {
	c, _ := r.Cookie("session_token")
	username, _ := rdb.Get(ctx, c.Value).Result()
	json.NewEncoder(w).Encode(map[string]string{"message": fmt.Sprintf("Hello %s, you accessed a protected route!", username)})
}

// Logout handler
func logoutHandler(w http.ResponseWriter, r *http.Request) {
	c, _ := r.Cookie("session_token")
	sessionToken := c.Value

	// Delete session from Redis (immediate revocation)
	rdb.Del(ctx, sessionToken)

	// Invalidate cookie
	http.SetCookie(w, &http.Cookie{
		Name: "session_token",
		Value: "",
		Expires: time.Now().Add(-1 * time.Hour),
		HttpOnly: true,
		Path: "/",
	})

	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(map[string]string{"message": "Logout successful"})
}

Code Explanation and Application Tips

Secure Cookie Usage: HttpOnly and Secure flags are used to prevent XSS (Cross-Site Scripting) and Man-in-the-Middle attacks. It is safer to encourage the client (browser) to store tokens in cookies rather than LocalStorage.
Leveraging Redis: Redis, being single-threaded, offers fast atomic operations and is ideal for use as a session store. Even if Redis goes down, the data isn’t permanently needed (as users can re-login), so it’s configured for fast response times.
Immediate Logout: The logoutHandler includes code to delete the key from Redis (rdb.Del). This perfectly solves JWT’s biggest weakness: “inability to log out.” The moment the key is deleted, that token (session ID) is no longer valid.

Conclusion: What Should You Choose?

When JWTs are good: When the system you are building consists of truly independent microservices, user authentication is needed for inter-service communication, and logout/reissue logic is not critical for simple API communications.
When Sessions/Cookies are good: For general web services, SaaS, and most cases where user security (immediate action required for account termination) is important.

The phrase “Stop Using JWTs” is not because JWT is a bad technology, but because it is misused and applied inappropriately for the situation. Adding complex JWT libraries and blacklist logic to a problem that can be solved with a simple session store can be an act of accumulating technical debt.

We recommend applying the Go code example above to your project and experiencing the ease of management and security firsthand.

Building a High-Performance Agent Runtime with Rust: An In-depth Analysis of the ZeroClaw Architecture

Tue, 16 Jun 2026 09:00:39 +0900

Building a High-Performance Agent Runtime with Rust: An In-depth Analysis of the ZeroClaw Architecture

Recently, we designed and discussed the future direction of a high-performance Rust-based agent runtime through the ZeroClaw project. Moving beyond the limitations of existing Python-based LLM applications or single-server architectures, building a multi-agent system by leveraging Rust’s inherent safety and excellent parallelism has been a technically challenging endeavor. In this article, we will explore ZeroClaw’s core architectural design, communication protocols, and the specific characteristics of Rust that need consideration during actual implementation.

1. Why Rust? (Safe Concurrency)

The core of a multi-agent system is concurrency. Numerous agents must run simultaneously, communicating with each other and sharing states. Python’s GIL (Global Interpreter Lock) hinders true parallel processing, and Go’s (Goroutine) garbage collection (GC) can sometimes lead to unpredictable latency. In contrast, Rust offers ‘Zero-cost Abstraction’ and ‘Fearless Concurrency’.

In the ZeroClaw project, message passing between agents is implemented using tokio::sync::mpsc channels, enabling lock-free asynchronous communication. This allows for maximum CPU resource utilization while completely eliminating data races at compile time.

2. Communication Protocol Design: File-Based vs. Memory-Based

The most debated aspect during the architectural design phase was the ‘method of communication between agents’. Initially, we considered a [Multi-Agent] file-based architecture design. This approach, treating the file system as shared memory, offered the advantages of easy implementation and straightforward debugging. However, for ZeroClaw, which aims for a high-performance runtime, I/O bottlenecks were a critical concern.

Consequently, we adopted a memory-based event bus architecture.

2.1. Implementing the Request-Response Pattern

Since simple fire-and-forget was insufficient and task delegation between agents was necessary, we had to implement a Request-Response pattern. For this, we actively utilized Rust’s type system.

use tokio::sync::{mpsc, oneshot};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

// Define messages to be exchanged between agents
#[derive(Debug, Serialize, Deserialize)]
enum AgentMessage {
 TaskRequest { id: String, payload: String },
 TaskResponse { id: String, result: String },
}

// Agent actor struct
struct AgentActor {
 id: String,
 receiver: mpsc::Receiver<AgentMessage>,
 // Map of senders to send messages to other agents
 peers: HashMap<String, mpsc::Sender<AgentMessage>>,
}

impl AgentActor {
 fn new(id: String, receiver: mpsc::Receiver<AgentMessage>) -> Self {
 Self {
 id,
 receiver,
 peers: HashMap::new(),
 }
 }

 // Register a peer
 fn register_peer(&mut self, id: String, sender: mpsc::Sender<AgentMessage>) {
 self.peers.insert(id, sender);
 }

 // Execute message loop
 async fn run(mut self) {
 println!("[{}] Agent started", self.id);
 while let Some(msg) = self.receiver.recv().await {
 match msg {
 AgentMessage::TaskRequest { id, payload } => {
 println!("[{}] Received Task {}: {}", self.id, id, payload);
 // Perform actual task (LLM call, etc.)
 let result = format!("Processed '{}' by {}", payload, self.id);
 
 // (In actual implementation, logic to send a response back to the requester is needed)
 }
 _ => {}
 }
 }
 }
}

This code provides a minimal skeleton for ZeroClaw’s communication layer. Each agent runs as an independent task (tokio::spawn) and exchanges messages through channels.

3. Integration with MCP: The Bridge Pattern

As discussed in the [Discord Decision MCP] architectural design document, the agent runtime needs to communicate with the external world. We adopted MCP (Model Context Protocol) as a standard interface, designing it so that agents within ZeroClaw can interact with platforms like Discord or blog APIs.

A crucial point here is bridging the gap between Rust’s powerful type system and external JSON-based protocols. We leverage serde_json to deserialize MCP messages into internal structs and pass them between agents while maintaining type safety.

// Struct for calling MCP tools
#[derive(Serialize, Deserialize)]
struct MCPToolCall {
 tool_name: String,
 arguments: HashMap<String, serde_json::Value>,
}

// Example logic for handling an MCP call detected by an agent
fn handle_mcp_message(msg: &str) -> Result<MCPToolCall, Box<dyn std::error::Error>> {
 let call: MCPToolCall = serde_json::from_str(msg)?;
 // Type verification is completed internally within Rust
 Ok(call)
}

4. Roadmap for H1 2026: Directions for Advancement

As mentioned in the [ZeroClaw] H1 2026 Development Direction Meeting Minutes, we are focusing on optimization beyond simple implementation.

Dynamic Agent Scaling: Currently, agents are created with static configurations. We plan to introduce auto-scaling logic that dynamically increases and decreases agent instances using tokio::task::spawn based on load.
Back-pressure Handling: To prevent channels from overflowing when the processing speed is faster than LLM API call rates, we need to meticulously adjust the buffer strategies of tokio::sync::mpsc.
Observability: Moving beyond simple logging, we need to build a structure that allows for distributed tracing of message flows between agents using the tracing crate.

Conclusion

ZeroClaw is not just another agent framework. It aims to be an infrastructure for operating large-scale LLM applications, built on Rust’s safety and performance. The insights gained from analyzing the codebase architecture are focused on ‘how to manage complexity’, which clarifies our future development direction. For any developer requiring a high-performance runtime, ZeroClaw will be a powerful option.

Designing and Implementing a Communication Protocol for MCP-based Multi-Agent Systems in Rust

Mon, 15 Jun 2026 09:00:53 +0900

Recently, while working on the ‘ZeroClaw’ project and MCP (Model Context Protocol), I’ve keenly felt the necessity of a Multi-Agent System that goes beyond a single agent. To build a structure where agents can exchange meaningful data and collaborate, rather than simply sending prompts to an LLM, a robust Communication Protocol is essential.

In this post, we’ll explore the design process for multi-agent communication based on the MCP architecture and how to implement it on ZeroClaw (Rust), a high-performance runtime.

1. Problem Definition: Why a Communication Protocol?

In previous implementations like [blog-api-server] or [Discord MCP], the ‘Request-Response’ structure was primarily followed. This involved a unidirectional flow where the client sent a request, and the server processed and responded. However, in a multi-agent environment, this structure alone is insufficient for the following reasons:

Asynchrony: If Agent A delegates a task to Agent B and Agent A stops execution until B completes, the overall system throughput decreases.
Event-Driven Interaction: Some agents need to monitor system state changes (e.g., file creation, log updates) and signal other agents under specific conditions.
Reliability: Messages must not be lost in situations of network instability or temporary agent failures.

2. Protocol Design: Request, Task, Completion

To address these issues, we designed a Task-Based Messaging Protocol. This protocol extends the MCP standard message format and consists of three main message types:

TaskRequest: Initiates a task. Used when Agent A delegates a specific task to Agent B.
TaskUpdate: Reports progress. Conveys intermediate results for long-running tasks.
TaskResult: Final outcome. Returns data along with a success or failure status.

3. Implementing the ZeroClaw Communication Layer in Rust

ZeroClaw implements this protocol in a type-safe manner using Rust’s powerful type system and its asynchronous runtime (Tokio). Below is a simplified message definition and handler structure.

3.1. Message Definition (Based on JSON-RPC)

MCP is fundamentally based on JSON-RPC 2.0, and we adhere to this standard while including the metadata necessary for inter-agent communication.

// src/protocol/message.rs

use serde::{Deserialize, Serialize};
use uuid::Uuid;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentMessage {
 pub id: String, // Unique message ID
 pub sender: String, // Sender agent ID
 pub target: String, // Recipient agent ID
 pub timestamp: i64, // Timestamp
 pub payload: Payload, // Actual data
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum Payload {
 #[serde(rename = "task/request")]
 TaskRequest {
 task_id: Uuid,
 description: String,
 context: serde_json::Value,
 },
 
 #[serde(rename = "task/result")]
 TaskResult {
 task_id: Uuid,
 status: TaskStatus,
 data: Option<serde_json::Value>,
 },
 
 #[serde(rename = "system/ping")]
 SystemPing,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum TaskStatus {
 Success,
 Failure(String), // Reason for failure
 Pending,
}

3.2. Agent Runtime Structure

In ZeroClaw, each agent runs as an independent Tokio task. Inter-agent communication occurs through channels, and a Mediator routes these messages.

// src/runtime/agent.rs

use tokio::sync::mpsc;
use crate::protocol::message::{AgentMessage, Payload};

pub struct Agent {
 id: String,
 tx: mpsc::Sender<AgentMessage>, // Sender for outgoing messages
 rx: mpsc::Receiver<AgentMessage>, // Receiver for incoming messages
}

impl Agent {
 pub fn new(id: String) -> Self {
 let (tx, rx) = mpsc::channel(100);
 Self { id, tx, rx }
 }

 // The agent's main execution loop
 pub async fn run(mut self) {
 println!("[{}] Agent started", self.id);
 while let Some(msg) = self.rx.recv().await {
 if let Err(e) = self.handle_message(msg).await {
 eprintln!("[{}] Error handling message: {:?}", self.id, e);
 }
 }
 }

 async fn handle_message(&self, msg: AgentMessage) -> Result<(), Box<dyn std::error::Error>> {
 match msg.payload {
 Payload::SystemPing => {
 // Logic to respond to ping with pong
 // In a real environment, this would use the client's tx to send a response
 println!("[{}] Received Ping from {}", self.id, msg.sender);
 }
 Payload::TaskRequest { task_id, description, context } => {
 println!("[{}] Received Task {}: {}", self.id, task_id, description);
 // LLM calls or tool execution logic would go here.
 
 // Example: Result return logic (simulated)
 // self.send_result(task_id, ...).await;
 }
 _ => {
 println!("[{}] Received unhandled message type", self.id);
 }
 }
 Ok(())
 }
}

4. Conclusion and Next Steps

Through the structured communication layer described above, we achieve an architecture capable of task-unit collaboration, moving beyond simple text generation. The ‘high-performance agent runtime’ goal for the [ZeroClaw] project in the first half of 2026 will be realized by integrating LLM inference logic on this solid foundation.

The next post will delve into the implementation details of a ‘Planner’ agent that uses tools by calling an LLM over this communication protocol.

References

[ZeroClaw] Multi-Agent Architecture Design Proposal
[Claude Code] Team Agent Communication Architecture
Rust Tokio Documentation

[ZeroClaw] Rust Channel-Based IPC Design for Asynchronous Agent Runtime

Thu, 11 Jun 2026 09:00:42 +0900

[ZeroClaw] Rust Channel-Based IPC Design for Asynchronous Agent Runtime

Hello. Recently, while enhancing the ‘Multi-Agent Architecture’, the core of the ZeroClaw project, I would like to share my experience building a high-performance asynchronous communication (IPC, Inter-Process Communication) environment that goes beyond simple message passing.

The previous synchronous communication method increased coupling between agents and became a bottleneck (Single Point of Failure) that could halt the entire system due to the failure of one agent. To address this, we designed an event-driven, loosely coupled architecture using Rust’s powerful concurrency feature, the tokio runtime, and MPSC (Multi-Producer, Single-Consumer) channels.

In this post, we will examine how channels were designed and implemented to maximize the efficiency of the agent runtime, along with actual code.

1. Problems with the Existing Architecture and the Need for Asynchronous Design

Until now, ZeroClaw agents primarily used the synchronous RPC pattern, requesting messages and waiting for responses. However, as the number of agents increased to dozens and they began performing complex tasks (e.g., analyzing file-based architectures, processing large-scale logs), the following problems arose:

Blocking Issue: While Agent A waits for a response from Agent B, Agent A cannot perform other tasks.
Complex Error Propagation: When a specific agent crashed or timed out, it was complicated to propagate the error to agents higher up the call chain.

To solve this, we adopted an asynchronous pattern: “An agent sends a message and immediately performs other tasks. The processed result is received as an event.”

2. Event Loop Structure Using Rust’s `tokio::sync::mpsc`

The MPSC channel provided by Rust’s tokio crate ensures high throughput and low latency, making it ideal for agent runtimes. Each agent has its own Task (unit of work), which executes independently via tokio::spawn.

Core Design Points

Message Bus: Each agent holds a sender (tx) and a receiver (rx).
Event Loop: The receiver (rx) runs in an infinite loop (loop), asynchronously waiting (recv()) until a message arrives.

3. Practical Code: A Concrete Implementation Example

Now, let’s write code that demonstrates how agents communicate within the ZeroClaw runtime.

Step 1: Define the Message Protocol

First, we need to define the data structures that will be exchanged between agents. It is recommended to use an Enum to manage message types safely.

// Cargo.toml dependencies
// [dependencies]
// tokio = { version = "1", features = ["full"] }
// serde = { version = "1", features = ["derive"] }

use tokio::sync::mpsc;
use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
enum AgentMessage {
 TaskAssigned { task_id: String, description: String },
 TaskCompleted { task_id: String, result: String },
 StatusCheck,
}

Step 2: Implement Agent Struct and Runner

Each agent has a unique ID and a receiver (rx). The run method is the core function that manages the agent’s lifecycle.

struct Agent {
 id: String,
 rx: mpsc::Receiver<AgentMessage>,
}

impl Agent {
 fn new(id: String, rx: mpsc::Receiver<AgentMessage>) -> Self {
 Self { id, rx }
 }

 async fn run(mut self) {
 println!("[{}] Agent started. Listening for messages...", self.id);
 
 // Asynchronously wait for message reception
 while let Some(msg) = self.rx.recv().await {
 match msg {
 AgentMessage::TaskAssigned { task_id, description } => {
 println!("[{}] Received task: {} - {}", self.id, task_id, description);
 // Actual logic processing (e.g., file analysis, external API calls)
 // Here, for example, we assume it takes 1 second and then sends a completion message.
 }
 AgentMessage::StatusCheck => {
 println!("[{}] Status: Active", self.id);
 }
 _ => {}
 }
 }
 println!("[{}] Agent shutting down.", self.id);
 }
}

Step 3: Main Runtime and Channel Connection

In the main function, we create multiple agents, connect the channels, and then execute them in parallel using tokio::spawn.

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 // 1. Create channel (capacity 32)
 let (tx, rx) = mpsc::channel::<AgentMessage>(32);

 // 2. Create and run agent (separated into asynchronous tasks)
 let agent_handle = {
 let agent = Agent::new("Agent-A".to_string(), rx);
 tokio::spawn(async move {
 agent.run().await;
 })
 };

 // 3. Send messages from the main runtime
 // Other agents or API servers can use this tx to send messages.
 
 // Assign task
 let _ = tx.send(AgentMessage::TaskAssigned {
 task_id: "T-101".to_string(),
 description: "Analyze server logs".to_string(),
 }).await;

 // Check status
 let _ = tx.send(AgentMessage::StatusCheck).await;

 // 4. Wait for the agent to complete its task (in a real environment, it would continue running)
 drop(tx); // Sender drops -> channel closes -> agent loop termination condition met
 
 agent_handle.await?;
 
 Ok(())
}

4. ZeroClaw Project Application Effects

As a result of applying the structure above to the ZeroClaw runtime, we achieved the following benefits:

Improved Parallel Processing Performance: Since agents run within their own tokio tasks, we were able to efficiently utilize CPU cores.
Reduced Coupling: The main logic doesn’t need to know the internal implementation of a specific agent; it simply calls tx.send.
Graceful Shutdown: By dropping tx, the channel closes, and the agent detects that no more messages will arrive, naturally exiting the while let loop and shutting down.

Conclusion

Rust’s ownership system and tokio’s asynchronous abstractions become powerful weapons in building multi-agent systems. In the next post, we will cover how these agents persist state when combined with a file-based architecture.

The development of ZeroClaw’s high-performance agent runtime continues.

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

Wed, 10 Jun 2026 09:00:57 +0900

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

As evident in the recent article “Grit: Rewriting Git in Rust with Agents,” the Rust language is being re-evaluated for its value as a runtime for agent systems. Our team’s ZeroClaw runtime is also under development with high performance and safety as its goals, and with this in mind, we are increasingly focusing on how to efficiently build an MCP (Model Context Protocol) server.

Instead of traditional heavy Python-based servers or complex Node.js architectures, we propose a lightweight MCP server structure that leverages Rust’s concurrency and low-latency capabilities. In this article, we will write a Rust-based MCP server example that can be immediately applied in practice, while capitalizing on the advantages of the ZeroClaw architecture.

1. Combining ZeroClaw Architecture and MCP

The core of the ZeroClaw project lies in its file-based architectural design and the efficient implementation of its multi-agent communication protocol. The most crucial aspects when building an MCP server are reducing the overhead of data serialization/deserialization (Serde) and asynchronous request handling.

By utilizing Rust’s tokio runtime and serde_json, we can handle JSON-based MCP protocols with an overhead in the nanosecond range. This is a critical element, especially for large-scale log processing or monitoring systems (as experienced with [blog-api-server]).

2. Core Structure: Asynchronous Request Routing

We will build the skeleton of an MCP server using only the standard library and a few essential crates, without complex dependencies. This structure follows ZeroClaw’s agent-to-agent communication pattern and ensures safety in a multi-threaded environment, not just a single-threaded one.

2.1. Cargo.toml Configuration

First, add project dependencies.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
hyper = { version = "0.14", features = ["full"] }

2.2. Defining MCP Message Structure

MCP fundamentally has a structure similar to JSON-RPC. We actively utilize Rust’s type system to ensure data integrity during agent-to-agent communication.

// src/types.rs
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPRequest {
 pub jsonrpc: String, // Always "2.0"
 pub id: Option<String>,
 pub method: String,
 pub params: Option<serde_json::Value>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPResponse {
 pub jsonrpc: String,
 pub id: Option<String>,
 pub result: Option<serde_json::Value>,
 pub error: Option<MCPError>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPError {
 pub code: i32,
 pub message: String,
}

3. Implementing a Lightweight Request Handler

In line with ZeroClaw’s philosophy, we will remove unnecessary abstraction layers and write intuitive handlers. The following code demonstrates the flow of parsing incoming requests, performing appropriate processing based on the method name, and returning a response.

// src/main.rs
use hyper::{Body, Request, Response, Server, StatusCode};
use hyper::service::{make_service_fn, service_fn};
use std::convert::Infallible;
use types::{MCPRequest, MCPResponse};

async fn handle_mcp_request(req: MCPRequest) -> MCPResponse {
 match req.method.as_str() {
 "tools/list" => {
 // Example of returning a list of tools
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(serde_json::json!({
 "tools": [
 { "name": "get_weather", "description": "Get current weather" },
 { "name": "calculate", "description": "Perform math operations" }
 ]
 })),
 error: None,
 }
 },
 "tools/call" => {
 // Actual tool execution logic (calling ZeroClaw Agent, etc.)
 // Parameter validation logic goes here.
 println!("Agent executing with params: {:?}", req.params);
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(serde_json::json!({"status": "success"})),
 error: None,
 }
 },
 _ => {
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: None,
 error: Some(types::MCPError {
 code: -32601,
 message: "Method not found".to_string(),
 }),
 }
 }
 }
}

async fn http_handler(req: Request<Body>) -> Result<Response<Body>, Infallible> {
 let whole_body = match hyper::body::to_bytes(req.into_body()).await {
 Ok(bytes) => bytes,
 Err(e) => {
 eprintln!("Error reading body: {}", e);
 return Ok(Response::builder()
 .status(StatusCode::INTERNAL_SERVER_ERROR)
 .body(Body::from("Internal Server Error"))
 .unwrap());
 }
 };

 // JSON Parsing
 let mcp_req: MCPRequest = match serde_json::from_slice(&whole_body) {
 Ok(req) => req,
 Err(_) => {
 return Ok(Response::builder()
 .status(StatusCode::BAD_REQUEST)
 .body(Body::from("Invalid JSON"))
 .unwrap());
 }
 };

 // MCP Logic Processing
 let mcp_res = handle_mcp_request(mcp_req).await;
 
 // Response Conversion
 let json_body = match serde_json::to_string(&mcp_res) {
 Ok(json) => json,
 Err(_) => "{}".to_string(),
 };

 Ok(Response::new(Body::from(json_body)))
}

#[tokio::main]
async fn main() {
 let make_svc = make_service_fn(|_conn| {
 async { Ok::<_, Infallible>(service_fn(http_handler)) }
 });

 let addr = ([127, 0 0, 1], 3000).into();
 let server = Server::bind(&addr).serve(make_svc);

 println!("MCP Server listening on http://{}", addr);

 if let Err(e) = server.await {
 eprintln!("Server error: {}", e);
 }
}

4. Advanced Optimization: ZeroClaw Integration

The code above is a basic HTTP server. To unleash the true power of ZeroClaw, this server needs to be integrated as a task within the agent runtime.

Channel-based Communication: Instead of directly handling HTTP requests, send requests through a tokio::sync::mpsc channel to the internal agent queue. This aligns with ZeroClaw’s asynchronous message passing structure.
Stealable Work Queue: Implement a work queue to allow agents to efficiently distribute tasks in a multi-core environment.

5. Conclusion

By writing an MCP server in Rust, you can fully leverage the benefits of high-performance runtimes like ZeroClaw. The key is not just changing the language, but designing an architecture that minimizes overhead in agent-to-agent communication. We encourage you to build upon the code provided and add your project-specific agent logic.

Note: This code focuses on practicality by simplifying error handling and logging, based on the experience gained from improving logging in blog-api-server.

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Tue, 09 Jun 2026 09:00:48 +0900

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Recently, Model Context Protocol (MCP) has become a standard interface in the AI agent ecosystem. When building an MCP server in high-performance runtime environments like our team’s ZeroClaw project, Rust’s safety and speed are essential. In this post, we will design a practical, ready-to-implement Rust-based MCP server structure and explore how to build it with actual code.

1. Core Requirements of an MCP Server

To allow AI models to access data, an MCP server must perform the following three core functions:

Resource Discovery: Provide a list of data (files, APIs, etc.) that the model can use.
Resource Access: Efficiently return the actual content of requested data.
Tool Execution: Perform actions within the system based on the model’s instructions.

Rust is ideal for MCP servers handling large-scale requests, especially due to its Zero-cost abstractions and robust asynchronous runtime (tokio).

2. Architecture Design: ZeroClaw Style

Beyond simple RPC calls, we adopt an event-driven architecture for scalability. The structure is as follows:

Transport Layer: Sending and receiving messages via stdio or WebSocket (JSON-RPC 2.0)
Handler Layer: Layer for routing and validating requests
Core Logic: Actual business logic (file system access, DB queries, etc.)

3. Practical Code Examples

We will write a simple MCP server based on stdio (standard input/output), the most common transport. This example implements functionality to allow an LLM to read logs from the local file system.

3.1. Dependency Setup (`Cargo.toml`)

We add crates for serialization and asynchronous processing to leverage Rust’s ecosystem.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
async-trait = "0.1"

3.2. Handler Trait Definition

Following the MCP standard, we define a common interface for handling Tool and Resource. This makes it easier to integrate with the ZeroClaw runtime later.

use serde_json::Value;
use async_trait::async_trait;

#[async_trait]
pub trait McpHandler {
 async fn handle(&self, params: Value) -> Result<Value, String>;
 fn name(&self) -> &str;
}

3.3. Implementing the Log Reading Tool

Now, we implement the logic to actually read files within the server and provide them to the AI model.

use std::fs;
use std::path::Path;

pub struct LogReaderTool;

#[async_trait]
impl McpHandler for LogReaderTool {
 fn name(&self) -> &str {
 "read_logs"
 }

 async fn handle(&self, params: Value) -> Result<Value, String> {
 // 1. Parameter validation and extraction
 let file_path = params.get("path")
 .and_then(|v| v.as_str())
 .ok_or("Missing 'path' parameter".to_string())?;

 // 2. Safeguard: Prevent path traversal (Sandboxing)
 // In a production environment, chroot or a dedicated virtual directory should be used.
 if !file_path.ends_with(".log") {
 return Err("Only .log files are allowed".into());
 }

 // 3. File system access (wrapping synchronous I/O in an asynchronous context)
 let content = fs::read_to_string(file_path)
 .map_err(|e| format!("Failed to read file: {}", e))?;

 // 4. Result formatting
 Ok(serde_json::json!({
 "status": "success",
 "content": content,
 "lines": content.lines().count()
 }))
 }
}

3.4. Main Loop and JSON-RPC Server

This is the main loop responsible for communication with the LLM. It reads JSON-RPC requests from standard input and outputs the processing results to standard output.

use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::io::{AsyncWriteExt, BufWriter};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 let stdin = tokio::io::stdin();
 let stdout = tokio::io::stdout();
 let mut reader = BufReader::new(stdin).lines();
 let mut writer = BufWriter::new(stdout);

 let tool = Arc::new(LogReaderTool);

 // Process requests as they arrive from the LLM or host
 while let Ok(Some(line)) = reader.next_line().await {
 if line.trim().is_empty() { continue; }

 if let Ok(json_req) = serde_json::from_str::<Value>(&line) {
 let method = json_req.get("method").and_then(|m| m.as_str()).unwrap_or("");
 let id = json_req.get("id");

 if method == "tools/call" || method == "tools/invoke" {
 let params = json_req.get("params").cloned().unwrap_or(Value::Null);
 
 // Execute business logic
 let result = tool.handle(params).await;
 
 let response = match result {
 Ok(data) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "result": data
 }),
 Err(e) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "error": { "code": -32000, "message": e }
 })
 };
 
 writer.write_all(response.to_string().as_bytes()).await?;
 writer.write_all(b"\n").await?;
 writer.flush().await?;
 }
 }
 }
 Ok(())
}

4. Optimization and Deployment Considerations

The code above provides a basic framework, but for production environments like ZeroClaw, consider the following:

Concrete Error Types: Use specific thiserror or anyhow-based error types instead of String to facilitate debugging.
Security Sandboxing: Use a virtual file system (VFS) library instead of std::fs to prevent agents from accessing the entire system.
Graceful Shutdown: Utilize tokio’s signal module to handle interrupt signals (SIGTERM) and safely terminate ongoing file operations.

5. Conclusion

Rust is the ideal language for building reliable MCP servers due to its type safety and memory management capabilities. Based on the code above, by integrating with a blog-api-server or monitoring system, you can build a fully automated cycle where AI models directly analyze system logs and suggest patches.

In the next post, we will cover how to agentize this MCP server on the ZeroClaw runtime and communicate with other services.

pg_durable Analysis: Implementing Durable Function Execution with Rust

Sat, 06 Jun 2026 09:00:49 +0900

Recently open-sourced by Microsoft, pg_durable is an experimental project that enables ‘Durable’ function execution directly within the database. In traditional microservice architectures, business logic often resides in the application layer, with the database primarily serving as a state storage. However, pg_durable proposes an approach that integrates logic and data in close proximity, minimizing external system failures or network costs.

In this article, we will analyze the core mechanisms of pg_durable and explore how to implement a similar pattern using Rust and PostgreSQL.

Core Mechanisms of pg_durable

The most significant feature of pg_durable is that it stores the function’s state and execution flow itself as database records. In typical applications, if an HTTP request fails, the in-memory context disappears. However, pg_durable records the input and current step of the function to be executed in a table.

This approach offers the following benefits:

Auto-Recovery: Even if a server crashes, ’tasks to be executed’ remain in the database, allowing for continued execution after the server restarts.
Exactly-Once Semantics: By leveraging database transactions, state updates and logic execution can be handled atomically.

Implementing a Database Trigger-Based Worker with Rust

While the internal implementation of pg_durable is complex, we can simply replicate this pattern using Rust and PostgreSQL’s LISTEN/NOTIFY functionality. This approach utilizes the database as a ‘message broker’ while saving on separate infrastructure costs.

1. Database Schema Design

First, we create a table to store jobs.

CREATE TABLE durable_jobs (
 id SERIAL PRIMARY KEY,
 status TEXT NOT NULL, -- 'pending', 'running', 'completed'
 payload JSONB NOT NULL,
 created_at TIMESTAMP DEFAULT NOW()
);

2. Rust Worker Implementation (Using sqlx)

We will use Rust’s asynchronous runtime and sqlx to write a worker that detects and processes new jobs as they enter the database.

# Cargo.toml
[dependencies]
tokio = { version = "1", features = ["full"] }
sqlx = { version = "0.7", features = ["runtime-tokio", "postgres", "json"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Now, let’s implement the worker in Rust code.

use sqlx::{PgPool, Listener};
use serde::{Deserialize, Serialize};
use tokio::time::{sleep, Duration};

#[derive(Debug, Serialize, Deserialize)]
struct JobPayload {
 user_id: i32,
 action: String,
}

#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
 // Create a database connection pool
 let pool = PgPool::connect("postgresql://user:password@localhost/mydb").await?;
 
 // Listener to detect database changes (using pg_notify)
 let mut listener = pool.acquire().await?.listen("job_channel");

 println!("Worker started, waiting for jobs...");

 loop {
 // Wait for notifications
 let notification = listener.recv().await?;
 println!("Received notification: {}", notification.payload);

 // Upon receiving a notification, attempt to process the actual job
 process_jobs(&pool).await?;
 }
}

async fn process_jobs(pool: &PgPool) -> Result<(), sqlx::Error> {
 // Within a transaction, fetch a 'pending' job and change its status to 'running' (Locking)
 let mut tx = pool.begin().await?;
 
 let job_opt = sqlx::query_as::<_, (i32, JobPayload)>(
 r#"
 UPDATE durable_jobs 
 SET status = 'running' 
 WHERE id = (
 SELECT id FROM durable_jobs 
 WHERE status = 'pending' 
 FOR UPDATE SKIP LOCKED 
 LIMIT 1
 )
 RETURNING id, payload
 "#
 )
 .fetch_optional(&mut *tx)
 .await?;

 if let Some((id, payload)) = job_opt {
 println!("Processing job {}: {:?}", id, payload);
 
 // Execute business logic (e.g., external API calls, etc.)
 // In a real environment, heavy tasks would be performed here.
 let result = simulate_heavy_task(&payload).await;

 match result {
 Ok(_) => {
 // On success, update status to 'completed'
 sqlx::query("UPDATE durable_jobs SET status = 'completed' WHERE id = $1")
 .bind(id)
 .execute(&mut *tx)
 .await?;
 }
 Err(e) => {
 // On failure, leave status as 'failed' or add retry logic
 eprintln!("Job {} failed: {}", id, e);
 sqlx::query("UPDATE durable_jobs SET status = 'failed' WHERE id = $1")
 .bind(id)
 .execute(&mut *tx)
 .await?;
 }
 }
 
 tx.commit().await?;
 }
 
 Ok(())
}

async fn simulate_heavy_task(payload: &JobPayload) -> Result<(), Box<dyn std::error::Error>> {
 // Example: Wait for 2 seconds
 sleep(Duration::from_secs(2)).await;
 println!("Task executed for user {}", payload.user_id);
 Ok(())
}

3. Job Registration Trigger

In practice, you can automate this by sending an INSERT query from the application level and then issuing a NOTIFY, or by using a trigger.

-- Example of creating a trigger function and trigger
CREATE OR REPLACE FUNCTION notify_job() RETURNS TRIGGER AS $$
BEGIN
 PERFORM pg_notify('job_channel', NEW.id::text);
 RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER job_notify_trigger
AFTER INSERT ON durable_jobs
FOR EACH ROW
EXECUTE FUNCTION notify_job();

Considerations for Applying the Architecture

When applying this pattern (the pg_durable style) to high-performance systems like ZeroClaw or MCP servers, consider the following:

Database Load: Since the database partially acts as an execution engine rather than just a storage, frequent polling by workers or executing heavy logic can degrade DB performance. It is essential to configure it to allow multiple worker instances to process tasks safely and in a distributed manner, using the SKIP LOCKED clause.
Scalability (Scale-out): Even when the Rust code shown above is run as multiple processes, it can safely distribute tasks thanks to FOR UPDATE SKIP LOCKED. In a Kubernetes environment, flexible responses can be achieved by increasing worker pods when the queue grows, using HorizontalPodAutoscaler (HPA).

Conclusion

Microsoft’s pg_durable showcases an evolved form of ‘Data-Centric Architecture’. Before introducing complex message queues (Kafka, RabbitMQ), why not achieve simple yet robust durability by actively leveraging the transactional capabilities of the database? The example code above is readily testable in practice, so we recommend applying it to your side projects or back-office systems.

Designing Durable Workflows with SQLite: A Practical Guide to 'SQLite is All You Need'

Sat, 30 May 2026 09:00:30 +0900

How to Make Your Workflows Durable with SQLite

Recently, an article titled “SQLite is all you need for durable workflows” gained significant traction on Hacker News. When designing distributed systems, it’s easy to jump to solutions like Kafka, Redis, or complex clustering. However, the article argues that the core problems we aim to solve – ‘State Management’ and ‘Resiliency’ – can be sufficiently addressed by SQLite, a single-file database.

While developing agent systems like our team’s ‘ZeroClaw’ or ‘Discord Decision MCP’, we opted to implement our workflow engines directly, leveraging SQLite’s lightweight yet robust transactional capabilities before resorting to complex message queues. In this post, we’ll share the core architecture and practical code examples.

1. What is a Durable Workflow?

A workflow is considered ‘durable’ if it can resume execution from the point of interruption, even if the program crashes or the server restarts. To achieve this, we need to guarantee two things:

Snapshotting: Continuously save the current progress.
Exactly-Once Semantics: Prevent duplicate execution upon restart.

2. Architecture Design: Using SQLite as a Queue and State Store

SQLite demonstrates remarkable performance in concurrent environments, thanks to its WAL (Write-Ahead Logging) mode and advanced locking mechanisms. Our workflow engine operates based on the following table structure.

Database Schema

-- Table to store the current state of workflows
CREATE TABLE workflows (
 id TEXT PRIMARY KEY,
 status TEXT NOT NULL, -- pending, running, completed, failed
 current_step INTEGER NOT NULL DEFAULT 0,
 payload TEXT, -- Input data in JSON format
 updated_at INTEGER NOT NULL
);

-- List of jobs to be executed (the queue)
CREATE TABLE jobs (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 workflow_id TEXT NOT NULL,
 target_step INTEGER NOT NULL,
 run_at INTEGER, -- Scheduled execution time (NULL for immediate execution)
 FOREIGN KEY(workflow_id) REFERENCES workflows(id)
);

CREATE INDEX idx_jobs_run_at ON jobs(run_at);

Rust Implementation Example

We’ll write a simple workflow scheduler using Rust’s rusqlite library. This code is inspired by the lightweight job scheduling logic in the ‘ZeroClaw’ runtime.

use rusqlite::{Connection, Result, params};
use std::time::{Duration, SystemTime};

fn main() -> Result<()> {
 // 1. Connect to an in-memory or file-based DB (WAL mode recommended)
 let mut conn = Connection::open("workflow.db")?;
 conn.execute_batch("PRAGMA journal_mode=WAL;")?;

 // 2. Create a workflow (initial state)
 let workflow_id = "order-12345";
 insert_workflow(&mut conn, workflow_id, "{\"item\": \"keyboard\"}")?;

 // 3. Schedule a job (payment step)
 enqueue_job(&mut conn, workflow_id, 1, None)?;

 // 4. Worker loop (daemonize in production)
 loop {
 match fetch_next_job(&mut conn)? {
 Some(job) => {
 println!("Processing job {} for workflow {}", job.target_step, job.workflow_id);
 
 // Execute business logic (e.g., LLM calls, external API requests)
 // simulate_work();

 // Upon success, schedule the next step or handle completion
 complete_step(&mut conn, &job.workflow_id, job.target_step)?;
 }
 None => {
 println!("No jobs, sleeping...");
 std::thread::sleep(Duration::from_secs(5));
 }
 }
 }
}

// Transaction to enqueue a job and update workflow status to 'pending'
fn enqueue_job(conn: &mut Connection, workflow_id: &str, step: i32, delay: Option<SystemTime>) -> Result<()> {
 let tx = conn.transaction()?;
 
 tx.execute(
 "INSERT INTO jobs (workflow_id, target_step, run_at) VALUES (?1, ?2, ?3)",
 params![workflow_id, step, delay.and_then(|t| Some(t.duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs()))]
 )?;

 tx.execute(
 "UPDATE workflows SET status = 'pending', updated_at = ?1 WHERE id = ?2",
 params![SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs(), workflow_id]
 )?;

 tx.commit()
}

// Function to fetch the next job to be processed (Locking Read)
fn fetch_next_job(conn: &mut Connection) -> Result<Option<Job>> {
 // Technique to lock and return rows using an UPDATE statement (UPDATE RETURNING)
 // Supported in SQLite 3.35.0 and later
 let mut stmt = conn.prepare(
 "UPDATE jobs 
 SET workflow_id = workflow_id || ':processing' -- Temporary status indicator (a dedicated status column is recommended)
 WHERE rowid IN (
 SELECT rowid FROM jobs 
 WHERE run_at IS NULL OR run_at <= strftime('%s', 'now')
 LIMIT 1
 )
 RETURNING id, workflow_id, target_step;"
 )?;

 let mut rows = stmt.query(params![])?;
 match rows.next()? {
 Some(row) => Ok(Some(Job {
 id: row.get(0)?,
 workflow_id: row.get(1)?,
 target_step: row.get(2)?,
 })),
 None => Ok(None),
 }
}

// Process step completion
fn complete_step(conn: &mut Connection, workflow_id: &str, step: i32) -> Result<()> {
 let tx = conn.transaction()?;
 
 // Delete completed job
 tx.execute("DELETE FROM jobs WHERE workflow_id = ?1 AND target_step = ?2", params![workflow_id, step])?;
 
 // Update workflow status (to the next step)
 tx.execute(
 "UPDATE workflows SET current_step = ?1, updated_at = ?2 WHERE id = ?3",
 params![step + 1, SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs(), workflow_id]
 )?;
 
 tx.commit()
}

struct Job {
 id: i64,
 workflow_id: String,
 target_step: i64,
}

3. Why is this Structure Powerful?

The biggest advantage of this approach is its minimal operational overhead.

In agent systems like ‘ZeroClaw’, each agent operates with its own SQLite file, avoiding bottlenecks of a centralized database.
When building bots like Discord MCP, instead of deploying complex Redis containers, simply backing up the discord.db file can perfectly protect all conversation history and in-progress tasks.

4. Conclusion: “Just Enough”

The title “SQLite is all you need” doesn’t imply that SQLite can replace everything, but rather that SQLite is sufficient for most problems. Before introducing complex distributed systems, why not secure your workflow’s reliability with the simplest and most stable file-based database?

In the next post, we’ll discuss persistent volume strategies for reliably operating this SQLite workflow engine in a Kubernetes environment.

Implementing Postgres-based Durable Workflows: Using a DB as a Workflow Engine

Fri, 29 May 2026 09:00:36 +0900

As we’ve been building a fast and lightweight microservice architecture recently, minimizing external dependencies has emerged as a critical challenge. Specifically, during the development of the ZeroClaw runtime, we considered introducing separate message queues like Kafka or Redis to ensure complex state machine management and reliable communication between agents, but we were concerned about operational complexity.

At this point, the “Postgres-based Durable Workflow” pattern, which has recently been a hot topic on Hacker News and similar platforms, caught our attention. This approach goes beyond simply storing data, leveraging the database itself as a workflow engine to handle state persistence and retry logic. In this post, we’ll share the core concepts of this pattern and a practical implementation method applied to the ZeroClaw project.

Why Postgres?

Traditionally, we might have used specialized workflow engines like Temporal.io or Cadence, or implemented event sourcing through Kafka. However, for small teams or personal projects, maintaining such infrastructure can be a significant burden.

PostgreSQL is already adopted as the default database for most services. It guarantees strong consistency through ACID transactions and allows for distributed lock implementation (claim-based lock) using the SKIP LOCKED feature. This means we can simplify our infrastructure stack by utilizing our “already trusted storage” as a queue, a scheduler, and a state store.

Core Architecture: Using Tables as a Queue

The core of this pattern lies in defining workflow states and execution tasks within tables. Let’s take the ZeroClaw agent task queue as an example.

1. Defining the State Table (SQL)

We designed the workflow_jobs table to store the current state of a job and its next execution time.

CREATE TABLE workflow_jobs (
 id SERIAL PRIMARY KEY,
 job_type TEXT NOT NULL, -- e.g., 'agent_task', 'discord_notify'
 payload JSONB NOT NULL, -- Data required for execution
 status TEXT NOT NULL DEFAULT 'pending', -- pending, running, succeeded, failed
 claimed_at TIMESTAMP,
 run_after TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- Timestamp for delayed execution or retries
 last_error TEXT,
 attempt_count INT DEFAULT 0,
 max_attempts INT DEFAULT 5,
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- State-based indexing (for efficient lookups)
CREATE INDEX idx_jobs_claim ON workflow_jobs (status, run_after) WHERE status = 'pending';

The status and run_after columns are key here. These two columns allow us to immediately find “jobs that need to be executed now.”

2. Scheduling and Executing Tasks (Rust Example)

Now, a worker must find a task, claim ownership, and execute it within a transaction. To prevent race conditions, we use the FOR UPDATE SKIP LOCKED clause.

Here’s an example implementation using Rust and sqlx:

use sqlx::{PgPool, Postgres};
use sqlx::types::chrono::{Utc, DateTime};
use serde_json::Value;

#[derive(Debug)]
pub struct Job {
 pub id: i32,
 pub job_type: String,
 pub payload: Value,
}

/// Function called by the worker in its execution loop.
/// Safely claims a job within a transaction.
pub async fn claim_job(pool: &PgPool, worker_id: &str) -> Result<Option<Job>, sqlx::Error> {
 let now = Utc::now();
 
 let mut tx = pool.begin().await?;
 
 // 1. Find an executable job and lock it.
 // SKIP LOCKED: Ignores rows that have already been locked by another worker.
 let query = r#"
 SELECT id, job_type, payload 
 FROM workflow_jobs 
 WHERE status = 'pending' 
 AND run_after <= $1
 ORDER BY created_at ASC
 FOR UPDATE SKIP LOCKED
 LIMIT 1
 FOR UPDATE OF workflow_jobs
 "#;

 let job: Option<Job> = sqlx::query_as::<_, Job>(query)
 .bind(now)
 .fetch_optional(&mut *tx)
 .await?;

 let job = match job {
 Some(j) => j,
 None => {
 tx.rollback().await?; // No job to claim (Rollback is not strictly necessary but explicit)
 return Ok(None);
 }
 };

 // 2. Change the job status to 'running'.
 sqlx::query(
 "UPDATE workflow_jobs SET status = 'running', claimed_at = $1, attempt_count = attempt_count + 1 WHERE id = $2"
 )
 .bind(Utc::now())
 .bind(job.id)
 .execute(&mut *tx)
 .await?;

 tx.commit().await?;

 Ok(Some(job))
}

/// Function to update status after job completion.
pub async fn complete_job(pool: &PgPool, job_id: i32, success: bool, error_msg: Option<String>) -> Result<(), sqlx::Error> {
 let status = if success { "succeeded" } else { "failed" };
 
 // For failures, exponential backoff can be considered to calculate run_after.
 let next_run = if success {
 None
 } else {
 // e.g., Retry after 10 seconds (actual implementation should include exponential logic based on attempt_count)
 Some(Utc::now() + chrono::Duration::seconds(10))
 };

 if success {
 sqlx::query(
 "UPDATE workflow_jobs SET status = $1, run_after = NULL WHERE id = $2"
 )
 .bind(status)
 .bind(job_id)
 .execute(pool)
 .await?;
 } else {
 sqlx::query(
 "UPDATE workflow_jobs SET status = $1, last_error = $2, run_after = $3 WHERE id = $4"
 )
 .bind(status)
 .bind(error_msg)
 .bind(next_run)
 .bind(job_id)
 .execute(pool)
 .await?;
 }

 Ok(())
}

3. Worker Loop Configuration

Now, using the functions above, we can run an infinite loop (or use Tokio’s tokio::time::interval) to process jobs.

async fn worker_loop(pool: PgPool, worker_id: String) {
 loop {
 match claim_job(&pool, &worker_id).await {
 Ok(Some(job)) => {
 println!("[{}] Job acquired: {:?}", worker_id, job.job_type);
 
 // Execute actual business logic (e.g., LLM inference, API calls)
 let result = execute_logic(job.payload.clone()).await;

 // Reflect the result
 let _ = complete_job(&pool, job.id, result.is_ok(), result.err().map(|e| e.to_string())).await;
 }
 Ok(None) => {
 // If there are no jobs to process, wait briefly (to prevent high CPU usage)
 tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
 }
 Err(e) => {
 eprintln!("[{}] Worker error: {}", worker_id, e);
 tokio::time::sleep(tokio::time::Duration::from_secs(1)).await;
 }
 }
 }
}

Pros, Cons, and Usage Tips

Pros:

Simplicity: Achieves reliability using only RDBMS transactions without complex distributed system theory.
Operational Efficiency: Backing up the DB also restores workflow states.
Strong Consistency: No worries about in-flight message loss.

Cons:

Throughput Limitations: Postgres has limitations on per-connection throughput, so a specialized MQ is better if you need tens of thousands of transactions per second.
DB Load: Workers continuously poll, so connection pools should be optimized using tools like pgbouncer.

Conclusion

In ZeroClaw’s multi-agent environment, the message processing throughput of individual agents wasn’t high enough to justify introducing Kafka, but state management reliability was crucial. Through the Postgres-based architecture, we were able to achieve both “stable state management” and a “scalable task queue” without introducing separate infrastructure.

If your project is grappling with the trade-off between “simplicity” and “reliability,” why not consider leveraging the readily available Postgres as a workflow engine before adopting heavy-duty solutions?

References

Building durable workflows on Postgres (Hacker News Discussion)
SKIP LOCKED and Distributed Lock Implementation

Building ZeroClaw with Rust: An LLM-Based Multi-Agent Runtime Architecture

Mon, 25 May 2026 09:00:53 +0900

The recent surge in interest surrounding automation and agent systems leveraging LLMs (Large Language Models) is undeniable. However, single agents often face limitations when handling complex tasks, leading to the growing prominence of Multi-Agent Systems. In this post, we will introduce the architecture of ZeroClaw, an agent runtime built with Rust for high performance and stability, and explore how inter-agent communication is structured.

1. Why Rust? (Performance & Safety)

Most LLM applications are typically written in Python. However, in a ‘runtime’ environment where multiple agents execute concurrently and need to control their own independent memory spaces or file systems, Rust’s powerful parallel processing capabilities and memory safety become significant advantages.

Notably, as discussed recently on Hacker News, the issue of “Constraint Decay in LLM Agent Backend Code Generation” has emerged. In scenarios where LLM-generated code unintentionally breaks system constraints, Rust’s type system and ownership model can provide a safety net at the runtime level.

2. ZeroClaw’s Core Architecture

ZeroClaw is not just a simple LLM wrapper; it is a runtime engine that manages the lifecycle of agents and relays messages between them.

2.1. File-Based State Management

We have adopted an architecture that manages agent states and contexts based on the file system, without relying on complex databases. This enhances portability and debugging ease.

// Example struct for storing agent state
#[derive(Serialize, Deserialize, Debug)]
pub struct AgentState {
 pub id: String,
 pub role: AgentRole,
 pub status: ExecutionStatus,
 pub last_heartbeat: u64,
}

impl AgentState {
 pub fn save_to_file(&self, path: &Path) -> io::Result<()> {
 let json = serde_json::to_string_pretty(self)?;
 fs::write(path, json)?;
 Ok(())
 }
}

As discussed in the Multi-Agent: File-Based Architecture Design discussion, this approach allows each agent to transparently record its state, increasing the predictability of the overall system.

2.2. Event-Driven Communication

ZeroClaw’s agents do not call each other directly. Instead, they communicate through a central Event Bus or a Pub/Sub mechanism. This reduces coupling and ensures scalability.

// Communication protocol message definition
#[derive(Debug, Clone)]
pub enum AgentMessage {
 TaskRequest { task_id: String, payload: String },
 TaskResponse { task_id: String, result: String },
 StatusUpdate { agent_id: String, status: String },
}

// Simple channel-based message router (using tokio::sync::mpsc)
pub struct MessageRouter {
 // sender: HashMap<AgentId, Sender<AgentMessage>>
 // In a real implementation, it would manage agent-specific channels
}

This structure provides a foundation for addressing the ‘message queue reliability’ issues considered in architectures like the Claude Code Team Agent Communication Architecture or Multi-Agent Communication Protocol Design, using Rust’s robust asynchronous runtime (tokio).

3. Integration with MCP (Model Context Protocol)

ZeroClaw acts as both an MCP server and client, enabling integration with external tools (e.g., blog APIs, Discord Gateway). Recent improvements like the language parameter added to blog-api-server and enhanced logging help ZeroClaw agents maintain context when interacting with external systems.

Safely wrapping the invocation of MCP tools by agents is crucial.

// Safe wrapper for invoking MCP tools
pub async fn invoke_mcp_tool(tool_name: &str, params: serde_json::Value) -> Result<String, AgentError> {
 // 1. Parameter Validation
 if !validate_params(tool_name, &params) {
 return Err(AgentError::InvalidInput);
 }

 // 2. Actual Invocation (HTTP or IPC)
 let response = reqwest::Client::new()
 .post("http://localhost:8080/mcp/call")
 .json(&json!({
 "tool": tool_name,
 "args": params
 }))
 .send()
 .await?;

 // 3. Response Parsing and Logging
 tracing::info!("MCP Tool {} called successfully", tool_name);
 Ok(response.text().await?)
}

4. Conclusion: Development Directions for H1 2026

ZeroClaw is evolving beyond a mere experimental project to become a ‘high-performance agent runtime’, as mentioned in the H1 2026 Development Direction Meeting Minutes.

The goal is to simultaneously achieve LLM creativity and system safety, leveraging Rust’s performance. Specifically, there are plans to improve cost-effectiveness by integrating efficient models like DeepSeek, which is a recent trend.

The next post will cover a CI/CD pipeline integration case study where ZeroClaw agents actually generate and deploy code.

Reference Links

MCP (Model Context Protocol) Based Multi-Agent System Design and Implementation Guide

Sat, 23 May 2026 09:01:19 +0900

MCP (Model Context Protocol) Based Multi-Agent System Design and Implementation Guide

Recently, in the generative AI domain, Multi-Agent Systems are gaining attention to overcome the limitations of single LLMs (Large Language Models). In particular, with the emergence of MCP (Model Context Protocol) for standardized communication between agents, designing scalable and modular architectures has become essential.

This post explores how to design and implement efficient multi-agent architectures using MCP in high-performance agent runtime environments like ZeroClaw. We’ve included architectural design principles and actual code examples so readers can apply them immediately.

1. MCP-Based Multi-Agent Architecture Design

The most crucial aspect when building a multi-agent system is lowering coupling and increasing cohesion. To achieve this, MCP adopts a client-server model, where each agent or tool operates as an independent server and communicates through a standard protocol (based on JSON-RPC 2.0).

Key Design Principles

Standardized Interface: All agents must adhere to the MCP standard to expose tools, resources, and prompts.
Asynchronous Communication: For agents with long task execution times (e.g., file processing, web scraping), an asynchronous message queue should be utilized.
Statelessness: Agent servers should be designed to be as stateless as possible to facilitate horizontal scaling.

Architecture Diagram (Conceptual)

[User/Client LLM] <--> [MCP Gateway (Orchestrator)]
 | | |
 v v v
 [Blog Server] [Discord MCP] [Cloud Monitor]
 (Rust/TS) (Gateway) (Agent)

In this structure, the Gateway (Orchestrator) analyzes user requests, delegates tasks to the appropriate MCP servers (agents), and aggregates the results to return them to the user.

2. Implementing MCP Servers: Building Lightweight Agents with Rust

We will implement a simple MCP server in Rust to achieve high performance in environments like blog-api-server or ZeroClaw. This server provides a simple tool that returns the current time.

Dependency Setup (Cargo.toml)

We will use Rust’s powerful asynchronous runtime tokio, serde for JSON processing, and hyper or jsonrpc for MCP communication.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
hyper = { version = "0.14", features = ["server", "http1"] }

MCP Server Code Example

The following is a simplified implementation of a standard MCP server that communicates via STDIN/STDOUT.

use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use std::io::{self, BufRead, Write};

// MCP Request/Response structure definitions
#[derive(Deserialize)]
struct MCPRequest {
 jsonrpc: String,
 id: Option<String>,
 method: String,
 params: Option<Value>,
}

#[derive(Serialize)]
struct MCPResponse {
 jsonrpc: String,
 id: Option<String>,
 result: Option<Value>,
 error: Option<Value>,
}

fn handle_request(req: MCPRequest) -> MCPResponse {
 match req.method.as_str() {
 "initialize" => {
 // Called when the client wants to check the server's capabilities
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(json!({
 "protocolVersion": "2024-11-05",
 "capabilities": {
 "tools": {}
 },
 "serverInfo": {
 "name": "my-rust-agent",
 "version": "0.1.0"
 }
 })),
 error: None,
 }
 }
 "tools/list" => {
 // Returns a list of available tools
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(json!({
 "tools": [
 {
 "name": "get_current_time",
 "description": "Returns the current server time",
 "inputSchema": {
 "type": "object",
 "properties": {}
 }
 }
 ]
 })),
 error: None,
 }
 }
 "tools/call" => {
 // Actual tool execution logic
 if let Some(params) = req.params {
 let tool_name = params["name"].as_str().unwrap_or("");
 if tool_name == "get_current_time" {
 return MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(json!({
 "content": [
 {
 "type": "text",
 "text": format!("Current time: {}", chrono::Utc::now().to_rfc3339())
 }
 ]
 })),
 error: None,
 };
 }
 }
 // Error handling
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: None,
 error: Some(json!({
 "code": -32601,
 "message": "Tool not found"
 })),
 }
 }
 _ => MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: None,
 error: Some(json!({ "code": -32601, "message": "Method not found" })),
 },
 }
}

fn main() {
 let stdin = io::stdin();
 let mut stdout = io::stdout();

 for line in stdin.lock().lines() {
 let line = line.unwrap();
 if let Ok(req) = serde_json::from_str::<MCPRequest>(&line) {
 let res = handle_request(req);
 let res_json = serde_json::to_string(&res).unwrap() + "\n";
 stdout.write_all(res_json.as_bytes()).unwrap();
 stdout.flush().unwrap();
 }
 }
}

This code handles the core MCP methods initialize, tools/list, and tools/call, enabling LLMs (e.g., Claude Code) to recognize and invoke this agent as a tool.

3. Agent Communication and Data Synchronization

In architectures like ZeroClaw, where multiple agents collaborate, data sharing is crucial. A file-based architecture allows agents to exchange data while reducing coupling.

Consider a scenario where Agent A generates data, and Agent B consumes it.

Agent A (Producer): Saves the computation result to /tmp/shared/task_result.json.
Agent B (Consumer): Reads the resource file://tmp/shared/task_result.json via MCP, or calls a separate read_file tool.

// Example of Agent A calling a tool (pseudo-code)
fn save_result(data: &str) -> std::io::Result<()> {
 fs::write("/tmp/shared/task_result.json", data)?;
 Ok(())
}

This approach is useful when message queues are complex and effective for continuously tracking data, such as in the logging system or monitoring dashboard of blog-api-server.

4. Conclusion and Future Directions

Leveraging MCP allows for the modularization and maintainability of complex multi-agent systems.

Advantages: Language-agnostic interface (can mix Rust, TypeScript, etc.), tool reusability, standardized error handling.
Considerations: STDIN/STDOUT communication overhead, load balancing for the Gateway to handle large traffic.

The future goal is to build an environment within the ZeroClaw runtime where these MCP servers are containerized and dynamically scaled as needed. This will enable LLMs to evolve beyond simple chatbots into intelligent agent networks that automate complex tasks.

References

Enhancing AI Agent Reliability: A Guide to Integrating Forge Guardrails with MCP

Wed, 20 May 2026 09:00:35 +0900

Recent advancements in AI agents powered by Large Language Models (LLMs) have been remarkable. A notable case on Hacker News, “Forge – Guardrails take an 8B model from 53% to 99% on agentic tasks,” highlighted how applying appropriate Guardrails can dramatically increase the success rate of specific tasks, often more effectively than simply increasing model parameter count.

For our ongoing projects, ZeroClaw and those based on MCP (Model Context Protocol), agent reliability is paramount. In this post, we will explore the concept of Forge, an open-source guardrail framework, and introduce practical methods for integrating it into our existing MCP architecture to ensure agent stability.

Problem Definition: The Dilemma of Autonomy

Granting agents more autonomy increases the risk of unexpected behavior. For instance, when an MCP request is made to generate a blog post, an agent might attempt to execute system commands or call unauthorized APIs.

Our previous implementation of [blog-api-server] attempted to mitigate this through prompt engineering and basic JSON schema validation, but these proved insufficient in complex multi-agent environments. To address this, we decided to introduce an L1 Guardrail layer for pre-filtering inputs and outputs.

Solution: Applying the Guardrails Pattern

As demonstrated by Forge, the key to improving agent task success rates (53% → 99%) lies in pre-execution validation. We designed a structure where a middleware layer validates the agent’s responses before they are delivered to the user or used to execute tools.

Architecture Overview

A Validator layer is placed between the existing MCP client and the LLM to perform the following:

Input Validation: Checks if user requests violate system policies (e.g., filtering for aggressive prompts).
Output Validation: Verifies if LLM-generated JSON or function call arguments conform to the schema.

Practical Code Example: Implementing Safeguards in Rust

Let’s implement a lightweight output validator within the Rust environment of ZeroClaw. This example uses serde and regex to safely wrap code execution commands generated by the LLM, without complex external libraries.

1. Implementing Validation Logic

First, here’s a simple validator to determine if a command generated by the agent is safe.

use regex::Regex;
use serde::{Deserialize, Serialize};

// Structure for commands an agent might generate
#[derive(Debug, Serialize, Deserialize)]
struct AgentCommand {
 tool_name: String,
 parameters: String,
}

pub struct Guardrail;

impl Guardrail {
 // Simple example for filtering dangerous strings
 fn is_dangerous(input: &str) -> bool {
 let dangerous_patterns = vec!["rm -rf", "sudo", "eval", "__import__"];
 dangerous_patterns.iter().any(|&pat| input.contains(pat))
 }

 // Validation logic before command execution
 pub fn validate_command(cmd: &AgentCommand) -> Result<&AgentCommand, String> {
 // 1. Check tool name against a whitelist
 let allowed_tools = vec!["blog_post", "search", "read_file"];
 if !allowed_tools.contains(&cmd.tool_name.as_str()) {
 return Err(format!("Attempt to use disallowed tool: {}", cmd.tool_name));
 }

 // 2. Check for dangerous keywords within parameters
 if Self::is_dangerous(&cmd.parameters) {
 return Err("Potentially dangerous command included in parameters.".to_string());
 }

 // 3. If safe, approve the command
 Ok(cmd)
 }
}

2. Integrating into the Agent Loop

Now, we connect the validator to the request processing loop of the MCP server. After the agent generates a response, it must pass through the Guardrail before the actual system executes it.

// Hypothetical agent execution function
fn execute_agent_task(llm_output: &str) -> Result<String, String> {
 // 1. Parse LLM output (in reality, this would involve JSON parsing, etc.)
 // We assume parsing is successful here for simplicity.
 let command = AgentCommand {
 tool_name: "blog_post".to_string(),
 parameters: "title: 'Hello World'".to_string(),
 };

 // 2. Before guardrail passage
 println!("[System] LLM response received: {}", command.tool_name);

 // 3. Execute guardrail validation
 let safe_command = Guardrail::validate_command(&command)?;

 // 4. Execute validated command
 println!("[System] Executing safe command...");
 // Actual tool execution logic (e.g., calling the blog API)
 Ok("Post successfully created.".to_string())
}

fn main() {
 // Normal case
 match execute_agent_task("valid_response") {
 Ok(msg) => println!("Success: {}", msg),
 Err(e) => println!("Blocked: {}", e),
 }

 // Simulate an abnormal case
 let malicious_cmd = AgentCommand {
 tool_name: "system_shell".to_string(), // Not in whitelist
 parameters: "rm -rf /".to_string(),
 };

 match Guardrail::validate_command(&malicious_cmd) {
 Ok(_) => println!("Error: Hacker has infiltrated!"),
 Err(e) => println!("Protected: {}", e), // "Protected: Attempt to use disallowed tool: system_shell"
 }
}

Benefits and Outlook

By establishing this L1 defense line, we gain the following advantages:

Improved Stability: Similar to the Forge case, even 8B models can be utilized safely, reducing inference costs.
Enhanced Transparency: Logs clearly indicate why an agent rejected a specific task.
Maintainability: Security policy changes only require modifications to the Guardrail module.

Moving forward, the ZeroClaw project plans to integrate this validation logic into an asynchronous runtime, enabling real-time safety monitoring during inter-agent communication ([Discord MCP], [Cloud Monitor]).

Instead of solely focusing on improving model performance, the key to deploying AI agents in actual production environments will lie in how we design system-level safeguards like these.

This article was written with reference to architectural design documents related to ZeroClaw and MCP.

Deep Dive into ZeroClaw Architecture: Implementing Secure Inter-Agent Communication with Rust

Mon, 11 May 2026 09:01:26 +0900

Hello everyone! As the ZeroClaw project progresses, I want to share the design considerations and solutions encountered while building a high-performance Rust agent runtime and a multi-agent system. Recent security incidents, such as the ‘Remote Access Trojan (RAT) exploiting Obsidian plugins’, serve as a stark reminder of how crucial Security and Trust are in plugin and agent systems.

Today, I’ll introduce the secure and scalable inter-agent communication protocol designed by analyzing ZeroClaw’s codebase, along with concrete Rust code examples.

1. Introduction: The Need for Security-Conscious Agent Communication

During the development of previous MCP (Model Context Protocol) and blog automation systems, we realized that beyond simple data transfer, Authentication and Authorization between agents are essential. In a multi-agent environment where multiple agents collaborate to generate files or call external APIs, a mechanism to prevent malicious command injection is indispensable.

To address this, ZeroClaw adopts an architecture that leverages Rust’s Type Safety and Ownership system to catch many bugs at compile time and minimize runtime overhead.

2. Communication Protocol Design: IPC and Message Queues

ZeroClaw’s communication platform is broadly divided into Local IPC (Inter-Process Communication) and an Asynchronous Message Queue. Based on our experience improving the logging system, all communication is handled asynchronously (async), ensuring the independence of each agent.

Key Design Principles

Zero-Copy Serialization: Minimizes data serialization overhead using serde and bincode.
Message Validation: A layer validates all incoming messages to prevent tampered data from reaching the system core.
Capability-Based Security: Goes beyond simple token-based authentication by restricting the capabilities (actions) an agent can perform.

3. Implementing Secure Messaging Handlers with Rust

Let’s explore how this is implemented through actual code. This example is based on tokio and demonstrates the basic structure for secure message delivery.

3.1 Message Definition and Validation

First, we define the data structures for inter-agent communication and use the validator crate for input validation.

// message.rs
use serde::{Deserialize, Serialize};
use validator::Validate;

/// Agent communication message type
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AgentMessage {
 TaskRequest { id: String, payload: TaskPayload },
 TaskResponse { id: String, result: String },
 Heartbeat,
}

/// Task payload (includes validation logic)
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct TaskPayload {
 #[validate(length(min = 1, max = 100))]
 pub command: String,
 
 // Accepts JSON-formatted arguments but must be parsed structurally safely
 pub args: serde_json::Value, 
}

impl AgentMessage {
 /// Safely deserializes a message from a byte array.
 pub fn from_bytes(bytes: &[u8]) -> Result<Self, Box<dyn std::error::Error>> {
 // 1. Basic serialization validation
 let msg: AgentMessage = bincode::deserialize(bytes)?;
 
 // 2. Business logic validation (e.g., prevent Command Injection)
 if let AgentMessage::TaskRequest { payload, .. } = &msg {
 payload.validate()?; // Using the validator crate
 
 // Security: Example of filtering disallowed shell commands
 if payload.command.contains("rm ") || payload.command.contains("sudo") {
 return Err("Blocked potentially dangerous command".into());
 }
 }
 
 Ok(msg)
 }
}

3.2 Actor Model-Based Agent Structure

Each agent follows an Actor pattern, maintaining its own state and processing messages. Rust’s tokio::sync::mpsc channel is used to implement the mailbox.

// agent.rs
use tokio::sync::mpsc;
use super::message::AgentMessage;

pub struct Agent {
 id: String,
 receiver: mpsc::Receiver<AgentMessage>,
 // The agent's state is encapsulated here and not directly accessible from outside
}

impl Agent {
 pub fn new(id: String, receiver: mpsc::Receiver<AgentMessage>) -> Self {
 Self { id, receiver }
 }

 /// The agent's main loop
 pub async fn run(mut self) {
 println!("[{}] Agent started", self.id);
 
 while let Some(msg) = self.receiver.recv().await {
 if let Err(e) = self.handle_message(msg).await {
 eprintln!("[{}] Error handling message: {:?}", self.id, e);
 }
 }
 }

 async fn handle_message(&self, msg: AgentMessage) -> Result<(), Box<dyn std::error::Error>> {
 match msg {
 AgentMessage::TaskRequest { id, payload } => {
 println!("[{}] Executing task {}: {}", self.id, id, payload.command);
 // Actual task execution logic goes here (e.g., LLM calls, file writes, etc.)
 // Safeguards: Execute in a sandboxed environment or restrict permissions.
 },
 AgentMessage::Heartbeat => {
 // Handle heartbeat signal
 },
 _ => return Err("Unknown message type".into()),
 }
 Ok(())
 }
}

3.3 Runtime and Message Routing

Finally, here’s a simple runtime system for creating multiple agents and routing messages.

// runtime.rs
use tokio::sync::mpsc;
use std::collections::HashMap;
use super::agent::Agent;
use super::message::AgentMessage;

pub struct Runtime {
 agents: HashMap<String, mpsc::Sender<AgentMessage>>,
}

impl Runtime {
 pub fn new() -> Self {
 Self { agents: HashMap::new() }
 }

 pub fn spawn_agent(&mut self, id: &str) {
 let (tx, rx) = mpsc::channel(32);
 let agent = Agent::new(id.to_string(), rx);
 
 // Run the agent in a separate task
 tokio::spawn(agent.run());
 
 self.agents.insert(id.to_string(), tx);
 println!("Runtime: Agent '{}' spawned", id);
 }

 pub async fn broadcast(&self, msg: AgentMessage) {
 for (id, tx) in self.agents.iter() {
 if let Err(e) = tx.send(msg.clone()).await {
 eprintln!("Failed to send to {}: {:?}", id, e);
 }
 }
 }
}

4. Conclusion and Next Steps

The code implemented above demonstrates the core of the ZeroClaw multi-agent system: secure communication and isolated state management. Systems that execute external inputs or scripts, like the Obsidian plugin incident, are always potential targets for attacks.

ZeroClaw uses Rust’s powerful type system to block most of these risks at compile time and defends against them at runtime with additional validation layers. In the next post, we will discuss how this agent system actually integrates with external gateways like Discord or MCP, and how it is controlled through LLM configurations.

So far, I’ve shared the current status of ZeroClaw’s architectural design. I hope this is helpful for those looking to build high-performance yet secure agent systems!

Note: The code above is a Proof of Concept (POC) level example. For actual production environments, more robust error handling and logging systems (referencing the logging setup improved in the previous post) must be integrated.

High-Performance MCP Server Implemented with Rust: Asynchronous Messaging Using ZeroMQ

Sun, 10 May 2026 09:01:24 +0900

High-Performance MCP Server Implemented with Rust: Asynchronous Messaging Using ZeroMQ

Recently, while working on the ZeroClaw project, we identified a need to overcome the performance limitations of MCP (Model Context Protocol) servers. Traditional HTTP-based communication struggles to move beyond a single request-response pattern, and real-time communication between numerous LLM agents is prone to bottlenecks. In this post, we will cover the process of building an ultra-lightweight, ultra-fast MCP server by leveraging Rust’s powerful asynchronous processing capabilities and ZeroMQ (ØMQ).

Why ZeroMQ? (Comparison with TCP Socket Limitations)

In the previous blog-api-server architecture, we defined and used protocols directly using standard TCP streams. However, in a multi-agent environment, the following issues arise:

Connection Management Complexity: As the number of agents grows into the dozens, managing the Accept loop and socket states requires unsafe code or complex state machines.
Message Enveloping: TCP is a byte stream. We must implement Length-Prefixing directly to demarcate message boundaries, which is a common source of bugs.

ZeroMQ abstracts away the complexity of this lower socket layer while providing a faster “User Space” transport layer than TCP. Notably, using the ipc (Inter-Process Communication) protocol can completely eliminate network stack overhead for localhost communication.

Architecture Design: ZeroMQ PUB/SUB Pattern

For this implementation, we will use the Publish/Subscribe (PUB/SUB) pattern for loose coupling between agents. When one agent changes its state (Publishes), a message is immediately broadcast to other agents subscribing to that topic.

Key Dependencies (Cargo.toml)

In the Rust ecosystem, ZeroMQ is available through the zmq crate. While tokio-zmq can be used for integration with asynchronous runtimes, for pure performance, leveraging ZeroMQ’s poll functionality is often more stable.

[dependencies]
zmq = "0.10"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio = { version = "1", features = ["full"] }

Implementation: High-Performance MCP Router

The code below is an example implementation of an MCP Router that acts as a simple message broker. It serves as a central hub for multiple LLM agents (teams) to communicate with each other.

1. Define Message Protocol

First, let’s define the format of messages exchanged between agents. We ensure compatibility by using JSON serialization.

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct McpMessage {
 pub source_id: String,
 pub target_topic: String,
 pub payload: String,
 pub timestamp: i64,
}

2. Asynchronous ZeroMQ Context and Socket Setup

ZeroMQ’s Context is thread-safe, so it’s common practice to create and share a single instance globally throughout the application.

use std::time::SystemTime;
use zmq::{Context, Socket, SocketType};

struct McpRouter {
 context: Context,
 frontend: Socket, // Agents connect here
 // Can add sockets for other patterns if needed
}

impl McpRouter {
 fn new() -> Result<Self, zmq::Error> {
 let context = Context::new();
 let frontend = context.socket(SocketType::SUB)?;
 
 // Set to receive all messages (no filtering)
 frontend.set_subscribe(b"")?;
 
 Ok(McpRouter { context, frontend })
 }

 fn start(&self, endpoint: &str) -> Result<(), zmq::Error> {
 self.frontend.bind(endpoint)?;
 println!("[ZeroClaw Router] Listening on {}", endpoint);

 let mut msg = zmq::Message::new();
 loop {
 // Can use poll for non-blocking receive
 // Here, a simple blocking receive example
 match self.frontend.recv(&mut msg) {
 Ok(_) => {
 let data = msg.as_str().unwrap();
 // Message parsing and routing logic
 if let Ok(mcp_msg) = serde_json::from_str::<McpMessage>(data) {
 self.route_message(mcp_msg);
 }
 }
 Err(e) => {
 eprintln!("Receive Error: {}", e);
 }
 }
 }
 }

 fn route_message(&self, msg: McpMessage) {
 // Implement actual routing logic
 println!("Routing from {} on topic {}", msg.source_id, msg.target_topic);
 // e.g., save to database, forward to another socket, etc.
 }
}

3. Agent Publisher Implementation

Now, let’s write the code for individual agents to send messages. When using tokio, you need to execute ZeroMQ’s blocking functions in a separate thread to avoid blocking the asynchronous runtime.

use std::thread;

fn spawn_publisher_agent(id: &str, endpoint: &str) {
 let context = Context::new();
 let sender = context.socket(SocketType::PUB).expect("Failed to create PUB socket");
 sender.connect(endpoint).expect("Failed to connect to Router");

 // Run in a separate thread to isolate from the Tokio runtime
 thread::spawn(move || {
 let counter = 0..100;
 for i in counter {
 let msg = McpMessage {
 source_id: id.to_string(),
 target_topic: "general".to_string(),
 payload: format!("Message #{} from agent {}", i, id),
 timestamp: SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs() as i64,
 };

 let json_str = serde_json::to_string(&msg).unwrap();
 // ZeroMQ automatically retries or queues sending if it fails (set High-water mark if needed)
 sender.send(json_str.as_bytes(), 0).expect("Failed to send");
 
 thread::sleep(std::time::Duration::from_millis(100));
 }
 });
}

Performance Optimization and IPC Utilization

The true power of a Rust ZeroMQ server is unleashed when using the IPC (Inter-Process Communication) transport. While TCP involves packets traversing the network stack and looping back, IPC uses Unix Domain Sockets or Windows Named Pipes for communication at a level close to memory copying.

To use the ipc protocol, change the endpoint as follows:

// Use IPC instead of TCP
let endpoint = "ipc:///tmp/mcp_router.ipc";
router.start(endpoint);

Just as modern languages like Bun and Zig gain attention for their system-level optimizations, the combination of Rust and ZeroMQ is one of the most powerful tools for building the “system bus” for LLM applications.

Conclusion

In this post, as part of the ZeroClaw project, we explored how to build a high-performance MCP server using Rust and ZeroMQ. Beyond simple HTTP requests, this architecture offers significant advantages in scalability and performance for environments requiring real-time messaging between agents.

In the next post, we will discuss the Circuit Breaker pattern and error handling strategies to add reliability to this messaging system.

References

Memory Safety and Efficient Resource Management of the ZeroClaw Agent Runtime

Sat, 09 May 2026 09:01:27 +0900

Memory Safety and Efficient Resource Management of the ZeroClaw Agent Runtime

As we’ve been building a high-performance multi-agent runtime through the ZeroClaw project, we’ve been contemplating how to leverage Rust’s distinctive features—‘memory safety’ and ‘zero-cost abstractions’—in practice. Beyond simply being safe, the core challenge was how to efficiently manage system resources and maintain stable performance without Garbage Collection (GC) in a scenario where numerous agents simultaneously exchange messages.

This post aims to share the efficient resource management strategies based on Rust and practical code examples that were applied during the ZeroClaw architecture design process.

Problem Definition: Resource Bottlenecks in Multi-Agent Environments

In multi-agent systems, each agent possesses its own independent state and communicates through asynchronous messages. This process gives rise to the following resource issues:

Frequent Allocation/Deallocation (Allocation Thrashing): When hundreds of agents process thousands of messages per second, frequent allocation and deallocation of heap memory become a primary cause of performance degradation.
Data Race: We must prevent race conditions that can occur when multiple agents access shared resources, while also avoiding bottlenecks caused by excessive lock usage.
Lifecycle Management: A mechanism is needed to safely reclaim resources, ensuring that memory leaks do not occur throughout the system even if an agent terminates abnormally.

Solution Strategy: Rust’s Ownership and Tokio’s Scheduling

To address these issues, ZeroClaw has combined Rust’s Ownership system with the asynchronous abstractions of the tokio runtime.

1. State Sharing using `Arc` and `RwLock`

For immutable data sharing in inter-agent communication, we’ve minimized costs using Arc (Atomic Reference Counting). For state updates, we’ve employed RwLock to allow concurrent read operations while ensuring data integrity only during write operations.

2. Message Passing via Channels

Instead of directly managing shared memory state, we adopted a message-passing approach (Actor model) using tokio::sync::mpsc channels. This fundamentally prevents data races by allowing each agent to exclusively manage its own state.

Practical Code Examples

Below is an example implementation of a simple agent message handler used in ZeroClaw’s communication layer.

Agent Message Definition and Handler Structure

use tokio::sync::{mpsc, RwLock};
use std::sync::Arc;
use std::time::Duration;

// Define the command types agents will process
#[derive(Debug)]
enum AgentCommand {
 ProcessTask(String),
 UpdateStatus(String),
 Shutdown,
}

// Agent's state structure
struct AgentState {
 id: String,
 status: String,
 processed_tasks: u64,
}

// Agent executor structure
struct AgentExecutor {
 state: Arc<RwLock<AgentState>>,
 receiver: mpsc::Receiver<AgentCommand>,
}

impl AgentExecutor {
 // Constructor for creating a new agent
 fn new(id: String, receiver: mpsc::Receiver<AgentCommand>) -> Self {
 Self {
 state: Arc::new(RwLock::new(AgentState {
 id,
 status: "Initialized".to_string(),
 processed_tasks: 0,
 })),
 receiver,
 }
 }

 // Start the message reception and processing loop
 async fn run(mut self) {
 println!("Agent {} started.", self.state.read().await.id);
 
 while let Some(cmd) = self.receiver.recv().await {
 match cmd {
 AgentCommand::ProcessTask(task_id) => {
 // Simulate asynchronous work (e.g., LLM inference request)
 let task_id_clone = task_id.clone();
 let state_clone = Arc::clone(&self.state);
 
 // Process as a background task to avoid blocking the message loop
 tokio::spawn(async move {
 tokio::time::sleep(Duration::from_millis(100)).await;
 let mut state = state_clone.write().await;
 state.processed_tasks += 1;
 state.status = format!("Processing {}", task_id_clone);
 println!("Task {} processed by Agent {}. Total: {}", 
 task_id_clone, state.id, state.processed_tasks);
 });
 }
 AgentCommand::UpdateStatus(new_status) => {
 let mut state = self.state.write().await;
 state.status = new_status;
 }
 AgentCommand::Shutdown => {
 println!("Agent {} shutting down...", self.state.read().await.id);
 break;
 }
 }
 }
 }
}

Main Runtime Configuration and Resource Management

Now, let’s write the main runtime code that creates and manages the agents above. Here, we implement graceful shutdown using the tokio::select! macro to prevent resource leaks.

#[tokio::main]
async fn main() {
 // Store a list of senders for managing multiple agents
 // Managed as a Vec to handle agent termination
 let mut agent_senders = Vec::new();

 // Spawn 3 agents
 for i in 0..3 {
 let (tx, rx) = mpsc::channel(100); // Buffer size 100
 agent_senders.push(tx);
 
 let executor = AgentExecutor::new(format!("Agent-{}", i), rx);
 tokio::spawn(executor.run());
 }

 // System-wide shutdown signal (handling Ctrl+C, etc.)
 let (shutdown_tx, mut shutdown_rx) = mpsc::channel::<()>(1);
 
 // Task distribution logic (simulation)
 let task_distributor = tokio::spawn(async move {
 let mut task_counter = 0;
 loop {
 // Check for shutdown signal
 if shutdown_rx.try_recv().is_ok() {
 println!("Task distributor stopping...");
 break;
 }

 // Send tasks to agents in a round-robin fashion
 if !agent_senders.is_empty() {
 let target_index = task_counter % agent_senders.len();
 let task_id = format!("Task-{}", task_counter);
 
 if let Err(_) = agent_senders[target_index].send(AgentCommand::ProcessTask(task_id)).await {
 println!("Failed to send task. Agent might be dead.");
 }
 
 task_counter += 1;
 tokio::time::sleep(Duration::from_millis(50)).await;
 }
 }
 });

 // Simulate system shutdown after 5 seconds
 tokio::time::sleep(Duration::from_secs(5)).await;
 
 // 1. Terminate task distribution
 let _ = shutdown_tx.send(()).await;
 task_distributor.await.unwrap();

 // 2. Send shutdown command to all agents
 for tx in agent_senders {
 let _ = tx.send(AgentCommand::Shutdown).await;
 }

 // Wait for resource cleanup
 tokio::time::sleep(Duration::from_millis(500)).await;
 println!("System shutdown complete.");
}

Key Point Analysis

Arc<RwLock<State>> Pattern: The AgentExecutor stores its state wrapped in Arc<RwLock>. Asynchronous tasks created with tokio::spawn receive a clone of this Arc. This is very lightweight as it only increments the reference count, not by copying the data itself.
Ownership Transfer in MPSC Channels: The tx (Sender) end is owned by the main loop, and the rx (Receiver) end is owned by the AgentExecutor. This clear separation of ownership ensures at compile time who sends and who receives messages.
Harmony of Asynchronous I/O and Locks: When using state.write().await, the current task is suspended (yielded) until it acquires the lock for writing. This differs from blocking an OS thread and allows other tasks to utilize the CPU, thereby increasing multi-core utilization.

Conclusion

Rust’s memory management mechanisms are not just about safety; they become a powerful tool for designing high-performance server architectures. In the ZeroClaw project, this allowed us to minimize inter-agent communication overhead and achieve predictable latency. In particular, the channel-based architecture combined with the tokio runtime provides a foundation for maintaining stability even in complex systems where thousands of agents interact.

In the next post, we will expand on inter-agent communication to discuss an architecture for implementing file-based persistence.

Reference Links

Building a Multi-LLM Distributed Orchestrator with NATS JetStream

Fri, 08 May 2026 21:57:11 +0900

Part 1 discussed the model-specific limitations discovered while running four AIs—Claude, ZAI, Codex, and Gemini—concurrently on the same tasks. This part is about “how we made it possible”—the system design and implementation story.

System Overview

AgentForge consists of three components.

[Task Publisher]
 │ NATS JetStream publish
 ▼
[NATS Broker] ─── af.worker.{id}.inbox
 │ JetStream consume (independent streams per worker)
 ▼
[Worker Pollers] × N (poller.py × 18 instances)
 │ LLM CLI Execution (claude / codex / gemini)
 ▼
[Result Return] af.task.{task_id}.completed

When a publisher posts a task to NATS, each worker, which is independently subscribed, receives the message on its inbox and executes the LLM CLI. The result is then published back to a completion topic.

Why NATS JetStream?

We considered several message broker options: Redis Streams, Kafka, RabbitMQ, and NATS JetStream.

Reasons for choosing NATS JetStream:

Single Binary — Operates with a single nats-server without requiring separate runtimes. It has no dependencies like Kafka’s ZooKeeper or RabbitMQ’s Erlang/OTP.
Built-in Persistence — JetStream is a streaming layer on top of NATS, storing messages to the filesystem. This ensures that unprocessed tasks are not lost even if a worker restarts.
NKey-based Authentication — We can issue independent Ed25519 key pairs for each worker. If one worker is compromised, the credentials of other workers remain valid.
Lightweight — Memory usage is around 30MB on a single server. Even with 18 workers connected, the broker load is minimal.

The Core: Backend Adapter in `poller.py`

The heart of the worker is poller.py. This single file handles NATS subscriptions, LLM CLI execution, and result returns.

Since LLMs have different execution methods, we separated them into a backend adapter dictionary.

_BACKENDS: dict[str, dict] = {
 "claude": {
 "bin": os.environ.get("CLAUDE_BIN", "/usr/local/bin/claude"),
 "tools": os.environ.get("ALLOWED_TOOLS", "Read,Edit,Write,Glob,Grep"),
 "model": os.environ.get("CLAUDE_MODEL", ""),
 },
 "codex": {
 "bin": os.environ.get("CODEX_BIN", "/usr/bin/codex"),
 "model": os.environ.get("CODEX_MODEL", ""),
 "sandbox": os.environ.get("CODEX_SANDBOX", "read-only"),
 },
 "gemini_cli": {
 "bin": os.environ.get("GEMINI_BIN", "/usr/bin/gemini"),
 "model": os.environ.get("GEMINI_MODEL", ""),
 },
}

The MODEL_BACKEND environment variable determines which LLM to use. This allows the same poller.py code to run different LLMs across 18 workers.

Claude Backend

async def run_claude(instructions: str, task_id: str) -> tuple[int, str]:
 cfg = _BACKENDS["claude"]
 cmd = [cfg["bin"], "--print", "--allowedTools", cfg["tools"]]
 if cfg.get("model"):
 cmd += ["--model", cfg["model"]]
 proc = await asyncio.create_subprocess_exec(*cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)

The --print flag is key. It runs Claude Code in non-interactive mode instead of conversational mode, ensuring the results are returned via stdout.

ZAI Backend

ZAI offers an Anthropic API-compatible endpoint, so it doesn’t require a separate backend. Routing is handled by two environment variables.

# /etc/agentforge/cc-zai-high-dev-01.env
ANTHROPIC_BASE_URL=<ZAI endpoint>
ANTHROPIC_AUTH_TOKEN=<ZAI API key>

By injecting this file using systemd’s EnvironmentFile= directive, the claude binary sends requests to the ZAI endpoint. This allows us to connect to a different LLM provider simply by changing environment variables, without altering the code.

Declarative Management: `fleet.yaml` × `servers.yaml`

Manually managing 18 workers is impractical. We declaratively defined the entire infrastructure using two YAML files.

`servers.yaml` — Server Inventory

servers:
 - name: worker-node-1
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

 - name: broker-host
 role: broker-host
 services: [nats-jetstream, postgres]

 - name: worker-node-2
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

`fleet.yaml` — Worker Placement

workers:
 - worker_id: cc-go-dev-01
 llm: claude-code
 model: claude-sonnet-4-6
 lang: go
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: true

 - worker_id: codex-py-dev-01
 llm: codex
 model: gpt-5.5
 lang: python
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

Changing just the host field moves a worker to a different server. Setting enabled: false stops the deployment script from starting that worker.

Worker Templating System: `provision_worker.py`

Manually writing systemd unit files for each new worker is prone to errors. We automated this using Jinja2 templates and a provisioning script.

Template Structure

templates/
 systemd/
 claude.service.j2 # For claude-code and ZAI alike
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

The core part of claude.service.j2:

Environment=MODEL_BACKEND=claude
Environment=CLAUDE_BIN={{ claude_bin }}
{% if claude_model %}
Environment=CLAUDE_MODEL={{ claude_model }}
{% endif %}
{% if env_file %}
EnvironmentFile={{ env_file }}
{% endif %}
Environment=WORK_BASE={{ work_base }}
Environment=WORK_DIR={{ work_base }}/repo
Environment="{{ 'ALLOWED_TOOLS=' + allowed_tools }}"
Environment=CREATE_PR={{ 'true' if create_pr else 'false' }}
{% if create_pr and github_remote %}
Environment=GITHUB_REMOTE={{ github_remote }}
{% endif %}

For ZAI workers, the env_file block is activated, adding the EnvironmentFile. For PR creation workers, github_remote is injected. Other settings use defaults.

`provision_worker.py` Usage

# Preview (no actual deployment)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# Actual deployment (including NATS creds issuance)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# Bulk deployment for the entire fleet.yaml
python3 scripts/provision_worker.py --all

Internal operations:

Reads worker entries from fleet.yaml.
Reads target hosts from servers.yaml.
Renders Jinja2 templates.
Deploys /etc/systemd/system/{worker_id}-poller.service via SSH.
Creates the working directory.
Executes systemctl daemon-reload && enable --now.
(Optional) Issues NATS NKey with nsc add user → deploys creds → regenerates auth.conf.

Distributed Hosting: Adding Workers to a Second Server

Running all workers on a single server creates a single point of failure. We added Claude workers to a second host.

The method for workers on the second host to connect to the NATS broker is via an autossh tunnel.

[Unit]
Description=NATS Broker Tunnel
After=network-online.target

[Service]
ExecStart=/usr/bin/autossh -N \
 -L 4222:127.0.0.1:4222 \
 -i /home/ubuntu/.ssh/id_ed25519 \
 broker-host
Restart=always
RestartSec=10

With this configuration active, workers always connect to nats://127.0.0.1:4222. They don’t need to know the broker host’s address. As long as the tunnel is alive, it works the same way from any host.

NATS Credential Operations Experience

NATS NKey management was the most complex part of the implementation.

NATS JetStream’s authentication structure is hierarchical.

Operator (Root Signing Authority)
 └── Account: SYS (System Account)
 └── Account: Services (Worker Account)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

Each worker has an independent User NKey and can publish/subscribe within the permissions scope (af.>, _INBOX.>, $JS.>) of the Services account.

Adding a new worker requires the Operator’s signing key. We initially made the mistake of not backing up this key, leading to its loss. Consequently, we had to regenerate the entire Operator and replace all worker credentials en masse. The service downtime was approximately 60 seconds.

# Regeneration procedure
nsc add operator AgentForge
nsc add account SYS
nsc add account Services
for worker in cc-dev-01 cc-go-dev-01 ...; do
 nsc add user --account Services --name $worker \
 --allow-pub "af.>,_INBOX.>,$JS.>" \
 --allow-sub "af.>,_INBOX.>,$JS.>"
done
nsc generate config --mem-resolver --sys-account SYS > auth.new.conf

Adding a New Worker: The Full Procedure

Since the completion of this system, adding a new worker is straightforward.

Step 1: Add an entry to fleet.yaml

- worker_id: my-new-worker
 llm: claude-code
 model: claude-haiku-4-5
 lang: multi
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

Step 2: Preview

python3 scripts/provision_worker.py --worker my-new-worker --dry-run

Step 3: Actual Deployment

python3 scripts/provision_worker.py --worker my-new-worker --issue-creds

That’s it. Template rendering, SSH deployment, NATS credential issuance, and service registration are all handled by a single command.

Next Steps

The current system is structured such that workers process tasks independently. Future plans include:

Routing Policies: Automatically selecting the appropriate worker based on task characteristics (e.g., Go code → claude-go-dev, cost-first → ZAI lightweight tier).
Results Comparison Dashboard: A UI to display fan-out results side-by-side.
Cost Tracking: Aggregating API call costs per worker.

The code is publicly available on GitHub.

The Next Step in Agent Development: Introducing Control Flow

Fri, 08 May 2026 09:01:23 +0900

The Next Step in Agent Development: Introducing Control Flow

I recently read the article ‘Agents need control flow, not more prompts’ and deeply resonated with its message. When initially developing LLM-based agents, prompt engineering felt like the entirety of development. However, as systems became more complex and we started dealing with multi-agent runtimes like ZeroClaw, I keenly realized that ‘structure,’ not ‘prompts,’ is the core.

In this article, I’ll share how to introduce Control Flow into your architecture to build scalable agent systems, reducing complex prompts and providing practical code examples.

Problem Definition: Prompt Limitations and ‘Dependency Hell’

It’s challenging to instruct a single agent with a prompt like “Do task A, and if the result is positive, execute B; if negative, execute C, and finally summarize D.” LLMs frequently lose context or ignore logical branches (if/else) and proceed directly.

As discussed in the design proposal for the [ZeroClaw] multi-agent architecture, especially in collaborative environments involving multiple agents, relying solely on prompts leads to the following issues:

Non-determinism: The LLM might choose different paths for the same input.
Debugging Difficulty: It’s hard to pinpoint which part of the prompt is causing errors when they occur.
Lack of Scalability: Adding new steps requires modifying the existing, massive prompt each time.

Solution: Graph-based Control Flow

The solution is to let the LLM decide “What” to do, and delegate “How” to execute it to an external state machine or graph workflow. This allows us to control the data flow and execution order between agents, rather than controlling the agents’ thinking process itself.

Building such a runtime in a stable language like Rust can achieve the high performance and reliability targeted by [ZeroClaw].

Implementation Example: Creating a Simple State Machine Runner with Rust

Without complex frameworks, let’s implement a simple agent workflow using Rust’s Enum. This code defines the steps (Step) an agent needs to perform and structures how the next step is determined based on the result of the previous one.

// 1. Define the agent's state and execution context
#[derive(Debug, Clone)]
struct AgentContext {
 current_data: String,
 step_count: usize,
}

// 2. Define each step of the workflow
enum WorkflowStep {
 Initialize,
 ProcessData,
 ValidateResult, // The next step is determined by the result
 Finalize,
 Complete,
}

// 3. Implement the execution logic for each step
impl WorkflowStep {
 fn execute(&self, ctx: &mut AgentContext) -> WorkflowStep {
 match self {
 WorkflowStep::Initialize => {
 println!("[Step 1] Initializing data...");
 ctx.current_data = "Sample Input Data".to_string();
 ctx.step_count += 1;
 WorkflowStep::ProcessData
 },
 WorkflowStep::ProcessData => {
 println!("[Step 2] Processing data via LLM: {}", ctx.current_data);
 // In a real scenario, this would involve calling an MCP client etc. for LLM inference
 ctx.current_data = format!("Processed: {}", ctx.current_data);
 ctx.step_count += 1;
 WorkflowStep::ValidateResult
 },
 WorkflowStep::ValidateResult => {
 println!("[Step 3] Validating result...");
 // Business logic: e.g., if the result length is less than 10, restart (or handle error)
 if ctx.current_data.len() < 10 {
 println!("Data is insufficient, returning to initialization step.");
 WorkflowStep::Initialize // Loop structure
 } else {
 println!("Validation passed. Moving to finalization step.");
 WorkflowStep::Finalize
 }
 },
 WorkflowStep::Finalize => {
 println!("[Step 4] Saving final result: {}", ctx.current_data);
 WorkflowStep::Complete
 },
 WorkflowStep::Complete => {
 println!("Workflow complete.");
 WorkflowStep::Complete // Maintain termination state
 }
 }
 }
}

// 4. Main execution loop (Runner)
fn run_agent_workflow() {
 let mut ctx = AgentContext {
 current_data: String::new(),
 step_count: 0,
 };
 
 let mut current_step = WorkflowStep::Initialize;
 
 // Prevent infinite loops with a maximum of 10 iterations (Safety Breaker)
 for _ in 0..10 {
 if matches!(current_step, WorkflowStep::Complete) {
 break;
 }
 current_step = current_step.execute(&mut ctx);
 }
}

fn main() {
 run_agent_workflow();
}

Benefits Gained from the Code

Even with a simple match statement and Enum as in the example above, the benefits are significant.

Clear Flow Visualization: You can understand how the system flows just by looking at the code. This greatly improves maintainability when handling complex requests, like in the [Discord MCP Gateway Architecture].
State Management: Memory state is explicitly managed through the AgentContext struct. Even if the LLM’s context window overflows, the Rust runtime accurately knows the current step.
Error Handling: When a specific step fails, you can easily transition to a Retry logic or a Fallback step at the code level, rather than retrying the prompt.

Conclusion: Agents are Software

We are moving past the era of treating LLMs as ‘magic’ and entering an era where LLMs are viewed as ‘a module.’ The trial and error experienced in projects like [Cloud Monitor] and [Improving LLM Settings] ultimately show that AI must be built upon a robust software architecture.

Instead of writing longer prompts, try building a runtime that clearly defines control flow using Rust or Python. You’ll feel the predictability of your agent’s behavior and the sturdiness of your system improve.

In the next post, we will discuss how to maximize performance by processing multiple LLM calls in parallel on top of this control flow.

The Evolution of Redis Arrays: An Architectural Analysis for Large-Scale Data Processing

Tue, 05 May 2026 09:00:52 +0900

The Evolution of Redis Arrays: An Architectural Analysis for Large-Scale Data Processing

Hello everyone! I recently came across an interesting article on Hacker News, written by Oran Agra, one of Redis’s core developers, titled “Redis array: short story of a long development process.” This wasn’t just a story about adding a new feature; it was a testament to the dedication of developers who tackled 25-year-old legacy code, ensuring performance, maintaining stability, and formatting a massive codebase overnight.

Today, based on this article, we’ll dive deep into how the Array data structure has evolved within Redis and what lessons we can learn for designing large-scale systems.

1. The Problem: The Shackle of 25-Year-Old Legacy Code

Redis’s LIST data structure internally uses QuickList. QuickList combines the advantages of ziplist and linkedlist, which are doubly linked lists. However, when dealing with massive lists containing tens of millions of elements, memory fragmentation and cache misses were causing significant performance degradation.

Specifically, when processing array-type data, the existing structure had the following bottlenecks:

Memory Overhead: Additional memory usage due to pointer connections.
Sequential Access Cost: Latency caused by inefficient use of cache lines.

To address this, the development team decided to overhaul the internal structure at the C language level. The biggest challenge here was the “legacy code that had to be changed.”

2. The Solution: Formatting a 25M-line Codebase

The most impressive part of the article was “Formatting a 25M-line codebase overnight.” The process of formatting and refactoring 25 million lines of code required more than just technical challenges; it demanded strategy akin to chess.

2.1. Preparations for Refactoring

The biggest fear in large-scale refactoring is “regression.” Modifying the array structure could affect hundreds of Redis commands (like LPUSH, RPUSH, LINDEX, etc.).

To mitigate this, the team adopted the following approach:

Expand Test Coverage: Ensure existing commands pass unit tests.
Strengthen CI/CD Pipeline: Implement benchmarking scripts to immediately detect performance degradation upon code changes.

2.2. The New Structure of Redis Arrays

The improved Array structure moved beyond simply allocating memory and was modified to maximize data locality. The core principle was “maximizing the use of contiguous memory blocks while allowing for segmentation and management when necessary.”

This yielded the following benefits:

Improved CPU Cache Hit Rate: Significantly increased L1/L2 cache hit rates due to contiguous memory access.
Memory Savings: Reduced actual data storage space by minimizing unnecessary pointer connections.

3. Practical Guide: Efficient Array Usage in Redis

Now that we’ve covered the theoretical background, let’s look at how to apply it in practice with code.

3.1. Problems with Existing List Usage

First, let’s consider the traditional way of adding tens of millions of items to a list. This operates based on QuickList, and as the number of items increases, the number of jumps also increases.

# Traditional Method (QuickList based)
# Add 10,000,000 items (potential for memory and speed degradation)
for i in {1..10000000}; do
 redis-cli LPUSH my_huge_list "item:$i"
done

3.2. Optimization using Streams and Hashes

While the internal improvements to Redis Arrays are transparent to users, when designing, we need to consider “data size” and “access patterns.” If simple sequential storage is all that’s needed, using the latest version of Redis alone will provide benefits.

However, if you need to search or modify data within the array, it’s advisable to use HASH instead of LIST.

import redis
import time

r = redis.Redis(host='localhost', port=6379, db=0)

# Scenario: Storing Log Data (Large Scale)
# 1. Using List (for sequential storage)
def push_to_list(count):
 start = time.time()
 for i in range(count):
 r.lpush("logs:timeline", f"log_entry_{i}")
 print(f"List pushed {count} items in {time.time() - start:.4f}s")

# 2. Using Hash (for search and modification)
def push_to_hash(count):
 start = time.time()
 pipe = r.pipeline()
 for i in range(count):
 pipe.hset("logs:details", f"entry_{i}", f"log_content_{i}")
 pipe.execute()
 print(f"Hash pushed {count} items in {time.time() - start:.4f}s")

if __name__ == "__main__":
 # Test inserting 100,000 data points
 push_to_list(100000)
 push_to_hash(100000)

Execution Result Analysis: In recent Redis versions (7.x and above), the internal Array structure is optimized, making LPUSH very fast. However, if you frequently need to retrieve data at a specific index, LINDEX has a complexity of O(N), making the O(1) approach using HGET much more advantageous.

4. Conclusion: The Harmony of Development Culture and Technology

The development process of Redis Arrays offers us important lessons:

Performance Isn’t Free: Improving 25-year-old code requires commensurate refactoring and testing costs.
Investment in Tools: This work was possible due to automated tools and a CI/CD environment capable of formatting 25 million lines of code.

When we design systems, we need to go beyond simply asking “Is it fast?” and consider “How can we achieve maintainable performance?” As the Redis team demonstrated, sometimes we must not shy away from large-scale improvements that shake the foundations of the architecture.

5. References

Thank you!

AgentForge Blog Automation Service: Full Architecture - From AI Comments to Translation and Post Generation

Tue, 05 May 2026 00:30:00 +0900

Running a blog involves three of the most tedious tasks: replying to comments, maintaining English translations, and consistently writing new posts. The AgentForge project automates all three with AI agents.

This post outlines the complete architecture of our blog automation service, which operates across two servers.

System Topology

┌─────────────────────┐ HTTPS ┌─────────────────────┐
│ arm1 server │ ──────────────▶ │ ec1 server │
│ (Agent Operator) │ │ (Blog Hosting) │
├─────────────────────┤ ├─────────────────────┤
│ blog-agent (:8081) │ │ Hugo (nginx) │
│ ├─ CommentHandler │ │ Blog API (:8000) │
│ ├─ TranslateHandler│ │ ├─ translator.py │
│ └─ PostGenerator │ │ ├─ blog_manager.py │
│ │ │ └─ git_handler.py │
│ NATS / PostgreSQL │ │ │
│ Prometheus / Grafana │ │ Git (yarang/blogs) │
└─────────────────────┘ └─────────────────────┘

Server	Role	Core Services
arm1	Agent Operator	`blog-agent.service` — Flask + Scheduler + LLM Client
ec1	Blog Hosting + API	Hugo (nginx) + `blog-api.service` (FastAPI)

Communication between the two servers is restricted to HTTPS API calls only. SSH access from arm1 to ec1 is blocked, so all integrations are done through the Blog API.

arm1: Unified Blog Agent

Why Unified?

Initially, comment response, translation, and post generation operated as separate processes (three systemd services). The issues were:

Using Claude Code CLI (--print) for calls resulted in a response time of 9.7 seconds and consumed 688MB of disk space.
Managing six systemd units was burdensome.
No state sharing between processes was possible.

By unifying these into one process and switching to direct LLM API calls, we achieved the following:

Metric	Before	After
Response Time	9.7s	1.7s
Disk Usage	688MB	~50MB
systemd Units	6	1
Processes	3	1

Architecture

class BlogAgent:
 """1 Process = Flask (webhook) + Scheduler (timer) + LLM Client"""
 
 def __init__(self):
 self.config = AgentConfig.from_credentials()
 self.llm = LLMClient(self.config) # ZAI glm-4.7
 self.api = BlogAPIClient(self.config) # ec1 Blog API
 
 # Handlers
 self.comment = CommentHandler(self.llm, self.config)
 self.translate = TranslateHandler(self.api)
 self.post_gen = PostGenerator(self.llm, self.api)
 
 # Scheduler
 self.scheduler = Scheduler()
 self.scheduler.every(hours=6, task=self.translate.check_and_sync)
 self.scheduler.daily_at(hour=9, task=self.post_gen.generate_and_publish)

Module Operations

1. CommentHandler — AI Comment Response

Receives Webhook events from GitHub Discussions to automatically generate AI comments.

[User Comment] → GitHub Webhook → arm1 Flask → CommentHandler
 → LLM Call (ZAI glm-4.7) → Generate Reply → Post Comment via GitHub API

Trigger: Webhook event-based (real-time)
Filtering: Skips blog owner comments and AI-generated comments.
Security: HMAC-SHA256 Webhook secret verification, Flask-Limiter applied.

2. TranslateHandler — Automatic Translation Trigger

Requests translation synchronization from ec1’s Blog API every 6 hours.

[Scheduler 6h] → TranslateHandler.check_and_sync()
 → POST /translate/sync → ec1 Blog API performs actual translation

arm1 does not perform the translation itself; it only sends a trigger to the ec1 API. The actual translation logic resides in translator.py on ec1.

3. PostGenerator — Automatic Post Generation

Automatically generates technical blog posts every day at 9 AM.

[Scheduler 09:00 KST] → PostGenerator.generate_and_publish()
 → Collect existing topics → Refer to RSS trends → Generate content with LLM
 → Deduplication Check → Publish via Blog API

Deduplication is key. It compares the similarity between new titles and the last 100 existing titles using difflib.SequenceMatcher:

def _is_duplicate_title(self, new_title, existing_titles):
 """Considers it a duplicate if the ratio is >= 0.6"""
 new_lower = new_title.lower().strip()
 for title in existing_titles[-100:]:
 ex_lower = title.lower().strip()
 ratio = difflib.SequenceMatcher(None, new_lower, ex_lower).ratio()
 if ratio >= 0.6:
 return True
 return False

ec1: Blog API Translation System

Transition to Gemini

Initially, translations were performed using ZAI (glm-4.7), but a critical issue arose:

glm-4.7 is a reasoning model, which first consumes its max_tokens budget for reasoning_content (internal thought process). If max_tokens=256, it uses all 256 tokens for reasoning, leaving the actual content as an empty string.

This led to an incident where nine English posts were translated with empty string titles.

Solution: Replaced with Gemini 2.5 Flash Lite.

Item	ZAI (Previous)	Gemini (Current)
Model	glm-4.7 (reasoning)	gemini-2.5-flash-lite
Translation Time	~30s/post	~8s/post
Cost	Paid API	Free (1,500 requests/day)
Empty Response Issue	Occurred	None

OpenAI-Compatible Endpoint

Gemini provides an OpenAI-compatible API. The existing code can be used without any changes by simply switching the base URL:

LLM_BASE_URLS = {
 "GEMINI": "https://generativelanguage.googleapis.com/v1beta/openai",
 "ZAI": "https://api.z.ai/api/coding/paas/v4",
}

Translation Matching Logic

Pairing Korean↔English posts uses date prefix matching:

ko: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
en: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
 ↑ Same prefix = Same post

Although the slugs might differ in language, if the YYYY-MM-DD-NNN part is the same, it’s recognized as the same post. The prerequisite for this method is that no two posts with the same date and number exist.

Title-in-Body Translation Technique

Translating the title via a separate API call caused issues with empty results from the reasoning model. The solution is to include the title as the first line of the body:

# When requesting translation
prompt = f"# {original_title}\n\n{original_body}"

# Extracting the title from the translation result
if translated.lstrip().startswith("# "):
 lines = translated.lstrip().split("\n", 1)
 extracted_title = lines[0].lstrip("# ").strip()
 translated_body = lines[1].lstrip("\n")

This translates the title and body simultaneously in a single API call, preserving context and saving tokens.

LLM Strategy: Role-Based Model Separation

Not all tasks are handled by a single LLM. Models are separated based on the nature of the task.

Task	Server	Model	Reason
AI Comment Response	arm1	ZAI glm-4.7	Conversational, excellent Korean quality
Post Generation	arm1	ZAI glm-4.7	Long-form content generation, creativity required
Translation (ko→en)	ec1	Gemini Flash Lite	Non-reasoning, fast and free

Core Principle: Do not use reasoning models for translation. Reasoning models consume tokens for internal thought processes, making non-reasoning models more suitable for simple conversion tasks.

Monitoring and Operations

Health Check Endpoints

# arm1 agent
curl http://arm1:8081/health
# → {"status":"healthy","agent":"blog-agent","scheduler_jobs":2,"uptime_sec":...}

curl http://arm1:8081/status
# → {"scheduler":[{"name":"auto-translate","last_run":...},{"name":"post-generator","last_run":"2026-05-04"}]}

# ec1 Blog API
curl https://blog.example.com/api/health
# → {"status":"healthy","version":"2.0.0"}

Observability Points

Metric	Normal Range	Alert Condition
arm1 uptime	>0	Service Down
scheduler_jobs	2	≠ 2
Translation Sync	ko post count = en post count	Discrepancy occurs
Post Generation	1 post daily	No posts for over 24 hours

Lessons Learned and Operational Tips

1. The Pitfall of Reasoning Models

It’s often not explicitly stated in documentation that max_tokens combines reasoning and content. If you get an empty response, check the finish_reason—if it’s "length", it indicates insufficient token budget.

2. Value of the OpenAI-Compatible Pattern

When switching translation providers from ZAI to Gemini, the code change was just one line for the base URL. Abstracting to an OpenAI-compatible interface from the start dramatically reduces LLM replacement costs.

3. Constraints of Date Prefix Matching

In the YYYY-MM-DD-NNN pattern, if two or more posts share the same date and number, translation matching will break. The PostGenerator must include logic to check the last number for that date and increment it when generating new posts.

4. Benefits of Process Consolidation

Consolidating three independent services into one resulted in:

State Sharing (LLM clients, configurations, API clients initialized only once)
Simplified Deployment (one systemd unit)
Easier Debugging (logs consolidated in one place)

Future Plans

Review the integration of arm1 agent’s LLM with Gemini.
Comment Quality Evaluation Pipeline (monitoring the appropriateness of auto-generated comments).
Automatic Translation Quality Verification (comparing with back-translation).
Expanding inter-agent collaboration through the AgentForge framework.

Blog automation aims not for “complete automation,” but for “minimal human intervention.” A structure where AI generates content, humans review it, and the system alerts operators to anomalies is the key to stable operation.

[Discord Decision MCP] Architecture Design Document

Mon, 02 Mar 2026 21:36:30 +0900

Discord Decision MCP — Architecture Design Document

1. Project Overview

1.1 Purpose

An MCP (Model Context Protocol) server that allows Claude Code, while operating in tmux Teammate mode for autonomous work, to ask questions via Discord when user decisions are needed and resume work after receiving responses.

1.2 Key Features

Feature	Description
One Bot per Project	Each project uses an independent Discord Bot
Infinite Wait Default	Wait for user response without timeout (Claude must not proceed unilaterally)
State Persistence	Restore waiting state after process restart
Korean-Friendly	Korean options, Yes/No response support
MCP-Based Communication	All Discord communication through MCP Tools

1.3 Version Information

Version: 1.0.0
Python Requirement: >= 3.11
MCP Framework: FastMCP >= 0.1.0

2. Directory Structure

discord-decision/
├── discord_mcp/ # Main package
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── config.py # Environment variable configuration
│ │
│ ├── bot/ # Discord API client
│ │ ├── __init__.py
│ │ ├── client.py # REST API client (httpx)
│ │ └── gateway.py # WebSocket gateway (receive only)
│ │
│ ├── decision/ # Decision request management
│ │ ├── __init__.py
│ │ ├── manager.py # Decision request lifecycle management
│ │ ├── poller.py # Discord polling and response waiting
│ │ ├── parser.py # User response parsing
│ │ └── state.py # State persistence (JSON files)
│ │
│ ├── tools/ # MCP Tools implementation
│ │ ├── __init__.py
│ │ ├── ask.py # discord_ask_decision
│ │ ├── notify.py # discord_notify
│ │ ├── report.py # discord_report_progress
│ │ ├── status.py # discord_check_pending
│ │ ├── inbox.py # discord_read_inbox, discord_clear_inbox
│ │ └── _templates.py # Discord message templates
│ │
│ └── daemon/ # Watcher daemon
│ ├── __init__.py
│ ├── watcher.py # Discord channel monitoring (discord-watch CLI)
│ └── inbox.py # Inbox file management
│
├── scripts/ # Utility scripts
│ └── start-discord-watch.sh
│
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_parser.py
│ └── test_state.py
│
├── CLAUDE.md # Claude Code project instructions
├── README.md # Project description
├── pyproject.toml # Project configuration and dependencies
└── mcp.json.example # MCP configuration example

3. Key Module Descriptions

3.1 Server Entry Point (`server.py`)

Role: FastMCP server creation and MCP Tool registration

mcp = FastMCP(name="discord-decision-mcp")
# Tool registration
mcp.tool()(discord_ask_decision)
mcp.tool()(discord_notify)
mcp.tool()(discord_report_progress)
mcp.tool()(discord_check_pending)
mcp.tool()(discord_read_inbox)
mcp.tool()(discord_clear_inbox)

Execution:

discord-mcp # or python -m discord_mcp.server

3.2 Configuration Management (`config.py`)

Role: Load configuration values from environment variables

Environment Variable	Description	Default
`DISCORD_BOT_TOKEN`	Discord Bot Token (includes “Bot " prefix)	Required
`DISCORD_CHANNEL_ID`	Default question channel ID	Required
`PROJECT_NAME`	Used for question_id generation	“project”
`PENDING_DIR`	State file storage path	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling interval (seconds)	5

3.3 Discord API Client (`bot/`)

3.3.1 REST API Client (`client.py`)

Role: Discord REST API calls (httpx-based)

Key Methods:

class DiscordClient:
 async def send_message(channel_id, content, embeds=None)
 async def get_messages(channel_id, after=None, limit=50)
 async def create_thread(channel_id, name, first_message)
 async def archive_thread(thread_id)

Features:

Automatic rate limit handling (retry on 429 response)
Singleton pattern (get_client())

3.3.2 WebSocket Gateway (`gateway.py`)

Role: Discord Gateway WebSocket connection (receive only)

Features:

Real-time MESSAGE_CREATE event reception
Reduces polling delay from 5 seconds to instant
System works without Gateway (polling fallback)
Automatic reconnection (Exponential backoff)

class GatewayClient:
 async def run() # Start event reception
 async def stop() # Close connection

3.4 Decision Request Management (`decision/`)

3.4.1 DecisionManager (`manager.py`)

Role: Coordinate the entire lifecycle of decision requests

class DecisionManager:
 async def ask(question, context, options, timeout_seconds, thread_id) -> PollResult
 async def restore_pending() -> list[DecisionState]

Flow:

Check for duplicate questions
Create thread (or reuse existing thread)
Create state file (~/.claude/pending_decisions/{question_id}.json)
Run poller to wait for response
Mark disconnected state on SIGHUP signal

3.4.2 DecisionPoller (`poller.py`)

Role: Poll Discord channel and wait for response

class DecisionPoller:
 async def wait(state: DecisionState) -> PollResult

Features:

Default: infinite wait (timeout_seconds=None)
Real-time waiting status display in tmux pane (ANSI escape)
Re-question up to 2 times for ambiguous responses

3.4.3 Response Parser (`parser.py`)

Role: Parse user Discord responses

Supported Patterns:

Option matching: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
Affirmative/Negative: “yes”, “네”, “예”, “no”, “아니요”
Natural language: 15+ characters or 3+ Korean characters

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str # Generate re-question message

3.4.4 State Store (`state.py`)

Role: Persist decision request state to JSON files

State File Location: ~/.claude/pending_decisions/{question_id}.json

class DecisionState(BaseModel):
 question_id: str
 project: str
 question: str
 context: str
 options: list[str]
 timeout_seconds: float | None
 thread_id: str
 message_id: str
 asked_at: str
 status: Literal["pending", "disconnected", "resolved", "aborted", "timeout"]
 clarify_attempts: int
 resolved_at: str | None
 resolution: str | None
 selected_option: str | None

class StateStore:
 def save(state: DecisionState)
 def load(question_id: str) -> DecisionState | None
 def load_all_pending() -> list[DecisionState]
 def resolve(question_id, resolution, selected_option)
 def is_duplicate(question: str) -> bool

3.5 MCP Tools (`tools/`)

Tool	Blocking	Description
`discord_ask_decision`	✅	User decision request
`discord_notify`	❌	Progress notification
`discord_report_progress`	❌	Task completion report
`discord_check_pending`	❌	Check pending questions
`discord_read_inbox`	❌	Inbox message query
`discord_clear_inbox`	❌	Inbox message deletion

3.6 Watcher Daemon (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

Role: Monitor Discord channel and record new messages to inbox file

Execution:

discord-watch --interval 10
# or
tmux new-session -d -s discord-watch 'uv run discord-watch'

Features:

Periodically poll specified channel(s)
Record new user messages to inbox
Display status in tmux pane

3.6.2 InboxStore (`inbox.py`)

Role: JSON file-based storage for Discord messages

Inbox File Location: ~/.claude/discord_inbox.json

class InboxMessage:
 message_id: str
 channel_id: str
 thread_id: str | None
 author: str
 author_id: str
 content: str
 timestamp: str
 read: bool

class InboxStore:
 def add_message(msg: InboxMessage)
 def get_unread() -> list[InboxMessage]
 def mark_read(message_id: str)
 def clear_read() # Delete read messages

4. Data Flow Diagrams

4.1 Decision Request Flow

┌─────────────────┐
│ Claude Code │
└────────┬────────┘
 │ discord_ask_decision()
 ▼
┌─────────────────────────────────────┐
│ MCP Server (server.py) │
│ ┌───────────────────────────────┐ │
│ │ DecisionManager.ask() │ │
│ │ 1. Duplicate check │ │
│ │ 2. Thread creation │ │
│ │ 3. State file save │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 ▼
┌─────────────────────────────────────┐
│ DecisionPoller.wait() │
│ ┌───────────────────────────────┐ │
│ │ Polling loop │ │
│ │ 1. tmux status update │ │
│ │ 2. Discord API call │ │
│ │ 3. Response parsing │ │
│ │ 4. Re-question if ambiguous │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 │
 ┌─────────┴─────────┐
 ▼ ▼
┌───────────────────┐ ┌──────────────────┐
│ Discord REST API │ │ Discord Thread │
│ (client.py) │ │ │
└───────────────────┘ └────────┬─────────┘
 │
 ┌────────▼────────┐
 │ User Response │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ parser.py │
 │ - Option match │
 │ - Ambiguity │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ store.resolve()│
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ PollResult │
 │ Return │
 └─────────────────┘

4.2 Watcher Daemon Flow

┌─────────────────────────────────────────────┐
│ DiscordWatcher (daemon/watcher.py) │
│ ┌───────────────────────────────────────┐ │
│ │ 1. Set initial message ID │ │
│ │ 2. Periodic polling (default 10s) │ │
│ │ 3. Detect new messages │ │
│ │ 4. InboxStore.add_message() │ │
│ └───────────────────┬───────────────────┘ │
└──────────────────────┼──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ ~/.claude/discord_inbox.json │
│ { │
│ "last_message_id": "...", │
│ "messages": [ │
│ { "message_id": "...", ... } │
│ ] │
│ } │
└──────────────────────┬──────────────────────┘
 ▲
 │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────┘

4.3 Session Restoration Flow

┌─────────────────────────────────────────────┐
│ Claude Code session start │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ discord_check_pending() │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ DecisionManager.restore_pending() │
│ ┌───────────────────────────────────────┐ │
│ │ 1. ~/.claude/pending_decisions/*.json │ │
│ │ 2. Check Thread via Discord API │ │
│ │ 3. If answered → Auto-resolve │ │
│ │ 4. If no answer → Restart notification│ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

5. MCP Tools List

5.1 discord_ask_decision

Description: Send question to Discord Thread and wait for response when user decision is needed (blocking)

Parameters:

Name	Type	Required	Description
`question`	string	✅	Question content
`context`	string	✅	Current work context
`options`	string[]	❌	List of options (empty array for free response)
`timeout_seconds`	float	❌	Wait timeout (null for infinite wait)
`thread_id`	string	❌	Existing Thread ID (null to create new Thread)

Return Value:

{
 "success": true,
 "answer": "A) Execute now",
 "selected_option": "A) Execute now",
 "question_id": "project_20260301_abc123",
 "timed_out": false,
 "aborted": false
}

5.2 discord_notify

Description: Send progress notification to Discord (non-blocking)

Parameters:

Name	Type	Required	Description
`message`	string	✅	Notification message
`level`	string	❌	info/warning/success/error (default: info)
`thread_id`	string	❌	Thread ID to send to (null for default channel)

5.3 discord_report_progress

Description: Report task completion or milestone completion (non-blocking)

Parameters:

Name	Type	Required	Description
`title`	string	✅	Report title
`summary`	string	✅	Task result summary
`details`	string[]	❌	List of detail items
`thread_id`	string	❌	Thread ID to send to

5.4 discord_check_pending

Description: Check pending questions at session start (non-blocking)

Parameters: None

Return Value:

{
 "has_pending": true,
 "pending_questions": [
 {
 "question_id": "project_20260301_abc123",
 "question": "Deploy?",
 "thread_id": "1234567890",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending"
 }
 ]
}

5.5 discord_read_inbox

Description: Query messages stored in Inbox (non-blocking)

Parameters:

Name	Type	Default	Description
`unread_only`	boolean	true	Return only unread messages
`mark_read`	boolean	false	Mark queried messages as read

5.6 discord_clear_inbox

Description: Delete Inbox messages (non-blocking)

Parameters:

Name	Type	Default	Description
`read_only`	boolean	true	Delete only read messages

6. Dependency Information

6.1 Core Dependencies

Package	Version	Purpose
`fastmcp`	>= 0.1.0	MCP server framework
`httpx`	>= 0.27.0	Async HTTP client
`websockets`	>= 12.0	WebSocket client
`python-dotenv`	>= 1.0.0	Environment variable loading
`pydantic`	>= 2.0.0	Data model validation
`anyio`	>= 4.0.0	Async execution

6.2 Development Dependencies

Package	Purpose
`pytest`	Test framework
`pytest-asyncio`	Async test support
`pytest-mock`	Mock support
`respx`	httpx mocking

6.3 CLI Commands

discord-mcp # Run MCP server
discord-watch # Run watcher daemon

7. State File Format

7.1 Decision State File

Location: ~/.claude/pending_decisions/{question_id}.json

{
 "question_id": "project_20260301_abc123",
 "project": "my-project",
 "question": "Run DB migration?",
 "context": "v1→v2 schema change",
 "options": ["A) Execute now", "B) Staging first", "C) Hold"],
 "timeout_seconds": null,
 "thread_id": "1234567890",
 "message_id": "0987654321",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending",
 "clarify_attempts": 0,
 "resolved_at": null,
 "resolution": null,
 "selected_option": null
}

7.2 Inbox File

Location: ~/.claude/discord_inbox.json

{
 "last_message_id": "1234567890",
 "messages": [
 {
 "message_id": "1234567890",
 "channel_id": "1234567890",
 "thread_id": null,
 "author": "username",
 "author_id": "1234567890",
 "content": "Message content",
 "timestamp": "2026-03-01T00:00:00Z",
 "read": false
 }
 ]
}

8. Architecture Principles

8.1 Design Principles

Singleton Pattern: DiscordClient, StateStore, InboxStore are module-level singletons
State Persistence: All decision request states are persisted to files
Infinite Wait Default: Timeout default is None so Claude does not proceed unilaterally
Re-question Limit: Ambiguous responses are re-asked up to 2 times
Rate Limit Handling: Automatic wait and retry on Discord API 429 responses

8.2 Error Handling

Situation	Handling
Discord API 429	Automatic wait and retry (max 5 times)
WebSocket disconnection	Reconnect with exponential backoff
Response parsing failure	Re-question up to 2 times then abort
Timeout occurrence	Send abort notification and set aborted state
Session disconnect (SIGHUP)	Save as disconnected state

Document Version: 1.0.0 Last Modified: 2026-03-02

Korean Version: 한국어 버전

[ZeroClaw] 2026 H1 Roadmap Meeting

Sat, 28 Feb 2026 09:55:15 +0900

ZeroClaw 2026 H1 Roadmap Team Meeting Minutes

Meeting Date: 2026-02-28 Attendees: Architect, Security Lead, Product Owner, DevOps Lead Location: ZeroClaw Development Team Meeting Room Author: ZeroClaw Team

1. Meeting Overview

This meeting was held to discuss ZeroClaw’s 2026 first-half development direction and establish roadmaps and priorities for each area.

1.1 Agenda

Multi-agent architecture development direction
Security enhancement and compliance response
Product competitiveness enhancement and UX improvement
DevOps and infrastructure advancement
Comprehensive roadmap and priority agreement

2. Architecture Development Discussion

2.1 Architect Statement

“ZeroClaw has completed Phase 1 (in-process delegation) and is currently implementing Phase 2 (file-based multi-agent). The following technical goals need to be achieved in the first half of 2026.”

2.1.1 Multi-Agent Orchestration Advancement

Proposals:

Implement DAG-based workflow execution engine
Support sequential/parallel/conditional/loop execution patterns
Improve agent task distribution algorithm

Priority: High (P1)

// Proposed workflow structure
pub struct Workflow {
 pub id: String,
 pub nodes: Vec<WorkflowNode>,
 pub edges: Vec<WorkflowEdge>,
 pub start_node: String,
 pub end_nodes: Vec<String>,
 pub error_handling: ErrorHandlingPolicy,
}

2.1.2 IPC Communication Protocol Improvement

Proposals:

Transition from stdout-based communication to structured IPC
Support multiple transport layers: Unix Socket, gRPC, WebSocket
Optimize message serialization (JSON → MessagePack/CBOR)

Priority: Medium (P2)

2.1.3 Extensibility and Modularization

Proposals:

Consider plugin architecture introduction
Implement Wasm execution mode (enhanced sandboxing)
Provide external agent registration API

Priority: Low (P3)

2.1.4 Performance Optimization

Proposals:

Zero-copy message passing
Connection pooling and caching strategies
Async I/O optimization

Priority: Medium (P2)

2.2 Discussion

Security Lead:

“Security channels must be applied first when improving IPC protocol. Encryption and authentication for inter-agent communication are needed.”

Product Owner:

“From a user perspective, agent definitions should be more intuitive. Let’s also consider simplifying the YAML schema.”

DevOps Lead:

“Performance optimization work should proceed in parallel with observability improvement. Metrics collection must be secured first to measure optimization effects.”

3. Security Development Discussion

3.1 Security Lead Statement

“ZeroClaw already has a strong security foundation, but there are areas that need improvement from an OWASP Top 10 perspective. Sandbox isolation and audit logging enhancement are particularly urgent.”

3.1.1 Sandbox Enhancement

Current Issues:

Docker sandbox: --read-only, --cap-drop, seccomp not applied
Firejail: Network isolation not applied (--net=none missing)

Proposals:

// Docker hardened profile
docker_cmd.args([
 "run", "--rm",
 "--read-only",
 "--security-opt", "no-new-privileges",
 "--cap-drop", "ALL",
 "--network", "none",
 "--memory", "256m",
 "--pids-limit", "64",
]);

Priority: High (P1)

3.1.2 Audit Logging Enhancement

Proposals:

Introduce Log Signing to prevent tampering
Real-time security alert webhook integration
Prometheus metrics exposure

Priority: Medium (P2)

3.1.3 SSRF Defense

Proposals:

Enforce HTTPS for external requests
Block private IP ranges
Strengthen domain allowlist validation

Priority: Medium (P2)

3.1.4 TOCTOU Vulnerability Fix

Proposals:

Perform path validation and normalization atomically
Prevent symbolic link race conditions

Priority: High (P1)

3.2 Discussion

Architect:

“Sandbox enhancement can provide stronger isolation when linked with Wasm execution mode.”

DevOps Lead:

“Prometheus metrics can greatly improve operational visibility when integrated with Grafana dashboards.”

Product Owner:

“Ensure that security enhancements don’t degrade user experience. Defaults should be secure while advanced users can configure flexibly.”

4. Product Development Discussion

4.1 Product Owner Statement

“ZeroClaw’s core values are ‘high performance’, ’extensibility’, and ‘security’. In the first half of 2026, we need to strengthen these while improving user experience.”

4.1.1 User Experience Improvement

CLI Improvements:

Improve zeroclaw agent list output (table format)
Interactive agent execution mode
Progress visualization

Configuration Simplification:

Simplify agent definition YAML schema
Provide sensible defaults
Improve configuration validation and error messages

Priority: High (P1)

4.1.2 Documentation and Onboarding Enhancement

Proposals:

Improve Quickstart guide
Auto-generate API reference documentation
Expand example scenarios
Multi-language documentation (Korean, Japanese, Chinese)

Priority: Medium (P2)

4.1.3 Community Growth Strategy

Proposals:

Improve CONTRIBUTING.md
Label good first issues
Publish regular release notes
Discord/Slack community channels

Priority: Medium (P2)

4.1.4 Differentiation Points Enhancement

Proposals:

Strengthen hardware peripheral support (STM32, RPi)
Specialized domain agent templates
Publish performance benchmarks

Priority: Low (P3)

4.2 Discussion

Architect:

“CLI improvement is important from an ergonomics perspective. Let’s also consider upgrading from structopt to clap 4.x.”

Security Lead:

“When writing multi-language documentation, accurate translation of security-related content is important. I recommend creating a terminology glossary first.”

DevOps Lead:

“For community channels, starting with GitHub Discussions is a good approach. It can be started without separate infrastructure.”

5. DevOps Development Discussion

5.1 DevOps Lead Statement

“We need to advance CI/CD pipelines and monitoring systems for stable deployment and operation.”

5.1.1 CI/CD Pipeline Advancement

Current Status:

GitHub Actions-based CI
Automated cargo fmt, clippy, test
Docker build

Proposals:

Integrate cargo audit (vulnerability scanning)
Cross-platform build (Linux, macOS, Windows)
Release automation (cargo-release)
Pre-deployment smoke tests

Priority: High (P1)

# Proposed CI workflow
- name: Security audit
 run: cargo audit

- name: Cross-platform build
 strategy:
 matrix:
 os: [ubuntu-latest, macos-latest, windows-latest]
 runs-on: ${{ matrix.os }}

5.1.2 Monitoring and Observability

Proposals:

Prometheus metrics endpoint
Grafana dashboard templates
Distributed tracing (OpenTelemetry)
Log aggregation (ELK/Loki)

Priority: Medium (P2)

5.1.3 Deployment Automation and Rollback

Proposals:

Blue-Green deployment support
Automatic rollback threshold settings
Canary release options

Priority: Medium (P2)

5.1.4 Development Environment Improvement

Proposals:

devcontainer configuration
Automatic git hooks setup
Development configuration profiles

Priority: Low (P3)

5.2 Discussion

Architect:

“OpenTelemetry integration is essential for multi-agent tracing. Inter-agent call chains must be visualizable.”

Security Lead:

“cargo audit must be included in CI. It’s also good to add dependency license checks.”

Product Owner:

“devcontainer will be very helpful for new contributor onboarding. We can raise its priority.”

6. Comprehensive Roadmap and Priorities

6.1 2026 First Half Roadmap

Q1 (March-April)

Item	Owner	Priority
Docker/Firejail sandbox enhancement	Security	P1
TOCTOU vulnerability fix	Security	P1
CI/CD security scan integration	DevOps	P1
CLI improvement and UX enhancement	Product	P1
DAG-based workflow engine	Architect	P1

Q2 (May-June)

Item	Owner	Priority
IPC communication protocol improvement	Architect	P2
Audit logging enhancement	Security	P2
SSRF defense implementation	Security	P2
Prometheus metrics exposure	DevOps	P2
Documentation and onboarding improvement	Product	P2
Community infrastructure building	Product	P2

6.2 Agreed Principles

Security First: All new features must go through security review
Gradual Deployment: Large changes are rolled out in stages
Rollback Capable: All changes must be easily rollbackable
Documentation Sync: Documentation updates required when features change
Test Coverage: Tests required for new code

6.3 Risks and Responses

Risk	Probability	Impact	Response
Sandbox compatibility issues	Medium	High	Implement fallback mechanism
Performance regression	Low	Medium	Automate benchmarks
Dependency vulnerabilities	Medium	High	Automate cargo audit
Poor documentation	High	Medium	Require documentation PRs

7. Conclusion and Next Steps

7.1 Meeting Conclusions

Architecture: Prioritize multi-agent orchestration advancement
Security: Immediately start sandbox enhancement and TOCTOU fix
Product: Improve user experience through CLI UX improvement
DevOps: Build CI/CD security enhancement and monitoring foundation

7.2 Action Items

#	Item	Owner	Due Date
1	Apply Docker sandbox security profile	Security Lead	2026-03-07
2	Fix TOCTOU path validation	Security Lead	2026-03-10
3	Integrate CI cargo audit	DevOps Lead	2026-03-05
4	Improve CLI agent list	Product Owner	2026-03-12
5	Workflow engine design document	Architect	2026-03-15

7.3 Next Meeting Schedule

Date: 2026-03-14 10:00
Agenda: Q1 progress review and Q2 detailed planning

Appendix: Reference Documents

docs/project/multi-agent-architecture-design.md - Multi-agent architecture design
docs/project/multi-agent-communication-protocols.md - Communication protocol design
docs/security/security-improvements.md - Security improvement report
CLAUDE.md - Engineering protocol

Meeting Minutes Date: 2026-02-28 Approved By: ZeroClaw Team Lead Distribution: ZeroClaw Development Team

Korean Version: 한국어 버전

[ZeroClaw] Multi-Agent Architecture Design

Fri, 27 Feb 2026 22:58:08 +0900

ZeroClaw Multi-Agent Architecture Design

Overview

ZeroClaw’s multi-agent architecture implements an advanced collaboration system evolving from a single-agent model.

Current Status

Phase 1: In-Process Delegation (Complete)
Phase 2: File-Based Multi-Agent Architecture (In Development)

1. Design Philosophy

Principle	Application
KISS	Simple communication protocol
YAGNI	Implement only essential features
SRP	Single responsibility agents
Secure	Least privilege principle

2. Architecture Structure

Application Layer: Research │ Code │ Test Agent
Message Bus Layer: NATS/Redis Pub/Sub
Transport Layer: gRPC │ WebSocket │ Unix Socket

3. Agent Definition

agent:
 id: "researcher"
 name: "Research Agent"

execution:
 mode: subprocess

provider:
 name: "openrouter"
 model: "claude-sonnet-4-6"

4. CLI Commands

zeroclaw agent list
zeroclaw agent show <id>
zeroclaw agent run --agent-id researcher

5. Security

Mode	Isolation	Use Case
Subprocess	Process	Trusted agents
Docker	Container	File operations
Wasm	Memory	High security

Korean Version: 한국어 버전

[Multi-Agent] File-Based Architecture Design

Fri, 27 Feb 2026 09:30:57 +0900

File-Based Multi-Agent Architecture Design

Status: Design Proposal
Author: multi-agent-architect
Date: 2026-02-24
Type: Alternative Architecture (Process-Per-Agent)

Executive Summary

This document defines a file-based, process-per-agent architecture where each agent is defined as a separate configuration file and runs as an independent process. Agents are invoked on-demand and report results back to a main coordinator agent.

Core Principles

File-Based Agent Definition: Each agent is a .toml file in agents/
Process Isolation: Each agent runs in its own process
On-Demand Invocation: Main agent spawns subprocess agents as needed
Reporting Protocol: Structured result reporting via IPC
Zero-Config Discovery: Auto-discovery of agent definitions

1. Agent Definition File Structure

1.1 Directory Layout

~/.zeroclaw/
├── config.toml # Main configuration
├── agents/ # Agent definitions directory
│ ├── researcher.toml # Research agent
│ ├── coder.toml # Code generation agent
│ ├── tester.toml # Testing agent
│ ├── reviewer.toml # Code review agent
│ └── summarizer.toml # Summarization agent
├── agents.d/ # Optional: additional agent dirs
│ └── custom/
│ └── my_agent.toml
└── workspace/ # Shared workspace

1.2 Agent File Schema

# agents/researcher.toml

# Agent metadata
[agent]
id = "researcher"
name = "Research Agent"
version = "1.0.0"
description = "Conducts research on given topics using web search and knowledge bases"

# Execution configuration
[agent.execution]
# How to run this agent: "subprocess" | "wasm" | "docker"
mode = "subprocess"

# Command to spawn (template variables: {agent_id}, {workspace}, {config_dir})
command = "zeroclaw"
args = [
 "agent",
 "run",
 "--agent-id", "{agent_id}",
 "--config", "{config}/agents/researcher.toml",
 "--workspace", "{workspace}"
]

# Working directory for the subprocess
working_dir = "{workspace}"

# Environment variables for the subprocess
[agent.execution.env]
ZEROCLAW_AGENT_MODE = "worker"
ZEROCLAW_AGENT_ID = "researcher"

# Provider configuration (overrides main config)
[provider]
name = "openrouter"
model = "anthropic/claude-sonnet-4-6"
api_key = null # Inherit from main, or set agent-specific key
temperature = 0.3
max_tokens = 4096

# Tools available to this agent
[[tools]]
name = "web_search"
enabled = true

[[tools]]
name = "web_fetch"
enabled = true

# Tools explicitly denied to this agent
[[tools.deny]]
name = "shell"
reason = "Research agent should not execute shell commands"

# System prompt
[system]
prompt = """
You are a Research Agent. Your role is to:
1. Search for and gather information from credible sources
2. Synthesize findings into structured reports
3. Cite sources and provide references
4. Avoid speculation - stick to verified information
"""

# Memory configuration
[memory]
backend = "shared" # "shared" | "isolated"
category = "research"

# Reporting configuration
[reporting]
mode = "ipc"
format = "json" # "json" | "markdown" | "both"
timeout_seconds = 300

# Retry configuration
[retry]
max_attempts = 3
backoff_ms = 1000

2. Agent Registry

The AgentRegistry discovers and manages agent definitions:

pub struct AgentRegistry {
 agents_dir: PathBuf,
 agents: HashMap<String, AgentDefinition>,
 security: Arc<SecurityPolicy>,
}

impl AgentRegistry {
 pub fn new(agents_dir: PathBuf, security: Arc<SecurityPolicy>) -> Result<Self>;
 pub fn discover(&mut self) -> Result<()>;
 pub fn get(&self, id: &str) -> Option<&AgentDefinition>;
 pub fn list(&self) -> Vec<String>;
}

3. Inter-Process Communication (IPC)

Task Message (Main → Agent)

pub struct AgentTask {
 pub task_id: String,
 pub from_agent: String,
 pub to_agent: String,
 pub prompt: String,
 pub context: HashMap<String, serde_json::Value>,
 pub input: Option<serde_json::Value>,
 pub timestamp: chrono::DateTime<chrono::Utc>,
 pub deadline: Option<chrono::DateTime<chrono::Utc>>,
}

Result Message (Agent → Main)

pub struct AgentResult {
 pub task_id: String,
 pub agent_id: String,
 pub status: AgentStatus,
 pub data: Option<serde_json::Value>,
 pub output: String,
 pub error: Option<String>,
 pub metrics: AgentMetrics,
 pub artifacts: Vec<Artifact>,
 pub timestamp: chrono::DateTime<chrono::Utc>,
}

4. Security Considerations

Execution Mode	Isolation	Use Case
Subprocess	Process-level	Trusted agents
Docker	Container	Untrusted, file operations
Wasm	Memory-only	High security needs

5. CLI Commands

# List available agents
zeroclaw agent list

# Show agent details
zeroclaw agent show <agent_id>

# Run an agent directly (for testing)
zeroclaw agent run --agent-id researcher --prompt "Research X"

# Create a new agent from template
zeroclaw agent create --id my-agent --name "My Agent"

# Validate agent definition
zeroclaw agent validate <agent_id>

6. Success Criteria

Agent definition files validated on load
Subprocess agents spawn and complete tasks
IPC protocol supports tasks >1GB data
Main agent can invoke worker agents via tool
Failed agents don’t crash main agent
Security policy enforced per-agent
CLI commands for agent management

Korean Version: 한국어 버전

[ZeroClaw] Codebase Architecture Analysis

Thu, 26 Feb 2026 10:07:29 +0900

ZeroClaw Codebase Architecture Analysis Report

Written on February 26, 2026

Overview

ZeroClaw is a high-performance autonomous agent runtime written in Rust. This report summarizes the analysis of the codebase structure and security architecture.

1. Core Architecture Patterns

ZeroClaw adopts trait-driven extensibility as its core design principle.

1.1 Major Traits (7)

Trait	Location	Role
`Provider`	src/providers/traits.rs	AI model provider interface
`Channel`	src/channels/traits.rs	Communication channel interface
`Tool`	src/tools/traits.rs	Tool execution interface
`Memory`	src/memory/traits.rs	Memory backend interface
`Observer`	src/observability/traits.rs	Observability interface
`RuntimeAdapter`	src/runtime/traits.rs	Runtime adapter interface
`Peripheral`	src/peripherals/traits.rs	Hardware peripheral interface

2. Security Architecture

ZeroClaw implements security through a Defense-in-Depth strategy.

2.1 Security Layers (6)

SecurityPolicy Core - Autonomy level management
Gateway Security - Bearer token authentication
Tool Validation - Injection prevention
Runtime Sandbox - Landlock/Firejail/Docker
Secret Management - ChaCha20-Poly1305
Audit Logging - Event tracking

2.2 Core Security Boundaries

Command allowlist: 15 items
Rate limiting: 20 requests/hour
Environment variables: only 8 allowed

3. Multi-Agent System

Implementation Roadmap

Phase	Duration	Content
1	1 week	Core traits, DelegateTool extension
2	2-3 weeks	Docker/Wasm execution modes
3	4+ weeks	Distributed message bus, consensus algorithm

Conclusion

ZeroClaw has an excellent architecture in terms of extensibility, security, performance, and maintainability.

This report was written based on collaborative analysis by the ZeroClaw development team.

Korean Version: 한국어 버전

[Multi-Agent] Communication Platform Design

Sat, 21 Feb 2026 21:00:00 +0900

Introduction

As AI agent systems evolve, the transition from single-agent to multi-agent systems is accelerating. This article explores how to design a platform architecture for efficient communication between multiple agents.

1. Architecture Overview

A multi-agent platform consists primarily of an Orchestrator, Message Bus, and various specialized agents.

Multi-Agent Architecture

Core Components

Component	Role
Orchestrator	Task coordination, agent scheduling
Message Bus	Inter-agent communication relay
State Store	Shared state management
Task Queue	Priority-based work queue
Agents	Specialized task execution

2. Communication Protocol Design

Inter-agent communication is designed based on asynchronous message passing.

Message Protocol

Communication Flow

Publish: Agent publishes task request to message bus
Route: Bus routes message to appropriate agent
Accept: Target agent accepts task
Acknowledge: Bus sends acceptance confirmation to requester
Execute: Agent performs actual work
Result: Result is published to bus
Deliver: Bus delivers result to requester

3. Message Structure

Design scalable and type-safe message structures.

Message Structure

Message Envelope

{
 "header": {
 "message_id": "uuid-v4",
 "timestamp": "2026-02-21T12:00:00Z",
 "source_agent": "agent-research-01",
 "target_agent": "agent-writer-01",
 "message_type": "TASK_REQUEST"
 },
 "metadata": {
 "priority": "normal",
 "ttl": 3600,
 "correlation_id": "parent-uuid"
 },
 "payload": {
 "content_type": "json",
 "encoding": "utf-8",
 "data": {
 "task": "summarize",
 "content": "..."
 }
 }
}

Message Types

Type	Purpose
`TASK_REQUEST`	Task request
`TASK_RESULT`	Task result
`STATUS_UPDATE`	Status change notification
`HEARTBEAT`	Liveness check
`QUERY`	Information lookup
`RESPONSE`	Query response

4. Agent State Management

Each agent has a clear state machine.

State Management

State Transitions

IDLE → RECEIVING → PROCESSING → EXECUTING → COMPLETED → IDLE
 ↘ ↘ ↘
 ERROR ──────→ retry ──→ IDLE

State Behaviors

State	Behavior
IDLE	Waiting for new task
RECEIVING	Message reception and validation
PROCESSING	Task analysis and preparation
EXECUTING	Actual work execution
COMPLETED	Result transmission and cleanup
ERROR	Error handling and retry

5. Communication Patterns

5.1 Request-Response

Synchronous 1:1 communication pattern.

# Request
response = await bus.request(
 target="agent-code-01",
 message=TaskRequest(task="generate_code", spec={...}),
 timeout=30
)

# Response
return TaskResult(status="success", data=generated_code)

Asynchronous 1:N communication pattern.

# Subscribe
@bus.subscribe("research.completed")
async def handle_research_result(message):
 # Handle research result
 pass

# Publish
await bus.publish(
 topic="research.completed",
 message=ResearchResult(data={...})
)

5.3 Broadcast

Used to send notifications to all agents.

# Broadcast
await bus.broadcast(
 message=SystemAlert(
 level="warning",
 message="High load detected"
 )
)

6. Core Design Principles

6.1 Loose Coupling

Agents should not know each other’s internal implementations. They communicate only through message interfaces.

6.2 Fault Tolerance

class Agent:
 async def execute_with_retry(self, task, max_retries=3):
 for attempt in range(max_retries):
 try:
 return await self.execute(task)
 except Exception as e:
 if attempt == max_retries - 1:
 await self.transition_to(State.ERROR)
 raise
 await asyncio.sleep(2 ** attempt) # Exponential backoff

6.3 Scalability

Horizontal scaling: Add agents with the same role
Load balancing: Automatic distribution by message bus
Sharding: Separate agent groups by task type

6.4 Observability

# Metrics collection
@metrics.track
async def process_message(self, message):
 with metrics.timer("process_duration"):
 result = await self.handle(message)
 metrics.increment("messages_processed")
 return result

7. Implementation Considerations

7.1 Message Serialization

Format	Pros	Cons
JSON	Readability, compatibility	Size, performance
Protocol Buffers	Performance, schema	Complexity
MessagePack	JSON compatible, size	Tool support

7.2 Backpressure

class Agent:
 def __init__(self, max_concurrent=10):
 self.semaphore = asyncio.Semaphore(max_concurrent)

 async def process(self, message):
 async with self.semaphore:
 return await self.handle(message)

7.3 Dead Letter Queue

Failed messages are moved to a separate queue for analysis and reprocessing.

8. Conclusion

Key elements of a multi-agent communication platform include:

Flexible message structure: Support for various communication scenarios
Clear state management: Predictable agent behavior
Diverse communication patterns: Request-response, publish-subscribe, broadcast
Fault-tolerant design: Retry, timeout, error handling

Based on these principles, scalable and reliable multi-agent systems can be built.

References

Korean Version: 한국어 버전

Architecture on Yarang's Tech Lair

MCP Integration Guide: Integrating Discord MCP with ZeroClaw Runtime

1. Architecture Design: Dual Communication on a Single Channel

2. Essential Dependencies and Setup (Rust)

3. MCP Client Implementation

4. Integration with ZeroClaw Agents

5. Efficiency and Security Considerations (Architecture Insights)

Conclusion

ZeroClaw Agent Runtime: Implementing a TCP/IP Architecture for High-Performance Multi-Agent Communication

Challenges with Existing Communication and ZeroClaw’s Approach

Asynchronous Server Structure Using Rust Tokio

1. Defining Basic Message Structures

2. Implementing Asynchronous TCP Handlers

Team Agent Communication and Protocol Design

Conclusion: Towards Scalable Agent Systems

Reference Code and Resources

Designing MCP Authentication Architecture for Zero-Touch OAuth Implementation

Why Zero-Touch?

Architecture Design

Implementation Step 1: Server Side (blog-api-server)

Implementation Step 2: Client Side (MCP Client)

Considerations for ZeroClaw Runtime Integration

Conclusion

Stop Using JWTs: The Practicality and Implementation of Session-Based Authentication

Stop Using JWTs: The Practicality and Implementation of Session-Based Authentication

The Sweet Trap of JWTs

1. Revocation Problem

2. Token Size and Overhead

Returning to Session-Based Authentication

Prerequisites

Implementation Code (Go)

Code Explanation and Application Tips

Conclusion: What Should You Choose?

Building a High-Performance Agent Runtime with Rust: An In-depth Analysis of the ZeroClaw Architecture

Building a High-Performance Agent Runtime with Rust: An In-depth Analysis of the ZeroClaw Architecture

1. Why Rust? (Safe Concurrency)

2. Communication Protocol Design: File-Based vs. Memory-Based

2.1. Implementing the Request-Response Pattern

3. Integration with MCP: The Bridge Pattern

4. Roadmap for H1 2026: Directions for Advancement

Conclusion

Designing and Implementing a Communication Protocol for MCP-based Multi-Agent Systems in Rust

1. Problem Definition: Why a Communication Protocol?

2. Protocol Design: Request, Task, Completion

3. Implementing the ZeroClaw Communication Layer in Rust

3.1. Message Definition (Based on JSON-RPC)

3.2. Agent Runtime Structure

4. Conclusion and Next Steps

References

[ZeroClaw] Rust Channel-Based IPC Design for Asynchronous Agent Runtime

[ZeroClaw] Rust Channel-Based IPC Design for Asynchronous Agent Runtime

1. Problems with the Existing Architecture and the Need for Asynchronous Design

2. Event Loop Structure Using Rust’s tokio::sync::mpsc

Core Design Points

3. Practical Code: A Concrete Implementation Example

Step 1: Define the Message Protocol

Step 2: Implement Agent Struct and Runner

Step 3: Main Runtime and Channel Connection

4. ZeroClaw Project Application Effects

Conclusion

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

1. Combining ZeroClaw Architecture and MCP

2. Core Structure: Asynchronous Request Routing

2.1. Cargo.toml Configuration

2.2. Defining MCP Message Structure

3. Implementing a Lightweight Request Handler

4. Advanced Optimization: ZeroClaw Integration

5. Conclusion

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

1. Core Requirements of an MCP Server

2. Architecture Design: ZeroClaw Style

3. Practical Code Examples

3.1. Dependency Setup (Cargo.toml)

3.2. Handler Trait Definition

3.3. Implementing the Log Reading Tool

3.4. Main Loop and JSON-RPC Server

4. Optimization and Deployment Considerations

5. Conclusion

2. Event Loop Structure Using Rust’s `tokio::sync::mpsc`

3.1. Dependency Setup (`Cargo.toml`)