Architecture on Yarang's Tech Lair

MCP 통합 가이드: ZeroClaw 런타임에서 Discord MCP 연동하기

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

최근 고성능 Rust 에이전트 런타임인 ZeroClaw를 발표하며, 멀티 에이전트 시스템의 효율성을 극대화하는 방안에 대한 고민이 깊어졌습니다. 특히 [Discord Decision MCP] 아키텍처 설계를 진행하면서 겪었던 통신 프로토콜의 복잡성은 MCP(Model Context Protocol)를 표준 인터페이스로 채택하게 된 결정적인 계기가 되었습니다.

이번 포스트에서는 ZeroClaw의 환경에서 Discord MCP를 실제로 통합하여, 에이전트가 Discord 메시지를 수신하고 처리하는 과정을 구체적인 코드와 함께 설명하겠습니다.

1. 아키텍처 설계: 단일 채널에서의 이중 통신

기존 [Discord MCP] Gateway 아키텍처에서는 게이트웨이가 이벤트를 필터링하고 에이전트에게 전달하는 역할을 했습니다. 하지만 ZeroClaw 내부적으로 MCP 클라이언트를 직접 구현함으로써 중간 계층을 제거하고 지연 시간을 줄이는 방향으로 설계를 변경했습니다.

핵심은 **MCP Client**가 Discord 이벤트를 stdio를 통해 ZeroClaw 프로세스로 전달하고, 에이전트의 응답을 다시 Discord로 보내는 흐름입니다.

2. 필수 의존성 및 설정 (Rust)

ZeroClaw는 Rust로 작성되었으므로, 높은 동시성 처리를 위해 비동기 런타임인 tokio와 JSON 처리를 위한 serde를 사용합니다. MCP 서버와의 통신은 JSON-RPC 메시지를 표준 입출력(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 클라이언트 구현

ZeroClaw 내부에서 Discord MCP 서버를 제어하기 위한 간단한 클라이언트 구조를 정의합니다. 이 클라이언트는 MCP 표준을 따르는 tools/call 메서드를 사용하여 Discord 봇의 기능을 실행합니다.

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 }
 }

 /// Discord 채널에 메시지를 전송하는 MCP 툴 실행
 pub async fn send_message(&mut self, channel_id: &str, content: &str) -> Result<(), Box<dyn std::error::Error>> {
 self.id += 1;
 
 // MCP 서버 프로세스 실행 (예: Python 기반 Discord MCP 서버)
 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
 }
 }),
 };

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

 // (실제 구현 시에는 비동기 리더에서 응답을 파싱하는 로직 필요)
 // 여기서는 간단한 예시를 위해 생략합니다.
 
 Ok(())
 }
}

4. ZeroClaw 에이전트와의 통합

이제 위에서 만든 DiscordMCPClient를 ZeroClaw의 에이전트 루프 내에서 사용해봅시다. 에이전트가 특정 작업을 완료했을 때, 이를 Discord에 알리는 시나리오입니다.

struct ZeroClawAgent {
 discord_client: DiscordMCPClient,
}

impl ZeroClawAgent {
 async fn run_task(&mut self, task: &str) {
 println!("[Agent] 작업 시작: {}", task);
 
 // 복잡한 추론 또는 파일 처리 로직 (생략)
 // ...

 let result = format!("작업 '{}' 완료됨.", task);

 // 결과를 Discord로 전송
 match self.discord_client.send_message("123456789", &result).await {
 Ok(_) => println!("[Agent] Discord 알림 전송 성공"),
 Err(e) => eprintln!("[Agent] 전송 실패: {}", e),
 }
 }
}

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

 agent.run_task("서버 로그 분석").await;
}

5. 효율성 및 보안 고려사항 (Architecture Insights)

리소스 관리: [Hacker News]의 최신 트렌드인 ‘Adrafinil’처럼, 에이전트가 유휴 상태일 때는 Discord MCP 연결을 끊고 작업이 활성화되었을 때만 연결을 맺는 speculative decoding 방식을 적용하면 리소스를 아낄 수 있습니다.
보안: [Anonymous GitHub account] 관련 이슈처럼, MCP 서버에 전달되는 파라미터(예: API 토큰)는 환경 변수로 관리하거나 별도의 보안 저장소(Vault)에서 가져오도록 설계해야 합니다. 코드 내에 하드코딩된 시크릿은 치명적입니다.
에러 처리: 통신 플랫폼 설계 고찰에서 언급된 바와 같이, Discord API의 Rate Limit을 고려하여 MCP 클라이언트에 재시도 로직(Retry Logic)을 포함하는 것이 중요합니다.

마무리하며

ZeroClaw와 Discord MCP의 통합은 단순히 봇을 만드는 것을 넘어, 에이전트가 외부 세계와 상호작용하는 표준화된 인터페이스를 구축하는 과정입니다. 앞으로도 [MCP] 블로그 자동화 시스템 구축 경험을 살려, 더욱 정교한 멀티 에이전트 협업 시스템을 발전시켜 나갈 계획입니다.

ZeroClaw 에이전트 런타임: 고성능 멀티 에이전트 통신을 위한 TCP/IP 아키텍처 구현

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

안녕하세요! 최근 오픈소스 AI 및 에이전트 생태계가 급격히 확장되면서, 단일 LLM을 넘어 여러 에이전트가 협력하는 ‘멀티 에이전트 시스템’에 대한 관심이 뜨겁습니다. 이전 포스트에서 ZeroClaw 프로젝트의 아키텍처 설계를 다루었는데요, 이번에는 실제 ZeroClaw 런타임이 내부적으로 어떻게 에이전트 간의 통신을 처리하고, Rust의 강력한 비동기 런타임을 활용해 고성능을 달성하는지 그 구체적인 구현 방법을 소개하고자 합니다.

기존 통신의 문제점과 ZeroClaw의 접근

일반적인 MCP(Model Context Protocol)나 기초적인 에이전트 시스템은 주로 단일 프로세스 내의 메모리 공유나 간단한 로컬 함수 호출로 통신을 처리합니다. 하지만 시스템이 복잡해지고 에이전트가 분산되면서 다음과 같은 문제가 발생합니다.

확장성의 한계: 단일 프로세스 메모리 버퍼는 한정되어 있으며, 수백 개의 에이전트가 동시에 메시지를 주고받을 때 병목이 발생합니다.
결합도(Coupling) 증가: 에이전트 간의 통신이 로직에 강하게 결합되어, 특정 에이전트를 교체하거나 업데이트하기 어렵습니다.
네트워크 분리: 로컬 개발 환경과 클라우드 배포 환경 간의 통신 방식이 달라지면 코드를 수정해야 하는 불편함이 있습니다.

ZeroClaw는 이를 해결하기 위해 **‘파일 기반 아키텍처 설계’**와 **‘TCP/IP 네트워킹 계층’**을 결합한 하이브리드 방식을 채택했습니다. 에이전트는 자신의 상태를 파일 시스템에 선언적으로(Declarative) 기록하며, 실제 메시지 전송은 비동기 TCP 소켓을 통해 처리합니다.

Rust Tokio를 활용한 비동기 서버 구조

ZeroClaw의 핵심은 Rust의 tokio 런타임 위에서 구축된 고성능 네트워크 계층입니다. 각 에이전트는 독립적인 태스크(Task)로 실행되며, 채널(Channel)을 통해 안전하게 메시지를 교환합니다.

다음은 ZeroClaw 런타임의 핵심인 메시지 브로커(Message Broker)의 간소화된 구현 예제입니다.

1. 기본 메시지 구조 정의

먼저, 에이전트 간 주고받을 데이터 구조를 정의합니다. serde를 사용하여 직렬화를 자동화합니다.

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

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentMessage {
 pub source: String, // 송신 에이전트 ID
 pub target: String, // 수신 에이전트 ID (혹은 "broadcast")
 pub payload: PayloadType,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum PayloadType {
 Text(String),
 Data(HashMap<String, String>), // 유연한 데이터 전달을 위한 Map
 Control(ControlSignal),
}

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

2. 비동기 TCP 핸들러 구현

실제 통신은 tokio::net::TcpListener를 통해 이루어집니다. 각 연결은 별도의 태스크로 분리되어 처리되므로, 특정 에이전트의 느린 응답이 전체 시스템을 멈추게 하지 않습니다.

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);

 // 메시지 라우팅을 위한 채널 (실제 구현에서는 더 복잡한 라우터 사용)
 let (tx, mut rx) = mpsc::channel::<AgentMessage>(1000);

 // 수신 태스크 (스폰)
 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, // 연결 종료
 Ok(n) => n,
 Err(e) => {
 eprintln!("Failed to read from socket; err = {:?}", e);
 return;
 }
 };

 // 메시지 파싱 (간소화된 로직)
 let received_data = &buf[..n];
 // 실제로는 여기서 역직렬화 수행
 println!("Received: {:?}", String::from_utf8_lossy(received_data));
 
 // ... (비즈니스 로직 처리) ...
 }
 });
 }
 });

 // 송신 태스크 예시 (주기적 하트비트)
 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),
 };
 // 실제로는 소켓에 쓰거나 외부로 전송
 println!("[{}] Sending Heartbeat...", config.id);
 }
 }
 });

 Ok(())
}

이 코드는 ZeroClaw 에이전트가 다른 에이전트의 요청을 비동기적으로 수신하고, 자신의 상태를 주기적으로 보고하는 기본 뼈대를 보여줍니다. tokio::spawn을 통해 각 연결이 독립적으로 실행되므로, 수천 개의 동시 연결도 효율적으로 처리할 수 있습니다.

팀 에이전트 통신과 프로토콜 설계

단순한 1:1 통신을 넘어, ZeroClaw는 팀(Team) 단위의 통신을 지향합니다. 이는 이전에 논의된 ‘팀 에이전트 통신 아키텍처’와 연결됩니다.

Pub/Sub 패턴: 특정 주제(Topic)를 구독한 에이전트 그룹에게 메시지를 일괄 전달합니다.
피어 투 피어 (P2P): 중앙 서버를 거치지 않고 에이전트 간 직접 통신하여 대기 시간(Latency)을 최소화합니다.

ZeroClaw의 프로토콜은 TCP 계층 위에서 JSON 또는 바이너리 포맷(성능이 중요할 경우 MessagePack 등)으로 캡슐화되어 전송됩니다. 이를 통해 네트워크 추상화 계층(Network Abstraction Layer)을 형성하여, 상위 비즈니스 로직은 통신이 로컬인지 원격인지 신경 쓰지 않고 로직을 작성할 수 있습니다.

결론: 확장 가능한 에이전트 시스템을 향하여

ZeroClaw는 단순한 LLM 래퍼(Wrapper)를 넘어, 진정한 분산 시스템으로 설계되고 있습니다. Rust의 메모리 안전성과 Zero-cost 추상화, 그리고 tokio의 강력한 비동기 처리 능력을 결합하여, 안정적이고 빠른 에이전트 런타임을 구축하고 있습니다.

다음 포스트에서는 이러한 통신 아키텍처 위에서 LLM이 어떻게 자신의 의사를 결정(Decision)하고, MCP 도구를 통해 실제 행동을 수행하는지 그 플로우를 디버깅해보겠습니다.

참고 코드 및 리소스

ZeroClaw GitHub Repository (오픈소스 준비 중)
The Garbage Collection Handbook: The Art of Automatic Memory Management (2nd Ed) - 최근 뉴스에서 언급되었던 메모리 관리의 고전이자 바이블입니다.

읽어주셔서 감사합니다!

Zero-Touch OAuth 구현을 위한 MCP 인증 아키텍처 설계

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

최근 ‘Zero-Touch OAuth for MCP’라는 흥미로운 기술 트렌드를 접했습니다. 우리가 개발 중인 ZeroClaw 런타임과 blog-api-server의 MCP(Model Context Protocol) 통합 과정에서, 사용자 경험을 저해하지 않으면서도 보안성을 확보하는 것은 필수적인 과제입니다. 이번 포스트에서는 별도의 복잡한 설정 없이 사용자가 MCP 클라이언트를 연결할 수 있도록 돕는 ‘Zero-Touch’ 인증 흐름을 설계하고, 이를 실제 코드로 구현하는 방법을 살펴보겠습니다.

왜 Zero-Touch인가?

기존의 OAuth 2.0 흐름은 사용자에게 ‘Client ID’와 ‘Client Secret’을 발급받아 설정 파일에 입력하도록 요구하곤 했습니다. 하지만 일반 사용자나 개발자에게 이는 큰 진입 장벽입니다. Zero-Touch OAuth는 클라이언트가 사전에 등록된 정보(Pre-registered metadata)를 통해 자동으로 인증을 시도하고, 사용자는 단순히 ‘허용’ 버튼만 누르면 되는 흐름을 지향합니다.

아키텍처 설계

우리는 blog-api-server를 MCP Provider로, Claude Code나 커스텀 클라이언트를 MCP Consumer로 구성합니다. 핵심은 PKCE (Proof Key for Code Exchange) 확장을 사용하여 Secret을 저장하지 않는 Public Client 환경을 구축하는 것입니다.

핵심 구성 요소:

MCP Client (Consumer): 사용자의 로컬 환경에서 실행되는 에이전트입니다.
Auth Server: blog-api-server 내에 구현된 OAuth2 인증 서버입니다.
Resource Server: 실제 블로그 API입니다.

구현 단계 1: 서버 사이드 (blog-api-server)

먼저, Rust 기반의 blog-api-server에 간단한 인증 엔드포인트를 추가해야 합니다. 이전 글인 *’[blog-api-server] MCP 블로그 클라이언트 언어 파라미터 추가’*에서 언급된 아키텍처를 확장하여 Auth 모듈을 독립시킵니다.

여기서는 핵심 로직인 코드 검증(Verification) 로직을 보여드리겠습니다. 클라이언트로부터 받은 code_verifier를 검증하는 과정입니다.

// 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, // 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. DB에서 Authorization Code 조회
 let auth_record = state.db.get_auth_code(&payload.code)
 .await
 .map_err(|_| "Invalid code".to_string())?;

 // 2. PKCE Challenge 검증 (핵심 보안 로직)
 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. 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,
 }))
}

이 코드는 클라이언트가 보내온 code_verifier를 해싱하여, 처음 인증 요청을 보낼 때 생성된 code_challenge와 일치하는지 확인합니다. 이 과정이 ‘Zero-Touch’를 보안적으로 가능하게 만드는 핵심입니다.

구현 단계 2: 클라이언트 사이드 (MCP Client)

이제 클라이언트는 사용자 개입 없이(혹은 최소한의 개입으로) 토큰을 발급받을 수 있습니다. Python을 사용한 MCP 클라이언트 예제를 작성해보겠습니다.

import hashlib
import base64
import requests
from urllib.parse import urlencode

# Zero-Touch 설정 (하드코딩 혹은 환경 변수)
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"

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

# 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 # 서버로 전송하여 검증받음
 }
 response = requests.post(TOKEN_URL, data=data)
 return response.json()

# 사용 예시
# 1. 사용자가 get_auth_url()를 통해 브라우저에서 인증 (최초 1회)
# 2. 리다이렉션된 쿼리 파라미터에서 'code' 추출
# 3. token = exchange_code_for_token(code)

ZeroClaw 런타임 통합 고찰

지난 회고록인 *’[ZeroClaw] 2026 상반기 발전방향 회의록’*에서 언급했듯, 우리의 에이전트 런타임은 보안과 확장성을 최우선으로 고려해야 합니다. 위에서 구현한 OAuth 흐름을 ZeroClaw의 Multi-Agent 아키텍처에 통합한다면, 각 에이전트는 독립된 Identity를 가질 수 있습니다.

특히 *’[ZeroClaw] 멀티 에이전트 통신 프로토콜 설계’*에서 논의된 바와 같이, Agent 간 통신 시 이 Access Token을 사용하여 다른 에이전트의 리소스(API)에 안전하게 접근할 수 있는 기반을 마련하게 됩니다. 이는 단순한 블로그 자동화를 넘어, 에이전트가 에이전트를 신뢰하고 작업을 위임하는 분산 시스템의 첫걸음이 됩니다.

마치며

Zero-Touch OAuth는 사용자의 편의성과 보안이라는 두 마리 토끼를 잡는 훌륭한 접근 방식입니다. blog-api-server와 같은 작은 프로젝트부터 시작하여, 점차 ZeroClaw의 핵심 인증 모듈로 발전시켜 나갈 계획입니다. 위 코드는 기본적인 골격이므로, 실제 운영 환경에서는 State 검증, Refresh Token Rotation 등의 로직을 추가해야 합니다.

다음 포스트에서는 이렇게 확보된 토큰을 활용하여 MCP 서버와 실제로 데이터를 주고받는 ‘핸드셰이크(Handshake)’ 과정을 디버깅해보겠습니다.

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

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

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

최근 Hacker News와 같은 커뮤니티에서 “Stop Using JWTs"라는 주제가 다시 한번 뜨거운 감자로 떠올랐습니다. JWT(JSON Web Token)는 처음 등장했을 때만 해도 “무상태(Stateless)“라는 마법의 주문 덕분에 마이크로서비스 아키텍처(MSA)의 표준처럼 여겨졌습니다. 하지만 현실의 웹 서비스를 운영하면서 무상태의 함정에 빠지는 경우가 너무나 많습니다.

이 글에서는 왜 많은 개발자가 JWT에서 발을 떼고, 전통적인 세션 기반 인증(혹은 DB 기반 토큰)으로 돌아가고 있는지, 그리고 이를 실전에서 어떻게 구현하는지 살펴보겠습니다.

JWT의 달콤한 함정

JWT의 가장 큰 장점은 서버에 사용자 상태를 저장하지 않아도 된다는 점입니다. 토큰 자체에 모든 정보가 담겨 있으니, 데이터베이스 조회 없이 서명만 검증하면 됩니다. 이론적으로는 확장성이 뛰어납니다.

하지만 이 “장점"은 곧 “단점"이 됩니다.

1. 폐기 불가능성(Revocation Problem)

JWT는 발급되면 유효기간이 끝날 때까지 유효합니다. 만약 사용자가 로그아웃을 하거나, 관리자가 강제로 탈퇴시켜야 한다면 어떻게 할까요?

Option 1: 토큰을 즉시 파기할 수 없으니 냅두기 (보험상 불가능)
Option 2: 블랙리스트를 도입하기 (결국 DB/Redis 조회 필요 -> Stateless의 장점 상실)

블랙리스트를 도입하는 순간, JWT 검증을 위해 매번 블랙리스트를 확인해야 하므로, “데이터베이스 조회 없이"라는 장점이 사라집니다.

2. 토큰 크기와 부하

JWT는 헤더, 페이로드, 서명을 포함하여 일반적인 세션 ID보다 훨씬 큽니다. 사용자별로 다양한 클레임(Role, 권한 등)을 담을수록 토큰은 비대해집니다. 이는 매 요청마다 네트워크 대역폭을 낭비하게 만듭니다.

세션 기반 인증으로의 회귀

결론적으로, 우리는 **“서버 측에서 상태를 관리한다”**는 사실을 받아들이는 것이 낫습니다. Redis와 같은 인메모리 DB를 사용하면 매우 빠르게 세션을 관리할 수 있으며, 로그아웃이나 강제 탈퇴가 즉시 가능합니다.

이번 섹션에서는 Go 언어와 Redis를 사용하여 간단하지만 강력한 세션 기반 인증 시스템을 구축해 보겠습니다.

사전 준비

Redis가 로컬에 설치되어 있고 실행 중이라고 가정합니다.

구현 코드 (Go)

아래 코드는 /login, /protected, /logout 엔드포인트를 제공하는 간단한 HTTP 서버입니다.

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

// 사용자 정보 (실제로는 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() {
	// Redis 클라이언트 초기화
	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))
}

// 로그인 핸들러
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
	}

	// 사용자 존재 및 비밀번호 확인
	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
	}

	// 새로운 세션 ID 생성
	sessionToken := uuid.NewString()

	// Redis에 세션 저장 (만료 24시간)
	err = rdb.Set(ctx, sessionToken, creds.Username, 24*time.Hour).Err()
	if err != nil {
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	// 쿠키 설정 (HttpOnly, Secure 권장)
	http.SetCookie(w, &http.Cookie{
		Name: "session_token",
		Value: sessionToken,
		Expires: time.Now().Add(24 * time.Hour),
		HttpOnly: true,
		Secure: true, // HTTPS 환경에서만
		Path: "/",
		SameSite: http.SameSiteStrictMode,
	})

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

// 인증 미들웨어
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

		// 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
		}

		// 요청 컨텍스트에 사용자 이름 저장 (선택 사항)
		// r = r.WithContext(context.WithValue(r.Context(), "username", response))

		next(w, r)
	}
}

// 보호된 리소스 핸들러
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)})
}

// 로그아웃 핸들러
func logoutHandler(w http.ResponseWriter, r *http.Request) {
	c, _ := r.Cookie("session_token")
	sessionToken := c.Value

	// Redis에서 세션 삭제 (즉시 폐기)
	rdb.Del(ctx, sessionToken)

	// 쿠키 무효화
	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"})
}

코드 설명 및 적용 팁

안전한 쿠키 사용: HttpOnly와 Secure 플래그를 사용하여 XSS(교차 사이트 스크립팅) 및 중간자 공격을 방지했습니다. 클라이언트(브라우저)가 토큰을 LocalStorage가 아닌 쿠키에 저장하도록 유도하는 것이 안전합니다.
Redis 활용: Redis는 싱글 스레드 기반이므로 원자적 연산이 빠르며, 세션 저장소로 사용하기에 최적입니다. 만약 Redis가 다운되더라도 영구적으로 데이터가 필요한 것은 아니므로(재로그인하면 됨), 빠른 응답 속도에 집중하여 설정합니다.
즉시 로그아웃: logoutHandler를 보면 Redis에서 키를 삭제하는 코드(rdb.Del)가 있습니다. 이는 JWT의 가장 큰 약점인 “로그아웃이 안 됨"을 완벽하게 해결합니다. 키가 삭제되는 순간, 해당 토큰(세션 ID)은 더 이상 유효하지 않습니다.

결론: 무엇을 선택해야 할까?

JWT가 좋은 경우: 당신이 구축하는 시스템이 진정으로 독립적인 마이크로서비스들로 구성되어 있고, 서비스 간 통신에서 사용자 인증이 필요하며, 로그아웃/재발급 로직이 중요하지 않은 단순 API 통신인 경우.
세션/Cookie가 좋은 경우: 일반적인 웹 서비스, SaaS, 사용자의 보안(계정 탈�� 시 즉각적인 조치 필요)이 중요한 대부분의 경우.

“Stop Using JWTs"라는 말은 JWT가 나쁜 기술이라서가 아니라, 상황에 맞지 않게 오남당되고 있기 때문입니다. 간단한 세션 저장소 하나면 해결될 문제에 복잡한 JWT 라이브러리와 블랙리스트 로직을 추가하는 것은 기술 부채를 쌓는 행위일 수 있습니다.

위의 Go 코드 예제를 프로젝트에 적용해 보시고, 관리의 용이성과 보안성을 직접 경험해 보시길 권장합니다.

Rust로 구축하는 고성능 에이전트 런타임: ZeroClaw 아키텍처 심층 분석

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

Rust로 구축하는 고성능 에이전트 런타임: ZeroClaw 아키텍처 심층 분석

최근 ZeroClaw 프로젝트를 통해 고성능 Rust 기반 에이전트 런타임을 설계하고 발전 방향을 논의했다. 기존의 Python 기반 LLM 애플리케이션이나 단일 서버 구조가 가진 한계를 넘어, 안전하고(Safe) 병렬성이 뛰어난 Rust의 특성을 활용하여 멀티 에이전트 시스템을 구축하는 과정은 기술적으로 매우 도전적이었다. 이 글에서는 ZeroClaw의 핵심 아키텍처 설계 안과 통신 프로토콜, 그리고 실제 구현 시 고려해야 할 Rust의 특성을 살펴보겠다.

1. 왜 Rust인가? (Safe Concurrency)

멀티 에이전트 시스템의 핵심은 병렬성이다. 수많은 에이전트가 동시에 돌면서 서로 통신하고 상태를 공유해야 한다. Python의 GIL(Global Interpreter Lock)은 진정한 병렬 처리를 방해하며, Go(Goroutine)는 가비지 컬렉션(GC)로 인한 지연(Latency)이 예측 불가능할 때가 있다. 반면, Rust는 ‘Zero-cost Abstraction’과 ‘Fearless Concurrency’를 제공한다.

ZeroClaw 프로젝트에서는 에이전트 간의 메시지 전달을 tokio::sync::mpsc 채널로 구현하여, 락(Lock) 없는 비동기 통신을 가능하게 했다. 이를 통해 CPU 리소스를 최대한 활용하면서도 데이터 레이스(Data Race)를 컴파일 타임에 완전히 배제할 수 있었다.

2. 통신 프로토콜 설계: 파일 기반 vs 메모리 기반

아키텍처 설계 단계에서 가장 많은 고민을 했던 부분은 ‘에이전트 간 통신 방식’이었다. 초기에는 [Multi-Agent] 파일 기반 아키텍처 설계를 고려했다. 파일 시스템을 공유 메모리처럼 사용하는 접근법은 구현이 쉽고 디버깅이 용이하다는 장점이 있다. 하지만 고성능 런타임을 목표로 하는 ZeroClaw에게는 I/O 병목이 치명적이었다.

결과적으로 우리는 메모리 기반의 이벤트 버스(Event Bus) 아키텍처를 채택했다.

2.1. 요청-응답 패턴 구현

단순한 파이어 앤 포겟(Fire-and-Forget) 방식이 아니라, 에이전트 간의 작업 위임이 필요하므로 요청-응답(Request-Response) 패턴을 구현해야 했다. 이를 위해 Rust의 타입 시스템을 적극 활용했다.

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

// 에이전트 간 주고받을 메시지 정의
#[derive(Debug, Serialize, Deserialize)]
enum AgentMessage {
 TaskRequest { id: String, payload: String },
 TaskResponse { id: String, result: String },
}

// 에이전트 액터 구조체
struct AgentActor {
 id: String,
 receiver: mpsc::Receiver<AgentMessage>,
 // 다른 에이전트에게 메시지를 보내기 위한 발신자 맵
 peers: HashMap<String, mpsc::Sender<AgentMessage>>,
}

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

 // 피어 등록
 fn register_peer(&mut self, id: String, sender: mpsc::Sender<AgentMessage>) {
 self.peers.insert(id, sender);
 }

 // 메시지 루프 실행
 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);
 // 실제 작업 수행 (LLM 호출 등)
 let result = format!("Processed '{}' by {}", payload, self.id);
 
 // (실제 구현에서는 요청자에게 응답을 보내는 로직이 필요)
 }
 _ => {}
 }
 }
 }
}

이 코드는 ZeroClaw의 통신 계층을 위한 최소한의 골격이다. 각 에이전트는 독립적인 태스크(tokio::spawn)로 실행되며, 채널을 통해 메시지를 교환한다.

3. MCP와의 연동: 브릿지 패턴

[Discord Decision MCP] 아키텍처 설계 문서에서 논의된 바와 같이, 에이전트 런타임은 외부 세계와 소통해야 한다. 우리는 MCP(Model Context Protocol)를 표준 인터페이스로 채택하여, ZeroClaw 내부의 에이전트가 Discord나 블로그 API와 상호작용할 수 있도록 설계했다.

이때 중요한 점은 Rust의 강력한 타입 시스템과 외부 JSON 기반 프로토콜 간의 간극을 줄이는 것이다. serde_json을 활용하여 MCP 메시지를 내부 구조체로 역직렬화하고, 타입 안전성을 유지한 상태에서 에이전트 간 전달한다.

// MCP 도구 호출을 위한 구조체
#[derive(Serialize, Deserialize)]
struct MCPToolCall {
 tool_name: String,
 arguments: HashMap<String, serde_json::Value>,
}

// 에이전트가 MCP 호출을 감지했을 때의 처리 로직 예시
fn handle_mcp_message(msg: &str) -> Result<MCPToolCall, Box<dyn std::error::Error>> {
 let call: MCPToolCall = serde_json::from_str(msg)?;
 // Rust 내부에서 타입 검증 완료
 Ok(call)
}

4. 2026 상반기 로드맵: 고도화 방향

[ZeroClaw] 2026 상반기 발전방향 회의록에서 언급된 바와 같이, 우리는 단순한 구현을 넘어 최적화에 집중한다.

동적 에이전트 스케일링 (Dynamic Scaling): 현재는 정적 설정으로 에이전트를 생성하지만, 부하에 따라 에이전트 인스턴스를 tokio::task::spawn으로 동적으로 늘리고 줄이는 오토스케일링 로직을 도입할 예정이다.
워터마크(Back-pressure) 처리: LLM API 호출 속도보다 처리 속도가 빠를 경우 채널이 터지는 것을 방지하기 위해, tokio::sync::mpsc의 버퍼 전략을 세밀하게 조정해야 한다.
관찰 가능성 (Observability): 단순한 로깅을 넘어, tracing 크레이트를 활용하여 에이전트 간 메시지 흐름을 분산 추적(Distributed Tracing)할 수 있는 구조를 만들어야 한다.

결론

ZeroClaw는 단순히 또 다른 에이전트 프레임워크가 아니다. Rust의 안전성과 성능을 바탕으로, 대규모 LLM 애플리케이션을 운영할 수 있는 인프라를 목표로 한다. 코드베이스 아키텍처 분석을 통해 얻은 통찰은 ‘복잡성을 어떻게 관리할 것인가’에 집중되어 있으며, 이는 앞으로의 개발 방향성을 명확히 해준다. 고성능 런타임이 필요한 모든 개발자에게 ZeroClaw는 강력한 선택지가 될 것이다.

MCP 기반 멀티 에이전트 시스템의 통신 프로토콜 설계와 Rust 구현

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

최근 ‘ZeroClaw’ 프로젝트와 MCP(Model Context Protocol) 관련 작업을 진행하며, 단일 에이전트를 넘어선 **멀티 에이전트 시스템(Multi-Agent System)**의 필요성을 절실히 느꼈습니다. 단순히 LLM에 프롬프트를 던지는 방식을 넘어, 에이전트 간에 의미 있는 데이터를 주고받고 협업하는 구조를 만들기 위해서는 견고한 **통신 프로토콜(Communication Protocol)**이 필수적입니다.

이번 포스트에서는 MCP 아키텍처를 기반으로 한 멀티 에이전트 통신 설계 과정과, 이를 고성능 런타임인 ZeroClaw(Rust) 위에 구현하는 방법을 살펴보겠습니다.

1. 문제 정의: 왜 통신 프로토콜인가?

기존의 [blog-api-server]나 [Discord MCP] 구현에서는 주로 ‘요청-응답(Request-Response)’ 구조를 따랐습니다. 클라이언트가 요청을 보내면 서버가 처리하고 응답하는 단방향 흐름이 주를 이루었습니다. 하지만 멀티 에이전트 환경에서는 다음과 같은 이유로 이 구조만으로는 부족합니다.

비동기성(Asynchrony): 에이전트 A가 에이전트 B에게 작업을 위임하고, B가 완료될 때까지 A가 멈춰 있으면 시스템 전체의 처리량이 떨어집니다.
이벤트 기반 상호작용: 어떤 에이전트는 시스템의 상태 변화(예: 파일 생성, 로그 업데이트)를 감시하다가 특정 조건에서 다른 에이전트에게 신호를 보내야 합니다.
신뢰성: 네트워크 불안정이나 에이전트의 일시적 장애 상황에서 메시지가 유실되지 않아야 합니다.

2. 프로토콜 설계: 요청, 작업, 완료

이러한 문제를 해결하기 위해 우리는 Task-Based Messaging Protocol을 설계했습니다. 이 프로토콜은 MCP 표준 메시지 형식을 확장하여 사용하며, 크게 세 가지 주요 메시지 타입으로 구성됩니다.

TaskRequest: 작업의 시작. 에이전트 A가 B에게 특정 작업을 의임할 때 사용합니다.
TaskUpdate: 진행 상황 보고. 장기 실행 작업 시 중간 결과를 전달합니다.
TaskResult: 최종 결과. 성공 또는 실패 여부와 함께 데이터를 반환합니다.

3. Rust로 구현하는 ZeroClaw 통신 계층

ZeroClaw는 Rust의 강력한 타입 시스템과 비동기 런타임(Tokio)을 사용하여 이 프로토콜을 타입 안전하게 구현합니다. 아래는 간소화된 메시지 정의와 핸들러 구조입니다.

3.1. 메시지 정의 (JSON-RPC 기반)

MCP는 기본적으로 JSON-RPC 2.0을 기반으로 하므로, 이를 준수하면서 에이전트 간 통신에 필요한 메타데이터를 포함합니다.

// src/protocol/message.rs

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

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentMessage {
 pub id: String, // 메시지 고유 ID
 pub sender: String, // 발신 에이전트 ID
 pub target: String, // 수신 에이전트 ID
 pub timestamp: i64, // 타임스탬프
 pub payload: Payload, // 실제 데이터
}

#[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), // 실패 사유
 Pending,
}

3.2. 에이전트 런타임 구조

ZeroClaw의 에이전트는 각각 독립적인 Tokio 태스크로 실행됩니다. 에이전트 간 통신은 채널(Channel)을 통해 이루어지며, 중재자(Mediator)가 이를 라우팅합니다.

// src/runtime/agent.rs

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

pub struct Agent {
 id: String,
 tx: mpsc::Sender<AgentMessage>, // 외부로 메시지를 보내는 송신자
 rx: mpsc::Receiver<AgentMessage>, // 내부에서 메시지를 받는 수신자
}

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

 // 에이전트의 메인 실행 루프
 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 => {
 // 핑에 퐁으로 응답하는 로직
 // 실제 환경에서는 클라이언트의 tx를 사용해 응답을 보냄
 println!("[{}] Received Ping from {}", self.id, msg.sender);
 }
 Payload::TaskRequest { task_id, description, context } => {
 println!("[{}] Received Task {}: {}", self.id, task_id, description);
 // 여기에 LLM 호출이나 도구 실행 로직이 들어갑니다.
 
 // 예: 결과 반환 로직 (가상)
 // self.send_result(task_id, ...).await;
 }
 _ => {
 println!("[{}] Received unhandled message type", self.id);
 }
 }
 Ok(())
 }
}

4. 결론 및 다음 단계

위와 같이 구조화된 통신 계층을 통해, 우리는 단순한 텍스트 생성을 넘어 작업(Task) 단위의 협업이 가능한 아키텍처를 갖추게 됩니다. [ZeroClaw] 프로젝트의 2026 상반기 목표인 ‘고성능 에이전트 런타임’은 이러한 견고한 기초 위에 LLM 추론 로직을 통합함으로써 완성될 것입니다.

다음 포스트에서는 이 통신 프로토콜 위에서 실제로 LLM을 호출하여 도구(Tool)를 사용하는 ‘플래너(Planner)’ 에이전트의 구현细节을 다루겠습니다.

참고자료

[ZeroClaw] 멀티 에이전트 아키텍처 설계안
[Claude Code] 팀 에이전트 통신 아키텍처
Rust Tokio Documentation

[ZeroClaw] 비동기 에이전트 런타임을 위한 Rust 채널 기반 IPC 설계

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

[ZeroClaw] 비동기 에이전트 런타임을 위한 Rust 채널 기반 IPC 설계

안녕하세요. 최근 ZeroClaw 프로젝트의 핵심인 ‘멀티 에이전트 아키텍처’를 고도화하면서, 단순한 메시지 전달을 넘어 고성능 비동기 통신(IPC, Inter-Process Communication) 환경을 구축한 경험을 공유하고자 합니다.

기존의 동기적 통신 방식은 에이전트 간 결합도를 높이고, 한 에이전트의 장애가 전체 시스템을 멈추게 만드는 병목 구간(Single Point of Failure)이 되었습니다. 이를 해결하기 위해 Rust의 강력한 동시성 기능인 tokio 런타임과 MPSC(Multi-Producer, Single-Consumer) 채널을 활용하여 이벤트 기반의 느슨한 결합 아키텍처를 설계했습니다.

이번 포스트에서는 에이전트 런타임의 효율성을 극대화하기 위해 채널을 어떻게 설계하고 구현했는지, 실제 코드와 함께 살펴보겠습니다.

1. 기존 아키텍처의 문제점과 비동기 설계의 필요성

이전까지의 ZeroClaw 에이전트는 메시지를 요청(Request)하고 응답(Response)을 기다리는 동기식 RPC 패턴을 주로 사용했습니다. 하지만 에이전트가 수십 개로 늘어나고 복잡한 작업(예: 파일 기반 아키텍처 분석, 대규모 로그 처리)을 수행하게 되면서 다음과 같은 문제가 발생했습니다.

블로킹(Blocking) 문제: A 에이전트가 B 에이전트의 응답을 기다리는 동안, A 에이전트는 다른 작업을 수행할 수 없습니다.
복잡한 에러 전파: 특정 에이전트가 뻗거나 타임아웃이 발생했을 때, 호출 체인 상위에 있는 에이전트들로 에러를 전달하기 복잡했습니다.

이를 해결하기 위해 우리는 **“에이전트는 메시지를 보내고 즉시 다른 작업을 수행한다, 처리된 결과는 이벤트로 수신한다”**는 비동기 패턴을 채택했습니다.

2. Rust의 `tokio::sync::mpsc`를 활용한 이벤트 루프 구조

Rust의 tokio 크레이트가 제공하는 MPSC 채널은 높은 처리량과 낮은 지연 시간을 보장하며, 에이전트 런타임에 최적화되어 있습니다. 각 에이전트는 자신만의 **Task(작업 단위)**를 가지며, 이는 tokio::spawn을 통해 독립적으로 실행됩니다.

핵심 설계 포인트

Message Bus: 각 에이전트는 송신자(tx)와 수신자(rx)를 보유합니다.
Event Loop: 수신자(rx)는 무한 루프(loop)를 돌며 메시지가 도착할 때까지 비동기적으로 대기(recv())합니다.

3. 실전 코드: 구체적인 구현 예제

이제 실제로 ZeroClaw 런타임 내에서 에이전트들이 통신하는 코드를 작성해 보겠습니다.

Step 1: 메시지 프로토콜 정의

먼저 에이전트 간 주고받을 데이터 구조를 정의해야 합니다. 이때 Enum을 사용하여 메시지의 타입을 안전하게 관리하는 것이 좋습니다.

// 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: 에이전트 구조체 및 러너(Runner) 구현

각 에이전트는 고유 ID와 수신자(rx)를 가집니다. run 메서드는 에이전트의 생명주기를 관리하는 핵심 함수입니다.

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);
 
 // 메시지 수신 대기 (비동기)
 while let Some(msg) = self.rx.recv().await {
 match msg {
 AgentMessage::TaskAssigned { task_id, description } => {
 println!("[{}] Received task: {} - {}", self.id, task_id, description);
 // 실제 로직 처리 (예: 파일 분석, 외부 API 호출)
 // 여기서는 예시를 위해 1초 대기 후 완료 메시지를 전송한다고 가정합니다.
 }
 AgentMessage::StatusCheck => {
 println!("[{}] Status: Active", self.id);
 }
 _ => {}
 }
 }
 println!("[{}] Agent shutting down.", self.id);
 }
}

Step 3: 메인 런타임 및 채널 연결

메인 함수에서는 여러 에이전트를 생성하고 채널을 연결한 뒤, tokio::spawn을 통해 병렬로 실행시킵니다.

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

 // 2. 에이전트 생성 및 실행 (비동기 태스크로 분리)
 let agent_handle = {
 let agent = Agent::new("Agent-A".to_string(), rx);
 tokio::spawn(async move {
 agent.run().await;
 })
 };

 // 3. 메인 런타임에서 메시지 송신
 // 다른 에이전트나 API 서버가 이 tx를 사용하여 메시지를 보낼 수 있습니다.
 
 // 작업 할당
 let _ = tx.send(AgentMessage::TaskAssigned {
 task_id: "T-101".to_string(),
 description: "Analyze server logs".to_string(),
 }).await;

 // 상태 확인
 let _ = tx.send(AgentMessage::StatusCheck).await;

 // 4. 에이전트가 작업을 마칠 때까지 대기 (실제 환경에서는 계속 실행됨)
 drop(tx); // 송신자 종료 -> 채널 닫힘 -> 에이전트 루프 종료 조건 성립
 
 agent_handle.await?;
 
 Ok(())
}

4. ZeroClaw 프로젝트 적용 효과

위와 같은 구조를 ZeroClaw 런타임에 적용한 결과 다음과 같은 이점을 얻었습니다.

병렬 처리 성능 향상: 에이전트가 자신만의 tokio 태스크 내에서 실행되므로, CPU 코어를 효율적으로 활용할 수 있었습니다.
결합도 감소: 메인 로직이 특정 에이전트의 내부 구현을 알 필요 없이, 단순히 tx.send만 호출하면 됩니다.
그레이스풀 셧다운(Graceful Shutdown): drop(tx)를 통해 채널을 닫으면, 에이전트는 더 이상 메시지가 오지 않음을 감지하고 자연스럽게 while let 루프를 빠져나와 종료합니다.

마치며

Rust의 소유권(Ownership) 시스템과 tokio의 비동기 추상화는 멀티 에이전트 시스템 구축에 있어 강력한 무기가 됩니다. 다음 포스트에서는 이 에이전트들이 파일 기반 아키텍처와 결합하여 상태를 어떻게 영속화하는지 다루도록 하겠습니다.

ZeroClaw의 고성능 에이전트 런타임 개발은 계속됩니다.

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

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

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

최근 ‘Grit: Rewriting Git in Rust with Agents’ 기사에서도 확인할 수 있듯, Rust 언어는 에이전트 시스템의 런타임으로서 그 가치를 재평가받고 있습니다. 우리 팀의 ZeroClaw 런타임 역시 고성능과 안전성을 목표로 개발 중이며, 이와 연계하여 MCP(Model Context Protocol) 서버를 어떻게 효율적으로 구축할지에 대한 고민이 깊어지고 있습니다.

기존의 무거운 Python 기반 서버나 복잡한 Node.js 아키텍처 대신, Rust의 병행성(concurrency)과 저지연성(low-latency)을 활용한 초경량 MCP 서버 구조를 제안합니다. 이 글에서는 ZeroClaw 아키텍처의 장점을 살리면서, 실무에서 바로 적용 가능한 Rust 기반 MCP 서버 예제를 작성해 보겠습니다.

1. ZeroClaw 아키텍처와 MCP의 결합

ZeroClaw 프로젝트의 핵심은 파일 기반 아키텍처 설계와 멀티 에이전트 통신 프로토콜의 효율화입니다. MCP 서버를 구축할 때 가장 중요한 점은 데이터 직렬화/역직렬화(Serde)의 오버헤드를 줄이는 것과 비동기 요청 처리입니다.

Rust의 tokio 런타임과 serde_json을 활용하면, JSON 기반 MCP 프로토콜을 나노초(nanosecond) 단위의 오버헤드로 처리할 수 있습니다. 이는 특히 대규모 로그 처리나 모니터링 시스템([blog-api-server] 경험)에서 필수적인 요소입니다.

2. 핵심 구조: 비동기 요청 라우팅

복잡한 의존성 없이, 표준 라이브러리와 몇 가지 필수 크레이트(crate)만으로 MCP 서버의 뼈대를 만들어 보겠습니다. 이 구조는 ZeroClaw의 에이전트 간 통신 패턴을 따르며, 단일 스레드가 아닌 멀티스레드 환경에서의 안전성을 보장합니다.

2.1. Cargo.toml 설정

먼저 프로젝트 의존성을 추가합니다.

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

2.2. MCP 메시지 구조 정의

MCP는 기본적으로 JSON-RPC와 유사한 구조를 가집니다. 에이전트 간 통신 시 데이터의 무결성을 보장하기 위해 Rust의 타입 시스템을 적극 활용합니다.

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

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPRequest {
 pub jsonrpc: String, // 항상 "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. 경량화된 요청 핸들러 구현

ZeroClaw의 철학처럼 불필요한 추상화 계층을 제거하고, 직관적인 핸들러를 작성합니다. 아래 코드는 들어오는 요청을 파싱하고, 메서드 이름에 따라 적절한 처리를 수행한 뒤 응답을 반환하는 흐름입니다.

// 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" => {
 // 도구 목록 반환 예시
 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" => {
 // 실제 도구 실행 로직 (ZeroClaw Agent 호출 등)
 // params 검증 로직이 여기에 들어갑니다.
 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 파싱
 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 로직 처리
 let mcp_res = handle_mcp_request(mcp_req).await;
 
 // 응답 변환
 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. 고급 최적화: ZeroClow 통합

위 코드는 기본적인 HTTP 서버입니다. ZeroClaw의 진짜 힘을 끌어내기 위해서는 이 서버를 에이전트 런타임 내부의 테스크(Task)로 통합해야 합니다.

채널 기반 통신: HTTP 요청을 직접 처리하는 대신, tokio::sync::mpsc 채널을 통해 요청을 내부 에이전트 큐로 보냅니다. 이는 ZeroClaw의 비동기 메시지 패싱 구조와 일치합니다.
Stealable Work Queue: 다중 코어 환경에서 에이전트가 작업을 효율적으로 분배받을 수 있도록, 작업 큐를 구현합니다.

5. 결론

Rust로 MCP 서버를 작성하면, ZeroClaw와 같은 고성능 런타임의 이점을 십분 활용할 수 있습니다. 단순히 언어를 바꾸는 것이 아니라, 에이전트 간 통신 오버헤드를 최소화하는 아키텍처 설계가 핵심입니다. 위 코드를 베이스로 여러분의 프로젝트에 맞는 에이전트 로직을 추가해 보시기 바랍니다.

참고: 이 코드는 blog-api-server의 로깅 개선 작업에서 얻은 경험을 바탕으로, 에러 처리와 로깅 부분을 간소화하여 실용성에 집중했습니다.

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

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

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

최근 AI 에이전트 생태계에서 **Model Context Protocol (MCP)**는 표준 인터페이스로 자리 잡고 있습니다. 저희 팀의 ZeroClaw 프로젝트와 같은 고성능 런타임 환경에서 MCP 서버를 구축할 때, Rust의 안전성과 속도는 필수적인 요소입니다. 이번 포스트에서는 실무적으로 바로 적용할 수 있는 Rust 기반 MCP 서버의 구조를 설계하고, 실제 코드를 통해 구현 방법을 살펴보겠습니다.

1. MCP 서버의 핵심 요구사항

AI 모델이 데이터에 접근하기 위해 MCP 서버는 다음 세 가지 핵심 기능을 수행해야 합니다.

리소스 발견 (Discovery): 모델이 사용할 수 있는 데이터(파일, API 등)의 목록을 제공
리소스 접근 (Access): 요청받은 데이터의 실제 내용을 효율적으로 반환
도구 실행 (Tool Execution): 모델의 지시에 따라 시스템 내부에서 동작을 수행

Rust는 특히 Zero-cost abstractions와 강력한 비동기 런타임(tokio) 덕분에 대규모 요청을 처리하는 MCP 서버에 최적입니다.

2. 아키텍처 설계: ZeroClaw 스타일

단순한 RPC 호출을 넘어, 우리는 이벤트 기반 아키텍처를 채택하여 확장성을 확보합니다. 구조는 다음과 같습니다.

Transport Layer: stdio 또는 WebSocket을 통한 메시지 송수신 (JSON-RPC 2.0)
Handler Layer: 요청을 라우팅하고 검증하는 계층
Core Logic: 실제 비즈니스 로직 (파일 시스템 접근, DB 조회 등)

3. 실전 코드 예제

가장 대중적인 트랜스포트인 stdio(표준 입출력) 기반의 간단한 MCP 서버를 작성해 보겠습니다. 이 예제는 LLM이 로컬 파일 시스템의 로그를 읽을 수 있게 해주는 기능을 구현합니다.

3.1. 의존성 설정 (`Cargo.toml`)

Rust의 생태계를 활용하기 위해 직렬화와 비동기 처리를 위한 크레이트를 추가합니다.

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

3.2. 핸들러 트레이트 정의

MCP 표준에 맞춰 Tool과 Resource를 처리할 공통 인터페이스를 정의합니다. 이는 추후 ZeroClaw 런타임에 통합하기 쉽게 만듭니다.

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. 로그 읽기 도구 구현

이제 실제로 서버 내부의 파일을 읽어서 AI 모델에 전달하는 로직을 구현합니다.

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. 파라미터 검증 및 추출
 let file_path = params.get("path")
 .and_then(|v| v.as_str())
 .ok_or("Missing 'path' parameter".to_string())?;

 // 2. 보상: 경로 조작 방지 (SandBoxing)
 // 실제 운영 환경에서는 chroot나 전용 가상 디렉토리를 사용해야 합니다.
 if !file_path.ends_with(".log") {
 return Err("Only .log files are allowed".into());
 }

 // 3. 파일 시스템 접근 (동기식 I/O를 비동기 컨텍스트로 래핑)
 let content = fs::read_to_string(file_path)
 .map_err(|e| format!("Failed to read file: {}", e))?;

 // 4. 결과 포맷팅
 Ok(serde_json::json!({
 "status": "success",
 "content": content,
 "lines": content.lines().count()
 }))
 }
}

3.4. 메인 루프 및 JSON-RPC 서버

LLM과의 통신을 담당하는 메인 루프입니다. 표준 입력에서 JSON-RPC 요청을 읽고, 처리 결과를 표준 출력으로 내보냅니다.

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);

 // LLM이나 호스트로부터 요청이 들어올 때마다 처리
 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);
 
 // 비즈니스 로직 실행
 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. 최적화 및 배포 고려사항

위 코드는 기본적인 골격이지만, ZeroClaw와 같은 프로덕션 환경에서는 다음 사항을 고려해야 합니다.

에러 타입 구체화: String 대신 구체적인 thiserror나 anyhow 기반의 에러 타입을 사용하여 디버깅을 용이하게 하세요.
보안 샌드박싱: std::fs 대신 가상 파일 시스템(VFS) 라이브러리를 사용하여, 에이전트가 시스템 전체에 접근하는 것을 막아야 합니다.
Graceful Shutdown: tokio의 signal 모듈을 활용하여 인터럽트 신호(SIGTERM)를 처리하고, 진행 중인 파일 작업을 안전하게 종료해야 합니다.

5. 결론

Rust는 타입 안전성과 메모리 관리 능력 덕분에 신뢰할 수 있는 MCP 서버를 구축하는 데 최적의 언어입니다. 위 코드를 바탕으로 blog-api-server나 모니터링 시스템과 연동한다면, AI 모델이 직접 시스템 로그를 분석하고 패치를 제안하는 완전한 자동화 사이클을 구축할 수 있습니다.

다음 포스트에서는 이 MCP 서버를 ZeroClaw 런타임 위에서 어떻게 에이전트화하고, 다른 서비스와 통신하는지 다루겠습니다.

pg_durable 분석: Rust로 구현하는 내구성 있는 함수 실행

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

최근 Microsoft가 오픈 소스로 공개한 pg_durable은 데이터베이스 내에서 직접 ‘내구성 있는(Durable)’ 함수 실행을 가능하게 하는 실험적인 프로젝트입니다. 전통적인 마이크로서비스 아키텍처에서는 비즈니스 로직이 애플리케이션 계층에 위치하고, 데이터베이스는 단순히 상태를 저장하는 역할에 그치는 경우가 많습니다. 하지만 pg_durable은 로직과 데이터를 물리적으로 가까운 곳에 통합하여, 외부 시스템의 장애나 네트워크 비용을 최소화하는 접근 방식을 제시합니다.

이번 글에서는 pg_durable의 핵심 메커니즘을 분석하고, Rust와 PostgreSQL을 활용해 유사한 패턴을 구현하는 방법을 살펴보겠습니다.

pg_durable의 핵심 메커니즘

pg_durable의 가장 큰 특징은 함수의 상태(State)와 실행 흐름(Execution Flow) 자체를 데이터베이스 레코드로 저장한다는 점입니다. 일반적인 애플리케이션에서 HTTP 요청이 실패하면 메모리에 있던 컨텍스트가 사라지지만, pg_durable은 실행할 함수의 입력(Input)과 현재 단계(Step)를 테이블에 기록합니다.

이를 통해 다음과 같은 이점을 얻을 수 있습니다:

자동 복구 (Auto-Recovery): 서버가 크래시되어도 데이터베이스에는 ‘실행해야 할 작업’이 남아있으므로, 서버 재시작 후 남은 작업을 이어서 수행할 수 있습니다.
정확히 한 번 실행 (Exactly-Once Semantics): 데이터베이스 트랜잭션을 활용해 상태 업데이트와 로직 실행을 원자적으로 처리할 수 있습니다.

Rust로 데이터베이스 트리거 기반 워커 구현하기

pg_durable의 내부 구현은 복잡하지만, 이 패턴을 Rust와 PostgreSQL의 LISTEN/NOTIFY 기능을 사용해 간단하게 재현해 볼 수 있습니다. 이 접근 방식은 데이터베이스를 ‘메시지 브로커’처럼 활용하면서도 별도의 인프라 비용을 절약할 수 있습니다.

1. 데이터베이스 스키마 설계

먼저 작업(Job)을 저장할 테이블을 생성합니다.

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 워커 구현 (sqlx 사용)

Rust의 비동기 런타임과 sqlx를 사용하여, 데이터베이스에 새 작업이 들어오면 이를 감지하고 처리하는 워커를 작성해 보겠습니다.

# 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"

이제 Rust 코드로 워커를 구현합니다.

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> {
 // 데이터베이스 연결 풀 생성
 let pool = PgPool::connect("postgresql://user:password@localhost/mydb").await?;
 
 // 데이터베이스 변경 사항 감지 리스너 (pg_notify 활용)
 let mut listener = pool.acquire().await?.listen("job_channel");

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

 loop {
 // 알림 수신 대기
 let notification = listener.recv().await?;
 println!("Received notification: {}", notification.payload);

 // 알림을 받으면 실제 작업 처리 시도
 process_jobs(&pool).await?;
 }
}

async fn process_jobs(pool: &PgPool) -> Result<(), sqlx::Error> {
 // 트랜잭션 내에서 'pending' 상태의 작업을 가져와 '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);
 
 // 비즈니스 로직 실행 (예: 외부 API 호출 등)
 // 실제 환경에서는 여기서 무거운 작업을 수행합니다.
 let result = simulate_heavy_task(&payload).await;

 match result {
 Ok(_) => {
 // 성공 시 상태를 'completed'로 업데이트
 sqlx::query("UPDATE durable_jobs SET status = 'completed' WHERE id = $1")
 .bind(id)
 .execute(&mut *tx)
 .await?;
 }
 Err(e) => {
 // 실패 시 상태를 'failed'로 남겨두거나 재시도 로직 추가
 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>> {
 // 예시: 2초 대기
 sleep(Duration::from_secs(2)).await;
 println!("Task executed for user {}", payload.user_id);
 Ok(())
}

3. 작업 등록 트리거

실제로는 애플리케이션 레벨에서 INSERT 쿼리를 날린 후 NOTIFY를 보내거나, 트리거를 사용해 자동화할 수 있습니다.

-- 트리거 함수 및 트리거 생성 예시
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();

아키텍처 적용 시 고려사항

이 패턴(pg_durable 스타일)을 ZeroClaw나 MCP 서버와 같은 고성능 시스템에 적용할 때는 다음 사항을 고려해야 합니다.

데이터베이스 부하: 데이터베이스가 단순한 저장소가 아니라 실행 엔진의 역할을 일부 담당하므로, 워커가 너무 잦은 폴링(Polling)을 하거나 무거운 로직을 수행하면 DB 성능에 저하가 올 수 있습니다. SKIP LOCKED 구문을 사용해 여러 워커 인스턴스가 안전하게 분산 처리하도록 구성하는 것이 필수입니다.
확장성(Scale-out): 앞서 보여준 Rust 코드는 다중 프로세스로 실행하더라도 FOR UPDATE SKIP LOCKED 덕분에 안전하게 작업을 분산 처리할 수 있습니다. Kubernetes 환경이라면 HorizontalPodAutoscaler(HPA)를 통해 큐가 쌓일 때 워커 파드를 늘리는 식으로 유연한 대응이 가능합니다.

결론

Microsoft의 pg_durable은 ‘데이터 중심 아키텍처(Data-Centric Architecture)‘의 진화된 형태를 보여줍니다. 복잡한 메시지 큐(Kafka, RabbitMQ)를 도입하기 전, 데이터베이스의 트랜잭션 기능을 적극 활용해 간단하고 강력한 내구성을 확보해 보는 것은 어떨까요? 위의 예제 코드는 바로 실무에서 테스트해 볼 수 있는 형태이므로, 여러분의 사이드 프로젝트나 백오피스 시스템에 적용해 보시길 권장합니다.

SQLite 기반 영구적 워크플로우 설계: 'SQLite is all you need' 실전 가이드

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

SQLite로 워크플로우를 지속 가능하게 만드는 방법

최근 Hacker News에서 “SQLite is all you need for durable workflows"라는 글이 큰 화제가 되었습니다. 분산 시스템을 설계할 때 Kafka, Redis, 복잡한 클러스터링을 떠올리기 쉽지만, 정작 우리가 해결하려는 핵심 문제인 ‘상태 유지(State Management)‘와 ‘재시작 내성(Resiliency)‘은 단일 파일 데이터베이스인 SQLite만으로도 충분히 해결할 수 있다는 주장입니다.

저희 팀의 ‘ZeroClaw’나 ‘Discord Decision MCP’와 같은 에이전트 시스템을 개발하면서, 복잡한 메시지 큐를 도입하기 전에 SQLite의 가벼우면서도 강력한 트랜잭션 기능을 활용해 워크플로우 엔진을 직접 구현해 보았습니다. 이 글에서는 그 핵심 아키텍처와 실제 코드 예제를 공유합니다.

1. 영구적 워크플로우(Durable Workflow)란?

워크플로우가 ‘영구적’이다 한다는 것은, 프로그램이 죽거나 서버가 재시작되더라도 중단된 지점부터 다시 시작할 수 있음을 의미합니다. 이를 위해 우리는 다음 두 가지를 보장해야 합니다.

상태 저장(Snapshotting): 현재 진행 상황을 지속적으로 저장해야 합니다.
정확히 한 번 실행(Exactly-Once Semantics): 재시작 시 중복 실행을 방지해야 합니다.

2. 아키텍처 설계: SQLite를 큐와 상태 저장소로 사용하기

SQLite는 WAL(Write-Ahead Logging) 모드와 고급 잠금 메커니즘 덕분에 동시성 환경에서도 놀라운 성능을 냅니다. 워크플로우 엔진은 다음과 같은 테이블 구조를 기반으로 동작합니다.

데이터베이스 스키마

-- 작업의 현재 상태를 저장하는 테이블
CREATE TABLE workflows (
 id TEXT PRIMARY KEY,
 status TEXT NOT NULL, -- pending, running, completed, failed
 current_step INTEGER NOT NULL DEFAULT 0,
 payload TEXT, -- JSON 형태의 입력 데이터
 updated_at INTEGER NOT NULL
);

-- 실행해야 할 작업 목록 (큐)
CREATE TABLE jobs (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 workflow_id TEXT NOT NULL,
 target_step INTEGER NOT NULL,
 run_at INTEGER, -- 예약 실행 시간 (NULL 즉시 실행)
 FOREIGN KEY(workflow_id) REFERENCES workflows(id)
);

CREATE INDEX idx_jobs_run_at ON jobs(run_at);

Rust 구현 예제

Rust의 rusqlite 라이브러리를 사용하여 간단한 워크플로우 스케줄러를 작성해 보겠습니다. 이 코드는 ‘ZeroClaw’ 런타임의 가벼운 작업 스케줄링 로직에서 영감을 받았습니다.

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

fn main() -> Result<()> {
 // 1. 메모리 또는 파일 DB 연결 (WAL 모드 활성화 권장)
 let mut conn = Connection::open("workflow.db")?;
 conn.execute_batch("PRAGMA journal_mode=WAL;")?;

 // 2. 워크플로우 생성 (초기 상태)
 let workflow_id = "order-12345";
 insert_workflow(&mut conn, workflow_id, "{\"item\": \"keyboard\"}")?;

 // 3. 작업 예약 (결제 단계)
 enqueue_job(&mut conn, workflow_id, 1, None)?;

 // 4. 워커 루프 (실무에서는 데몬화)
 loop {
 match fetch_next_job(&mut conn)? {
 Some(job) => {
 println!("Processing job {} for workflow {}", job.target_step, job.workflow_id);
 
 // 비즈니스 로직 실행 (예: LLM 호출, 외부 API 요청)
 // simulate_work();

 // 성공 시 다음 스텝 예약 또는 완료 처리
 complete_step(&mut conn, &job.workflow_id, job.target_step)?;
 }
 None => {
 println!("No jobs, sleeping...");
 std::thread::sleep(Duration::from_secs(5));
 }
 }
 }
}

// 작업을 큐에 넣고, 워크플로우 상태를 '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()
}

// 다음 처리할 작업을 가져오는 함수 (Locking Read)
fn fetch_next_job(conn: &mut Connection) -> Result<Option<Job>> {
 // UPDATE 문을 통해 행을 잠그고 반환하는 기법 (UPDATE RETURNING)
 // SQLite 3.35.0 이상 지원
 let mut stmt = conn.prepare(
 "UPDATE jobs 
 SET workflow_id = workflow_id || ':processing' -- 임시 상태 표시 (실제로는 status 컬럼 추천)
 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),
 }
}

// 스템 완료 처리
fn complete_step(conn: &mut Connection, workflow_id: &str, step: i32) -> Result<()> {
 let tx = conn.transaction()?;
 
 // 완료된 작업 삭제
 tx.execute("DELETE FROM jobs WHERE workflow_id = ?1 AND target_step = ?2", params![workflow_id, 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. 왜 이 구조가 강력한가?

이 접근 방식의 가장 큰 장점은 관리 부하(Ops Overhead)가 거의 없다는 점입니다.

ZeroClaw와 같은 에이전트 시스템에서는 각 에이전트가 자신의 SQLite 파일을 가지고 동작하므로, 중앙 집중식 DB의 병목 현상을 피할 수 있습니다.
Discord MCP 같은 봇을 만들 때, 복잡한 Redis 컨테이너를 띄우는 대신 단순히 discord.db 파일만 백업해두면 모든 대화 기록과 처리 중인 작업을 완벽하게 보호할 수 있습니다.

4. 결론: “필요한 만큼만”

“SQLite is all you need"라는 제목은 SQLite가 모든 것을 대체할 수 있다는 뜻이 아니라, 대부분의 문제는 SQLite면 충분하다는 뜻입니다. 복잡한 분산 시스템을 도입하기 전에, 가장 단순하고 안정적인 파일 기반 데이터베이스로 워크플로우의 신뢰성을 확보해 보는 것은 어떨까요?

다음 포스트에서는 이 SQLite 워크플로우 엔진을 Kubernetes 환경에서 안정적으로 운영하기 위한 Persisntent Volume 전략에 대해 다루겠습니다.

Postgres 기반 Durable Workflow 구현: DB를 워크플로우 엔진처럼 쓰기

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

최근 빠르고 가벼운 마이크로 서비스 아키텍처를 구축하면서, 외부 의존성을 최소화하는 것이 중요한 과제로 떠올랐습니다. 특히 ZeroClaw 런타임 개발 과정에서 복잡한 상태 머신 관리와 에이전트 간의 통신 신뢰성을 보장하기 위해 Kafka나 Redis 같은 별도의 메시지 큐를 도입하려 했으나, 운영 복잡도가 우려되었습니다.

이때 눈에 들어온 것이 최근 Hacker News 등에서 화제가 된 ‘Postgres 기반 Durable Workflow’ 패턴입니다. 단순히 데이터를 저장하는 것을 넘어, 데이터베이스 자체를 워크플로우 엔진처럼 활용하여 상태 유지와 재시작(Retry) 로직을 처리하는 방식입니다. 이번 포스트에서는 이 패턴의 핵심 개념과 ZeroClaw 프로젝트에 적용한 실용적인 구현 방법을 공유합니다.

왜 Postgres인가?

기존에는 Temporal.io나 Cadence 같은 전문 워크플로우 엔진을 사용하거나, Kafka를 통해 이벤트 소싱을 구현했습니다. 하지만 소규모 팀이나 개인 프로젝트에서는 이러한 인프라를 유지하는 것이 큰 부담이 됩니다.

PostgreSQL은 이미 대부분의 서비스가 기본 데이터베이스로 채택하고 있습니다. ACID 트랜잭션을 통해 강력한 일관성을 보장하며, SKIP LOCKED 기능을 통해 분산 락(Claim-based lock)을 구현할 수 있습니다. 즉, ‘이미 우리가 가진 신뢰할 수 있는 저장소’를 큐(Queue)로, 스케줄러로, 그리고 상태 저장소로 활용하여 인프라 스택을 단순화할 수 있습니다.

핵심 아키텍처: 테이블을 큐처럼 사용하기

이 패턴의 핵심은 워크플로우의 상태(State)와 실행 대상(Task)을 테이블에 정의하는 것입니다. ZeroClaw의 에이전트 작업 큐를 예로 들어보겠습니다.

1. 상태 테이블 정의 (SQL)

우리는 작업의 현재 상태와 다음 실행 시점을 저장하기 위해 workflow_jobs 테이블을 설계했습니다.

CREATE TABLE workflow_jobs (
 id SERIAL PRIMARY KEY,
 job_type TEXT NOT NULL, -- 예: 'agent_task', 'discord_notify'
 payload JSONB NOT NULL, -- 실행에 필요한 데이터
 status TEXT NOT NULL DEFAULT 'pending', -- pending, running, succeeded, failed
 claimed_at TIMESTAMP,
 run_after TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- 지연 실행 또는 재시작 타임스탬프
 last_error TEXT,
 attempt_count INT DEFAULT 0,
 max_attempts INT DEFAULT 5,
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 상태 기반 인덱싱 (효율적인 조회를 위해)
CREATE INDEX idx_jobs_claim ON workflow_jobs (status, run_after) WHERE status = 'pending';

여기서 status와 run_after 컬럼이 핵심입니다. 이 두 컬럼을 통해 ‘지금 실행해야 할 작업’을 즉시 찾아낼 수 있습니다.

2. 작업 예약 및 실행 (Rust 예제)

이제 워커(Worker)는 트랜잭션 내에서 작업을 찾고(SELECT), 소유권을 주장(UPDATE)한 뒤 실행해야 합니다. 이 과정에서 경쟁 조건(Race Condition)을 방지하기 위해 FOR UPDATE SKIP LOCKED 구문을 사용합니다.

다음은 Rust와 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,
}

/// 워커가 실행 루프에서 호출할 함수
/// 트랜잭션 내에서 안전하게 작업을 할당받습니다.
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. 실행 가능한 작업을 찾고 락을 겁니다.
 // SKIP LOCKED: 다른 워커가 이미 락을 건 행은 무시하고 넘어갑니다.
 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?; // 할당받을 작업 없음 (Rollback은 불필요하지만 명시적 표현)
 return Ok(None);
 }
 };

 // 2. 작업 상태를 '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))
}

/// 작업 완료 후 상태를 업데이트하는 함수
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" };
 
 // 실패 시 지수 백오프(Exponential Backoff)를 고려하여 run_after를 계산할 수 있습니다.
 let next_run = if success {
 None
 } else {
 // 예: 10초 후 재시도 시도 (실제 구현에서는 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. 워커 루프 구성

이제 위 함수를 사용해 무한 루프(또는 Tokio의 tokio::time::interval)를 돌며 작업을 처리합니다.

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);
 
 // 실제 비즈니스 로직 실행 (예: LLM 추론, API 호출)
 let result = execute_logic(job.payload.clone()).await;

 // 결과 반영
 let _ = complete_job(&pool, job.id, result.is_ok(), result.err().map(|e| e.to_string())).await;
 }
 Ok(None) => {
 // 처리할 작업이 없으면 잠시 대기 (CPU 점유율 방지)
 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;
 }
 }
 }
}

장단점 및 활용 팁

장점:

단순성: 복잡한 분산 시스템 이론 없이 RDBMS의 트랜잭션만으로 신뢰성을 확보합니다.
운영 효율성: DB만 백업하면 워크플로우 상태도 함께 복구됩니다.
강력한 일관성: 메시지 유실(In-flight loss)에 대한 걱정이 없습니다.

단점:

처리량 처리량: Postgres는 연결당 처리량에 한계가 있으므로, 초당 수만 건 이상의 처리량이 필요하면 전문 MQ가 낫습니다.
DB 부하: 워커가 순환 쿼리(Polling)를 지속적으로 수행하므로, pgbouncer 등을 통해 연결 풀을 최적화해야 합니다.

결론

ZeroClaw의 멀티 에이전트 환경에서는 개별 에이전트의 메시지 처리량이 Kafka를 도입할 만큼 높지 않지만, 상태 관리의 신뢰성은 매우 중요했습니다. Postgres 기반 아키텍처를 통해 별도의 인프라 도입 없이 ‘안정적인 상태 관리’와 ‘확장 가능한 작업 큐’를 모두 달성할 수 있었습니다.

만약 당신의 프로젝트가 ‘단순함’과 ‘신뢰성’ 사이에서 고민하고 있다면, 굳이 무거운 솔루션을 도입하기 전에 가까운 곳에 있는 Postgres를 워크플로우 엔진으로 활용해 보는 것은 어떨까요?

참고자료

Building durable workflows on Postgres (Hacker News 토론)
SKIP LOCKED와 분산 락 구현

Rust로 구축하는 ZeroClaw: LLM 기반 멀티 에이전트 런타임 아키텍처

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

Rust로 구축하는 ZeroClaw: LLM 기반 멀티 에이전트 런타임 아키텍처

최근 LLM(Large Language Model)을 활용한 자동화와 에이전트 시스템에 대한 관심이 뜨겁습니다. 하지만 단일 에이전트로 복잡한 작업을 처리하는 데에는 한계가 있으며, 이를 해결하기 위해 **멀티 에이전트 시스템(Multi-Agent System)**이 주목받고 있습니다. 이번 포스트에서는 고성능과 안정성을 위해 Rust로 작성된 에이전트 런타임인 ZeroClaw의 아키텍처를 소개하고, 실제로 에이전트 간 통신을 어떻게 구조화하는지 살펴보겠습니다.

1. 왜 Rust인가? (Performance & Safety)

LLM 애플리케이션은 대부분 Python으로 작성되곤 합니다. 하지만 여러 에이전트가 동시에 실행되고 각자 독립된 메모리 공간이나 파일 시스템을 제어해야 하는 ‘런타임’ 환경에서는 Rust의 강력한 병렬 처리 능력과 메모리 안전성이 큰 무기가 됩니다.

특히, 최근 Hacker News에서 논의된 것처럼 “LLM 에이전트의 백엔드 코드 생성 취약점(Constraint Decay)” 문제가 대두되고 있습니다. LLM이 생성한 코드가 의도치 않게 시스템 제약을 무너뜨리는 상황에서, Rust의 타입 시스템과 소유권(Ownership) 모델은 런타임 차원에서 안전망을 제공할 수 있습니다.

2. ZeroClaw의 핵심 아키텍처

ZeroClaw는 단순한 LLM 래퍼가 아니라, 에이전트의 생명주기를 관리하고 메시지를 중계하는 런타임 엔진입니다.

2.1. 파일 기반 상태 관리 (File-Based State Management)

복잡한 데이터베이스 없이 에이전트의 상태와 컨텍스트를 파일 시스템에 기반하여 관리하는 아키텍처를 채택했습니다. 이는 휴대성(Portability)과 디버깅 용이성을 높여줍니다.

// 에이전트 상태를 저장하는 구조체 예시
#[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(())
 }
}

이 접근 방식은 Multi-Agent: 파일 기반 아키텍처 설계 논의에서 언급된 바와 같이, 각 에이전트가 자신의 상태를 투명하게 기록하게 하여 시스템 전체의 예측 가능성을 높입니다.

2.2. 이벤트 기반 통신 (Event-Driven Communication)

ZeroClaw의 에이전트들은 서로 직접 호출하지 않고, 중앙의 **이벤트 버스(Event Bus)**나 Pub/Sub 메커니즘을 통해 통신합니다. 이는 결합도(Coupling)를 낮추고 확장성을 확보합니다.

// 통신 프로토콜 메시지 정의
#[derive(Debug, Clone)]
pub enum AgentMessage {
 TaskRequest { task_id: String, payload: String },
 TaskResponse { task_id: String, result: String },
 StatusUpdate { agent_id: String, status: String },
}

// 간단한 채널 기반 메시지 라우터 (tokio::sync::mpsc 사용)
pub struct MessageRouter {
 // sender: HashMap<AgentId, Sender<AgentMessage>>
 // 실제 구현 시 에이전트별 채널을 관리
}

이러한 구조는 Claude Code 팀 에이전트 통신 아키텍처나 멀티 에이전트 통신 프로토콜 설계에서 고민되었던 ‘메시지 큐의 신뢰성’ 이슈를 Rust의 강력한 비동기 런타임(tokio)으로 해결하는 기반이 됩니다.

3. MCP(Model Context Protocol)와의 연동

ZeroClaw는 MCP 서버와 클라이언트 역할을 수행하여 외부 도구(예: 블로그 API, Discord Gateway)와 연동됩니다. 최근 blog-api-server에 추가된 언어 파라미터나 로깅 개선 사항들은 ZeroClaw 에이전트가 외부 시스템과 상호작용할 때 컨텍스트를 잃지 않도록 돕습니다.

에이전트가 MCP 도구를 호출하는 과정을 안전하게 래핑(Wrapping)하는 것은 중요합니다.

// MCP 도구 호출을 위한 안전한 래퍼
pub async fn invoke_mcp_tool(tool_name: &str, params: serde_json::Value) -> Result<String, AgentError> {
 // 1. 파라미터 검증 (Validation)
 if !validate_params(tool_name, &params) {
 return Err(AgentError::InvalidInput);
 }

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

 // 3. 응답 파싱 및 로깅
 tracing::info!("MCP Tool {} called successfully", tool_name);
 Ok(response.text().await?)
}

4. 결론: 2026 상반기 발전 방향

ZeroClaw는 단순한 실험적 프로젝트를 넘어, 2026 상반기 발전방향 회의록에서 언급된 바와 같이 ‘고성능 에이전트 런타임’으로 진화하고 있습니다.

Rust의 성능을 바탕으로 LLM의 생성성(Creativity)과 시스템의 안전성(Safety)을 동시에 확보하는 것이 목표입니다. 특히, 최근 트렌드인 DeepSeek와 같은 효율적인 모델을 통합하여 비용 효율성까지 개선할 계획입니다.

다음 포스트에서는 ZeroClaw 에이전트가 실제로 코드를 생성하고 배포하는 CI/CD 파이프라인 연동 사례를 다루겠습니다.

참고 링크

MCP(Model Context Protocol) 기반 멀티 에이전트 시스템 설계 및 구현 가이드

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

MCP(Model Context Protocol) 기반 멀티 에이전트 시스템 설계 및 구현 가이드

최근 생성형 AI 도메인에서 단일 LLM(Large Language Model)의 한계를 극복하기 위해 **멀티 에이전트 시스템(Multi-Agent System)**이 주목받고 있습니다. 특히, 에이전트 간의 표준화된 통신을 위한 **MCP(Model Context Protocol)**가 등장하면서, 확장 가능하고 모듈화된 아키텍처를 설계하는 것이 필수적이 되었습니다.

본 포스트에서는 ZeroClaw와 같은 고성능 에이전트 런타임 환경에서 MCP를 활용해 효율적인 멀티 에이전트 아키텍처를 설계하고 구현하는 방법을 살펴봅니다. 독자가 바로 적용할 수 있도록 아키텍처 설계 원칙과 실제 코드 예제를 포함했습니다.

1. MCP 기반 멀티 에이전트 아키텍처 설계

멀티 에이전트 시스템을 구축할 때 가장 중요한 것은 결합도(Coupling)를 낮추고 응집도(Cohesion)를 높이는 것입니다. MCP는 이를 달성하기 위해 클라이언트-서버 모델을 채택하여, 각 에이전트나 도구가 독립적인 서버로 동작하며 표준 프로토콜(JSON-RPC 2.0 기반)을 통해 통신하도록 합니다.

핵심 설계 원칙

표준화된 인터페이스 (Standardized Interface): 모든 에이전트는 MCP 표준을 준수하여 tools, resources, prompts를 노출해야 합니다.
비동기 통신 (Asynchronous Communication): 작업 수행 시간이 긴 에이전트(예: 파일 처리, 웹 스크래핑)를 위해 비동기 메시지 큐를 활용해야 합니다.
상태 비저장 (Stateless): 에이전트 서버는 가능한 한 상태 비저장으로 설계하여 수평 확장(Scale-out)이 용이하게 만들어야 합니다.

아키텍처 다이어그램 (개념적)

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

이 구조에서 **Gateway(오케스트레이터)**는 사용자의 요청을 분석하여 적절한 MCP 서버(에이전트)에게 작업을 위임하고, 결과를 취합하여 다시 사용자에게 전달하는 역할을 수행합니다.

2. MCP 서버 구현: Rust로 가벼운 에이전트 만들기

blog-api-server나 ZeroClaw 환경에서 고성능을 발휘하기 위해 Rust로 간단한 MCP 서버를 구현해 보겠습니다. 이 서버는 현재 시간을 반환하는 간단한 도구를 제공합니다.

의존성 설정 (Cargo.toml)

Rust의 강력한 비동기 런타임인 tokio와 JSON 처리를 위한 serde, 그리고 MCP 통신을 위한 hyper 또는 jsonrpc를 사용합니다.

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

MCP 서버 코드 예제

다음은 STDIN/STDOUT을 통해 통신하는 표준 MCP 서버의 뼈대를 간소화하여 구현한 것입니다.

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

// MCP 요청/응답 구조체 정의
#[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" => {
 // 클라이언트가 서버의 능력을 확인할 때 호출
 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" => {
 // 사용 가능한 도구 목록 반환
 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" => {
 // 실제 도구 실행 로직
 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,
 };
 }
 }
 // 에러 처리
 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();
 }
 }
}

이 코드는 MCP의 핵심인 initialize, tools/list, tools/call 메서드를 처리하여 LLM(예: Claude Code)이 이 에이전트를 도구로 인식하고 호출할 수 있게 합니다.

3. 에이전트 간 통신 및 데이터 동기화

ZeroClaw 아키텍처에서와 같이 여러 에이전트가 협업할 때는 데이터 공유가 중요합니다. 파일 기반 아키텍처(File-based architecture)를 사용하면 에이전트 간 결합도를 낮추면서 데이터를 주고받을 수 있습니다.

파일 기반 상태 공유 예시

에이전트 A가 데이터를 생성하고, 에이전트 B가 이를 소비하는 시나리오입니다.

에이전트 A (생산자): 계산 결과를 /tmp/shared/task_result.json에 저장합니다.
에이전트 B (소비자): MCP를 통해 file://tmp/shared/task_result.json 리소스를 읽거나, 별도의 read_file 도구를 호출합니다.

// 에이전트 A의 도구 호출 예시 (의사 코드)
fn save_result(data: &str) -> std::io::Result<()> {
 fs::write("/tmp/shared/task_result.json", data)?;
 Ok(())
}

이 방식은 메시지 큐가 복잡할 때 유용하며, blog-api-server의 로깅 시스템이나 모니터링 대시보드처럼 데이터를 지속적으로 추적해야 할 때 유효합니다.

4. 결론 및 발전 방향

MCP를 활용하면 복잡한 멀티 에이전트 시스템을 모듈화하고 유지보수하기 쉽게 만들 수 있습니다.

장점: 언어에 독립적인 인터페이스(Rust, TypeScript 등 혼용 가능), 도구의 재사용성, 표준화된 에러 처리.
고려사항: STDIN/STDOUT 통신 오버헤드, 대규모 트래픽 처리를 위한 Gateway의 부하 분산.

향후 ZeroClaw 런타임 내에서 이러한 MCP 서버들을 컨테이너화하여 필요에 따라 동적으로 스케일링(Scale-out)하는 환경을 구축하는 것이 목표입니다. 이를 통해 LLM이 단순한 챗봇을 넘어, 복잡한 작업을 자동화하는 지능형 에이전트 네트워크로 진화할 수 있습니다.

참고 자료

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

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

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

최근 LLM(Large Language Model)을 활용한 에이전트 시스템이 급격히 발전하고 있습니다. Hacker News에서는 “Forge – Guardrails take an 8B model from 53% to 99% on agentic tasks"라는 흥미로운 사례가 화제가 되었습니다. 이는 모델의 파라미터 수를 늘리는 것보다, 적절한 **가드레일(Guardrails)**을 적용하는 것이 특정 작업의 성공률을 비약적으로 높일 수 있음을 시사합니다.

저희 팀에서 진행 중인 ZeroClaw 및 MCP(Model Context Protocol) 기반 프로젝트들에 있어 에이전트의 신뢰성은 필수적입니다. 이번 포스트에서는 오픈소스 가드레일 프레임워크인 Forge의 개념을 살펴보고, 이를 기존 MCP 아키텍처에 통합하여 에이전트의 안정성을 확보하는 구체적인 방법을 소개합니다.

문제 정의: 자율성의 딜레마

에이전트에게 자율성을 부여할수록 예상치 못한 행동을 할 위험이 커집니다. 예를 들어, 블로그 게시글을 생성하라는 MCP 요청이 있을 때, 에이전트가 시스템 명령어를 실행하거나 허용되지 않은 API를 호출하려 시도할 수 있습니다.

기존의 [blog-api-server] 구현에서는 프롬프트 엔지니어링과 간단한 JSON 스키마 검증으로 이를 방어하려 했으나, 복잡한 멀티 에이전트 환경에서는 한계가 있었습니다. 이를 해결하기 위해 입력과 출력을 사전에 필터링하는 L1 가드레일 레이어를 도입하기로 결정했습니다.

솔루션: Guardrails 패턴 적용

Forge가 보여주듯, 에이전트 작업의 성공률(53% → 99%)을 높이는 핵심은 실행 전 검증입니다. 우리는 에이전트가 LLM으로부터 응답을 받아 사용자에게 전달하거나 도구(Tool)를 실행하기 전, 중간 계층에서 이를 검증하는 구조를 설계했습니다.

아키텍처 개요

기존 MCP 클라이언트와 LLM 사이에 Validator 계층을 두어 다음을 수행합니다.

입력 검증 (Input Validation): 사용자의 요청이 시스템 정책을 위반하지 않는지 확인 (예: 공격적인 프롬프트 필터링).
출력 검증 (Output Validation): LLM이 생성한 JSON이나 함수 호출 인자가 스키마에 부합하는지 확인.

실전 코드 예제: Rust로 구현하는 안전장치

ZeroClaw의 Rust 환경에서 가벼운 출력 검증기를 구현해 보겠습니다. 복잡한 외부 라이브러리 없이, serde와 regex를 활용하여 LLM이 생성한 코드 실행 명령을 안전하게 감싸는 예제입니다.

1. 검증 로직 구현하기

먼저, 에이전트가 생성한 명령어가 안전한지 판별하는 간단한 검증기입니다.

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

// 에이전트가 생성할 수 있는 명령어 구조
#[derive(Debug, Serialize, Deserialize)]
struct AgentCommand {
 tool_name: String,
 parameters: String,
}

pub struct Guardrail;

impl Guardrail {
 // 위험한 문자열 필터링 (간단한 예시)
 fn is_dangerous(input: &str) -> bool {
 let dangerous_patterns = vec!["rm -rf", "sudo", "eval", "__import__"];
 dangerous_patterns.iter().any(|&pat| input.contains(pat))
 }

 // 명령어 실행 전 검증 로직
 pub fn validate_command(cmd: &AgentCommand) -> Result<&AgentCommand, String> {
 // 1. 도구 이름 화이트리스트 확인
 let allowed_tools = vec!["blog_post", "search", "read_file"];
 if !allowed_tools.contains(&cmd.tool_name.as_str()) {
 return Err(format!("허용되지 않은 도구 사용 시도: {}", cmd.tool_name));
 }

 // 2. 파라미터 내 위험 키워드 검사
 if Self::is_dangerous(&cmd.parameters) {
 return Err("파라미터에 잠재적으로 위험한 명령어가 포함되어 있습니다.".to_string());
 }

 // 3. 안전하다면 명령어 승인
 Ok(cmd)
 }
}

2. 에이전트 루프에 통합하기

이제 검증기를 MCP 서버의 요청 처리 루프에 연결합니다. 에이전트가 응답을 생성하면, 실제 시스템이 이를 실행하기 전에 Guardrail을 거쳐야 합니다.

// 가상의 에이전트 실행 함수
fn execute_agent_task(llm_output: &str) -> Result<String, String> {
 // 1. LLM 출력 파싱 (실제로는 JSON 파싱 등)
 // 여기서는 간단히 파싱되었다고 가정합니다.
 let command = AgentCommand {
 tool_name: "blog_post".to_string(),
 parameters: "title: 'Hello World'".to_string(),
 };

 // 2. 가드레일 통과 전
 println!("[System] LLM 응답 수신: {}", command.tool_name);

 // 3. 가드레일 검증 실행
 let safe_command = Guardrail::validate_command(&command)?;

 // 4. 검증된 명령어 실행
 println!("[System] 안전한 명령어 실행 중...");
 // 실제 도구 실행 로직 (예: 블로그 API 호출)
 Ok("게시글이 성공적으로 생성되었습니다.".to_string())
}

fn main() {
 // 정상 케이스
 match execute_agent_task("valid_response") {
 Ok(msg) => println!("성공: {}", msg),
 Err(e) => println!("차단됨: {}", e),
 }

 // 비정상 케이스 시뮬레이션
 let malicious_cmd = AgentCommand {
 tool_name: "system_shell".to_string(), // 화이트리스트에 없음
 parameters: "rm -rf /".to_string(),
 };

 match Guardrail::validate_command(&malicious_cmd) {
 Ok(_) => println!("오류: 해커가 침입했습니다!"),
 Err(e) => println!("보호됨: {}", e), // "보호됨: 허용되지 않은 도구 사용 시도: system_shell"
 }
}

효과 및 전망

이러한 L1 방어선을 구축함으로써 우리는 다음과 같은 이점을 얻을 수 있습니다.

안정성 향상: Forge 사례처럼 8B 모델도 충분히 안전하게 활용할 수 있어 추론 비용 절감.
투명성 확보: 에이전트가 왜 특정 작업을 거부했는지 로그를 통해 명확히 파악 가능.
유지보수성: 보안 정책이 변경되어도 Guardrail 모듈만 수정하면 됨.

앞으로 ZeroClaw 프로젝트에서는 이 검증 로직을 비동기 런타임에 통합하여, 멀티 에이전트 간 통신([Discord MCP], [Cloud Monitor]) 시에도 실시간으로 안전성을 모니터링할 계획입니다.

단순히 모델의 성능을 높이는 것에 집착하기보다, 이처럼 시스템 레벨에서의 안전장치를 어떻게 설계하느냐가 AI 에이전트를 실제 프로덕션에 배포하는 관건이 될 것입니다.

이 글은 ZeroClaw 및 MCP 관련 아키텍처 설계 문서들을 참고하여 작성되었습니다.

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

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

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

안녱하세요! ZeroClaw 프로젝트의 진행에 따라 고성능 Rust 에이전트 런타임과 멀티 에이전트 시스템을 구축하며 겪은 설계상의 고민과 해결 과정을 공유하고자 합니다. 최근 ‘Obsidian 플러그인을 악용한 원격 접속 트로이어나(RAT)’ 사건과 같은 보안 이슈들은 플러그인 및 에이전트 시스템에서 **보안(Security)**과 **신뢰성(Trust)**이 얼마나 중요한지를 다시금 상기시켜 줍니다.

오늘은 ZeroClaw의 코드베이스를 분석하며 설계한, 안전하고 확장 가능한 에이전트 간 통신 프로토콜을 구체적인 Rust 코드 예제와 함께 소개하겠습니다.

1. 서론: 보안을 고려한 에이전트 통신의 필요성

기존의 MCP(Model Context Protocol)나 블로그 자동화 시스템 구축 과정에서 우리는 단순한 데이터 전송을 넘어, 에이전트 간의 **신원 확인(Authentication)**과 **권한 부여(Authorization)**가 필수적임을 깨달았습니다. 특히 여러 에이전트가 협업하여 파일을 생성하거나 외부 API를 호출하는 멀티 에이전트 환경에서는 악의적인 명령 삽입을 방지하는 메커니즘이必不可少입니다.

ZeroClaw는 이를 위해 Rust의 타입 안전성(Type Safety)과 소유권(Ownership) 시스템을 적극 활용하여, 컴파일 타임에 많은 버그를 잡고 런타임 오버헤드를 최소화하는 아키텍처를 채택했습니다.

2. 통신 프로토콜 설계: IPC와 메시지 큐

ZeroClaw의 통신 플랫폼은 크게 **로컬 IPC(Inter-Process Communication)**와 비동기 메시지 큐로 나뉩니다. 로그 시스템 개선 과정에서 얻은 경험을 바탕으로, 모든 통신은 비동기(async)로 처리되며 각 에이전트의 독립성을 보장합니다.

주요 설계 원칙

Zero-Copy Serialization: serde와 bincode를 활용하여 데이터 직렬화 오버헤드를 최소화합니다.
Message Validation: 들어오는 모든 메시지를 검증하는 레이어를 두어, 변조된 데이터가 시스템 코어에 도달하는 것을 방지합니다.
Capability-Based Security: 단순한 토큰 기반 인증 넘어, 에이전트가 수행할 수 있는 행위(Capability) 자체를 제한합니다.

3. Rust로 구현하는 안전한 메시징 핸들러

이제 실제 코드를 통해 어떻게 구현했는지 살펴보겠습니다. 이 예제는 tokio를 기반으로 하며, 안전한 메시지 전달을 위한 기본 구조를 보여줍니다.

3.1 메시지 정의 및 검증

먼저, 에이전트 간에 오가는 데이터 구조를 정의하고, validator 크레이트를 사용하여 입력값을 검증합니다.

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

/// 에이전트 간 통신 메시지 타입
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AgentMessage {
 TaskRequest { id: String, payload: TaskPayload },
 TaskResponse { id: String, result: String },
 Heartbeat,
}

/// 작업 페이로드 (검증 로직 포함)
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct TaskPayload {
 #[validate(length(min = 1, max = 100))]
 pub command: String,
 
 // JSON 형식의 인자를 받지만, 구조적으로 안전하게 파싱해야 함
 pub args: serde_json::Value, 
}

impl AgentMessage {
 /// 바이트 배열로부터 안전하게 메시지를 역직렬화합니다.
 pub fn from_bytes(bytes: &[u8]) -> Result<Self, Box<dyn std::error::Error>> {
 // 1. 기본 직렬화 검증
 let msg: AgentMessage = bincode::deserialize(bytes)?;
 
 // 2. 비즈니스 로직 검증 (예: Command Injection 방지)
 if let AgentMessage::TaskRequest { payload, .. } = &msg {
 payload.validate()?; // validator 크레이트 사용
 
 // 보안: 허용되지 않는 쉘 명령어 필터링 예시
 if payload.command.contains("rm ") || payload.command.contains("sudo") {
 return Err("Blocked potentially dangerous command".into());
 }
 }
 
 Ok(msg)
 }
}

3.2 액터 모델 기반 에이전트 구조

각 에이전트는 자신의 상태를 가지며, 메시지를 받아 처리하는 Actor 패턴을 따릅니다. Rust의 tokio::sync::mpsc 채널을 사용하여 메일박스를 구현합니다.

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

pub struct Agent {
 id: String,
 receiver: mpsc::Receiver<AgentMessage>,
 // 에이전트의 상태는 여기에 캡슐화되어 외부에서 직접 접근 불가
}

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

 /// 에이전트의 메인 루프
 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);
 // 여기에 실제 작업 실행 로직 (예: LLM 호출, 파일 쓰기 등)
 // 안전 장치: 샌드박스 환경에서 실행하거나 권한을 제한합니다.
 },
 AgentMessage::Heartbeat => {
 // 생존 신호 처리
 },
 _ => return Err("Unknown message type".into()),
 }
 Ok(())
 }
}

3.3 런타임 및 메시지 라우팅

마지막으로, 여러 에이전트를 생성하고 메시지를 라우팅하는 간단한 런타임 시스템입니다.

// 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);
 
 // 에이전트를 별도의 태스크로 실행
 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. 마무리 및 다음 단계

위에서 구현한 코드는 ZeroClaw 멀티 에이전트 시스템의 핵심인 **‘안전한 통신’**과 **‘격리된 상태 관리’**를 보여줍니다. Obsidian 플러그인 사건처럼, 외부 입력이나 스크립트를 실행하는 시스템은 언제나 공격의 대상이 될 수 있습니다.

ZeroClaw는 Rust의 강력한 타입 시스템을 통해 이러한 위험을 컴파일 타임에 대부분 차단하고, 런타임에도 추가적인 검증 레이어를 두어 방어합니다. 다음 포스트에서는 이 에이전트 시스템이 실제로 Discord나 MCP와 같은 외부 게이트웨이와 어떻게 연동되는지, 그리고 LLM 설정을 통해 어떻게 제어되는지에 대해 다루겠습니다.

지금까지 ZeroClaw의 아키텍처 설계 현황을 공유했습니다. 고성능이면서도 안전한 에이전트 시스템을 구축하려는 분들께 도움이 되기를 바랍니다!

참고: 위 코드는 개념 증명(POC) 수준의 예제이며, 실제 프로덕션 환경에서는 더욱 견고한 에러 핸들링과 로깅 시스템(이전 포스트에서 개선한 로깅 설정 참조)이 통합되어야 합니다.

Rust로 구현하는 고성능 MCP 서버: ZeroMQ를 활용한 비동기 메시징

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

Rust로 구현하는 고성능 MCP 서버: ZeroMQ를 활용한 비동기 메시징

최근 ZeroClaw 프로젝트를 진행하며 MCP(Model Context Protocol) 서버의 성능 한계를 뛰어넘을 필요성이 생겼습니다. 기존의 HTTP 기반 통신은 단일 요청-응답 패턴을 벗어나기 어렵고, 수많은 LLM 에이전트 간의 실시간 통신에는 병목이 발생하기 쉽습니다. 이번 포스트에서는 Rust의 강력한 비동기 처리 능력과 ZeroMQ(ØMQ)를 결용하여 초경량 초고속 MCP 서버를 구축하는 과정을 다룹니다.

왜 ZeroMQ인가? (TCP 소켓의 한계와 비교)

기존 blog-api-server 아키텍처에서는 표준 TCP 스트림을 사용하여 프로토콜을 직접 정의하고 사용했습니다. 하지만 멀티 에이전트 환경에서는 다음과 같은 문제가 발생합니다.

Connection Management(연결 관리) 복잡도: 에이전트가 수십 개씩 늘어날 때, Accept 루프와 소켓 상태 관리를 위한 unsafe 코드나 복잡한 상태 머신(State Machine)이 필요합니다.
Message Enveloping(메시지 봉투): TCP는 바이트 스트림입니다. 메시지의 경계를 구분하기 위해 Length-Prefixing을 직접 구현해야 하며, 이는 버그의 주요 원인이 됩니다.

ZeroMQ는 이러한 하부 소켓 계층의 복잡성을 추상화하면서, TCP보다 빠른 “사용자 공간(User Space)” 전송 계층을 제공합니다. 특히 ipc(Inter-Process Communication) 프로토콜을 사용하면 로컬호스트 통신에서 네트워크 스택 오버헤드를 완전히 제거할 수 있습니다.

아키텍처 설계: ZeroMQ PUB/SUB 패턴

이번 구현에서는 에이전트 간 느슨한 결합을 위해 Publish/Subscribe(PUB/SUB) 패턴을 사용합니다. 하나의 에이전트가 상태를 변경(Publish)하면, 해당 토픽을 구독하는 다른 에이전트들에게 즉시 메시지가 브로드캐스트됩니다.

주요 의존성 (Cargo.toml)

Rust 생태계에서 ZeroMQ는 zmq 크레이트를 통해 사용할 수 있습니다. 비동기 런타임과의 통합을 위해 tokio-zmq를 사용할 수도 있지만, 순수 성능을 위해 zmq의 poll 기능을 활용하는 것이 더 안정적일 때가 많습니다.

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

구현: 고성능 MCP Router

아래 코드는 간단한 메시지 브로커 역할을 하는 MCP Router의 구현 예제입니다. 이는 여러 LLM 에이전트(팀)가 서로 통신할 수 있는 중앙 허브 역할을 합니다.

1. 메시지 프로토콜 정의

먼저, 에이전트 간에 오가는 메시지 형식을 정의합니다. JSON 직렬화를 사용하여 호환성을 확보합니다.

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. 비동기 ZeroMQ 컨텍스트 및 소켓 설정

ZeroMQ의 Context는 스레드 안전(Thread-safe)하므로, 애플리케이션 전역에서 하나만 생성하여 공유하는 것이 일반적입니다.

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

struct McpRouter {
 context: Context,
 frontend: Socket, // Agents connect here
 // 필요시 다른 패턴의 소켓 추가 가능
}

impl McpRouter {
 fn new() -> Result<Self, zmq::Error> {
 let context = Context::new();
 let frontend = context.socket(SocketType::SUB)?;
 
 // 모든 메시지를 수신하도록 설정 (필터링 없음)
 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 {
 // Non-blocking receive를 위해 poll 사용 가능
 // 여기서는 간단한 blocking receive 예시
 match self.frontend.recv(&mut msg) {
 Ok(_) => {
 let data = msg.as_str().unwrap();
 // 메시지 파싱 및 라우팅 로직
 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) {
 // 실제 라우팅 로직 구현
 println!("Routing from {} on topic {}", msg.source_id, msg.target_topic);
 // 예: 데이터베이스 저장, 다른 소켓으로 전달 등
 }
}

3. 에이전트 발행(Publisher) 구현

이제 개별 에이전트가 메시지를 보내는 코드를 작성해 보겠습니다. tokio와 함께 사용할 때는 별도의 스레드에서 ZeroMQ의 blocking 함수를 실행해야 비동기 런타임을 방해하지 않습니다.

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");

 // 별도 스레드에서 실행하여 Tokio 런타임과 분리
 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는 전송 실패 시 자동으로 재시도하거나 큐에 쌓음 (High-water mark 설정 필요 시)
 sender.send(json_str.as_bytes(), 0).expect("Failed to send");
 
 thread::sleep(std::time::Duration::from_millis(100));
 }
 });
}

성능 최적화 및 IPC 활용

Rust ZeroMQ 서버의 진정한 힘은 IPC(Inter-Process Communication) 트랜스포트를 사용할 때 발휘됩니다. TCP를 사용하면 패킷이 네트워크 스택을 거쳐 루프백(Loopback) 되지만, IPC는 Unix Domain Socket이나 Windows Named Pipes를 사용하여 메모리 복사 수준에 가까운 속도로 통신합니다.

ipc 프로토콜을 사용하려면 엔드포인트를 다음과 같이 변경하면 됩니다.

// TCP 대신 IPC 사용
let endpoint = "ipc:///tmp/mcp_router.ipc";
router.start(endpoint);

Bun이나 Zig 같은 최신 언어들이 시스템 레벨 최적화를 통해 주목받는 것처럼, Rust와 ZeroMQ의 조합은 LLM 애플리케이션의 “시스템 버스"를 구축하는 데 있어 가장 강력한 도구입니다.

결론

이번 글에서는 ZeroClaw 프로젝트의 일환으로, Rust와 ZeroMQ를 사용하여 고성능 MCP 서버를 구축하는 방법을 살펴보았습니다. 단순한 HTTP 요청을 넘어, 에이전트 간 실시간 메시징이 필요한 환경에서 이 아키텍처는 확장성과 성능 면에서 큰 이점을 제공합니다.

다음 포스트에서는 이 메시징 시스템에 안정성을 더해주는 Circuit Breaker 패턴과 에러 핸들링 전략을 다루겠습니다.

참고 자료

ZeroClaw 에이전트 런타임의 메모리 안전성과 효율적인 리소스 관리

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

ZeroClaw 에이전트 런타임의 메모리 안전성과 효율적인 리소스 관리

최근 ZeroClaw 프로젝트를 통해 고성능 멀티 에이전트 런타임을 구축하면서, Rust의 특장점인 ‘메모리 안전성’과 ‘제로 비용 추상화’를 실전에서 어떻게 활용할지 고민하게 되었습니다. 단순히 안전하다는 것을 넘어, 수많은 에이전트가 동시에 메시지를 주고받는 상황에서 어떻게 시스템 리소스를 효율적으로 관리하고 GC(Garbage Collection) 없이 안정적인 성능을 유지할 수 있는지가 핵심 과제였습니다.

이 글에서는 ZeroClaw 아키텍처 설계 과정에서 적용한 Rust 기반의 효율적인 리소스 관리 전략과 실제 코드 예제를 공유하고자 합니다.

문제 정의: 멀티 에이전트 환경의 리소스 병목

멀티 에이전트 시스템에서는 각 에이전트가 독립적인 상태(State)를 가지며, 서로 비동기 메시지를 통해 통신합니다. 이 과정에서 다음과 같은 리소스 이슈가 발생합니다.

빈번한 할당/해제 (Allocation Thrashing): 수백 개의 에이전트가 초당 수천 개의 메시지를 처리할 때, 힙(Heap) 메모리의 잦은 할당과 해제는 성능 저하의 주원인이 됩니다.
데이터 경합 (Data Race): 여러 에이전트가 공유 리소스에 접근할 때 발생할 수 있는 경합 조건(Race Condition)을 방지하면서도, 지나친 락(Lock) 사용으로 인한 병목을 피해야 합니다.
수명 주기 관리: 에이전트가 비정상적으로 종료되더라도 시스템 전체의 메모리 누수가 발생하지 않도록 안전하게 리소스를 회수하는 메커니즘이 필요합니다.

해결 전략: Rust의 소유권과 Tokio의 스케줄링

ZeroClaw에서는 이러한 문제를 해결하기 위해 Rust의 소유권(Ownership) 시스템과 tokio 런타임의 비동기 추상화를 결합했습니다.

1. `Arc`와 `RwLock`을 활용한 상태 공유

에이전트 간 통신에서 불변(Immutable) 데이터 공유는 Arc (Atomic Reference Counting)를 통해 비용을 최소화했습니다. 상태 업데이트가 필요한 경우에는 RwLock을 사용하여 읽기 작업이 병렬로 수행되도록 허용하면서 쓰기 작업 시에만 데이터 무결성을 보장했습니다.

2. 채널(Channel) 기반 메시지 전달

공유 메모리 상태를 직접 제어하는 대신, tokio::sync::mpsc 채널을 통해 메시지를 전달하는 방식(Actor 모델)을 채택했습니다. 이는 각 에이전트가 자신의 상태를 독점적으로 관리하게 하여 데이터 경합을 근본적으로 차단합니다.

실전 코드 예제

다음은 ZeroClaw의 통신 계층에서 사용하는 간단한 에이전트 메시지 핸들러의 구현 예제입니다.

에이전트 메시지 정의 및 핸들러 구조

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

// 에이전트가 처리할 명령 타입 정의
#[derive(Debug)]
enum AgentCommand {
 ProcessTask(String),
 UpdateStatus(String),
 Shutdown,
}

// 에이전트의 상태 구조체
struct AgentState {
 id: String,
 status: String,
 processed_tasks: u64,
}

// 에이전트 실행기 구조체
struct AgentExecutor {
 state: Arc<RwLock<AgentState>>,
 receiver: mpsc::Receiver<AgentCommand>,
}

impl AgentExecutor {
 // 새로운 에이전트 생성자
 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,
 }
 }

 // 메시지 수신 및 처리 루프 시작
 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) => {
 // 비동기 작업 시뮬레이션 (예: LLM 추론 요청)
 let task_id_clone = task_id.clone();
 let state_clone = Arc::clone(&self.state);
 
 // 백그라운드 작업으로 처리하여 메시지 루프 차단 방지
 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;
 }
 }
 }
 }
}

메인 런타임 구성 및 리소스 관리

이제 위 에이전트를 생성하고 관리하는 메인 런타임 코드를 작성해보겠습니다. 여기서는 리소스 누수를 방지하기 위해 tokio::select! 매크로를 사용하여 그레이스풀 셧다운(Graceful Shutdown)을 구현합니다.

#[tokio::main]
async fn main() {
 // 여러 에이전트를 관리하기 위한 송신자(Sender) 목록 저장
 // 에이전트가 종료될 때를 대비해 Vec으로 관리
 let mut agent_senders = Vec::new();

 // 3개의 에이전트 스폰
 for i in 0..3 {
 let (tx, rx) = mpsc::channel(100); // 버퍼 크기 100
 agent_senders.push(tx);
 
 let executor = AgentExecutor::new(format!("Agent-{}", i), rx);
 tokio::spawn(executor.run());
 }

 // 시스템 전체의 종료 신항 (Ctrl+C 등 대응)
 let (shutdown_tx, mut shutdown_rx) = mpsc::channel::<()>(1);
 
 // 작업 분산 로직 (시뮬레이션)
 let task_distributor = tokio::spawn(async move {
 let mut task_counter = 0;
 loop {
 // 종료 신호 확인
 if shutdown_rx.try_recv().is_ok() {
 println!("Task distributor stopping...");
 break;
 }

 // 라운드 로빈 방식으로 에이전트들에게 작업 전송
 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;
 }
 }
 });

 // 5초 후 시스템 종료 시뮬레이션
 tokio::time::sleep(Duration::from_secs(5)).await;
 
 // 1. 작업 분배 종료
 let _ = shutdown_tx.send(()).await;
 task_distributor.await.unwrap();

 // 2. 모든 에이전트에게 종료 명령 전송
 for tx in agent_senders {
 let _ = tx.send(AgentCommand::Shutdown).await;
 }

 // 리소스 정리 대기
 tokio::time::sleep(Duration::from_millis(500)).await;
 println!("System shutdown complete.");
}

핵심 포인트 분석

Arc<RwLock<State>> 패턴: AgentExecutor는 상태를 Arc<RwLock>으로 감싸서 보관합니다. tokio::spawn으로 생성된 비동기 태스크는 이 Arc를 클론(clone)하여 가져옵니다. 이때 데이터 자체가 복사되는 것이 아니라 참조 카운터만 증가하므로 매우 가볍습니다.
MPSC 채널의 소유권 이동: tx (Sender) 끝은 메인 루프가 소유하고, rx (Receiver) 끝은 AgentExecutor가 소유합니다. 이렇게 명확하게 소유권을 분리함으로써, 누가 메시지를 보내고 받는지 컴파일 타임에 보장할 수 있습니다.
비동기 I/O와 락의 조화: state.write().await를 사용할 때, 해당 코드는 데이터를 쓰기 위해 잠금(Lock)을 획득할 때까지 현재 태스크를 일시 중단(Yield)합니다. 이는 OS 스레드가 블로킹되는 것과 다르며, 다른 태스크가 CPU를 사용할 수 있게 하여 멀티코어 활용도를 높입니다.

결론

Rust의 메모리 관리 메커니즘은 단순한 안전성을 넘어, 고성능 서버 아키텍처 설계의 강력한 도구가 됩니다. ZeroClaw 프로젝트에서는 이를 통해 에이전트 간의 통신 오버헤드를 최소화하고, 예측 가능한 지연 시간(Latency)을 확보할 수 있었습니다. 특히 tokio 런타임과 결합된 채널 기반 아키텍처는 수천 개의 에이전트가 상호작용하는 복잡한 시스템에서도 안정성을 유지하는 기반이 되고 있습니다.

다음 포스트에서는 이러한 에이전트 간 통신을 확장하여, 파일 기반의 영속성(Persistence)을 구현하는 아키텍처에 대해 다루겠습니다.

참고 링크

NATS JetStream으로 멀티-LLM 분산 오케스트레이터 구축하기

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

1편에서는 Claude, ZAI, Codex, Gemini 네 가지 AI를 같은 태스크에 동시에 돌리면서 발견한 모델별 제한 사항을 다뤘다. 이번 편은 “어떻게 그게 가능하도록 만들었나”—시스템 설계와 구현 이야기다.

시스템 개요

AgentForge는 세 가지 요소로 이루어진다.

[태스크 발행자]
 │ NATS JetStream publish
 ▼
[NATS 브로커] ─── af.worker.{id}.inbox
 │ JetStream consume (워커별 독립 스트림)
 ▼
[워커 폴러] × N (poller.py × 18개)
 │ LLM CLI 실행 (claude / codex / gemini)
 ▼
[결과 반환] af.task.{task_id}.completed

발행자가 NATS에 태스크를 올리면, 각 워커가 독립적으로 구독하고 있다가 자신의 inbox로 들어온 메시지를 받아 LLM CLI를 실행한다. 결과는 완료 주제로 다시 publish된다.

왜 NATS JetStream인가

메시지 브로커 선택지는 여러 개였다: Redis Streams, Kafka, RabbitMQ, NATS JetStream.

NATS JetStream을 선택한 이유:

단일 바이너리 — 별도의 런타임 없이 nats-server 하나로 동작한다. Kafka의 ZooKeeper나 RabbitMQ의 Erlang/OTP 의존성이 없다.
내장 영속성 — JetStream은 NATS 위에 올라가는 스트리밍 레이어로, 메시지를 파일시스템에 저장한다. 워커가 재시작되어도 처리 안 된 태스크가 유실되지 않는다.
NKey 기반 인증 — 워커별로 독립된 Ed25519 keypair를 발급할 수 있다. 한 워커가 침해되어도 다른 워커의 자격증명은 유효하다.
경량 — 단일 서버에서 메모리 사용량 ~30MB. 18개 워커를 연결해도 브로커 부하가 거의 없다.

핵심: poller.py의 백엔드 어댑터

워커의 핵심은 poller.py다. 이 파일 하나가 NATS 구독, LLM CLI 실행, 결과 반환을 모두 담당한다.

LLM별 실행 방식이 다르기 때문에, 백엔드 어댑터 딕셔너리로 분리했다.

_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", ""),
 },
}

MODEL_BACKEND 환경변수로 어떤 LLM을 쓸지 결정한다. 덕분에 동일한 poller.py 코드로 18개 워커가 각자 다른 LLM을 실행한다.

Claude 백엔드

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)

--print 플래그가 핵심이다. Claude Code가 대화 모드가 아닌 비대화형 모드로 실행되어 stdout으로 결과를 반환하게 만든다.

ZAI 백엔드

ZAI는 Anthropic API 호환 엔드포인트를 제공하기 때문에 별도 백엔드가 없다. 환경변수 두 개로 라우팅을 바꾼다.

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

systemd EnvironmentFile= 지시어로 이 파일을 주입하면, claude 바이너리가 ZAI 엔드포인트로 요청을 보낸다. 코드 변경 없이 환경변수만으로 다른 LLM 공급자를 연결하는 셈이다.

선언적 관리: fleet.yaml × servers.yaml

18개 워커를 수동으로 관리하는 건 비현실적이다. 두 개의 YAML 파일로 전체 인프라를 선언적으로 정의했다.

servers.yaml — 서버 인벤토리

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 — 워커 배치

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

host 필드 하나를 바꾸면 워커가 다른 서버로 이동한다. enabled: false로 설정하면 배포 스크립트가 해당 워커를 중지한다.

워커 템플릿 시스템: provision_worker.py

워커를 새로 추가할 때마다 systemd 유닛 파일을 직접 작성하는 건 오류가 생기기 쉽다. Jinja2 템플릿 + 프로비저닝 스크립트로 자동화했다.

템플릿 구조

templates/
 systemd/
 claude.service.j2 # claude-code, ZAI 공용
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

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 %}

ZAI 워커는 env_file 블록이 활성화되어 EnvironmentFile이 추가된다. PR 생성 워커는 github_remote가 주입된다. 나머지는 기본값을 쓴다.

provision_worker.py 사용법

# 미리보기 (실제 배포 없음)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# 실제 배포 (NATS creds 발급 포함)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# fleet.yaml 전체 일괄 배포
python3 scripts/provision_worker.py --all

내부적으로 수행하는 작업:

fleet.yaml에서 워커 항목 읽기
servers.yaml에서 대상 호스트 읽기
Jinja2 템플릿 렌더링
SSH로 /etc/systemd/system/{worker_id}-poller.service 배포
워크 디렉터리 생성
systemctl daemon-reload && enable --now
(선택) nsc add user로 NATS NKey 발급 → creds 배포 → auth.conf 재생성

분산 호스트: 두 번째 서버에 워커 추가

모든 워커를 한 서버에서 돌리면 단일 장애점이 된다. 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커에 연결하는 방법은 autossh 터널이다.

[Unit]
Description=NATS 브로커 터널
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

이 설정이 활성화된 상태에서 워커는 항상 nats://127.0.0.1:4222로 연결한다. 브로커 호스트 주소를 몰라도 된다. 터널만 살아있으면 어느 호스트에서든 동일하게 동작한다.

NATS 자격증명 운영 경험

구현 중 가장 복잡했던 부분은 NATS NKey 관리다.

NATS JetStream의 인증 구조는 계층적이다.

Operator (최상위 서명 기관)
 └── Account: SYS (시스템 계정)
 └── Account: Services (워커 계정)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

각 워커는 독립된 User NKey를 가지고, Services 계정의 권한 범위(af.>, _INBOX.>, $JS.>) 내에서만 publish/subscribe할 수 있다.

신규 워커를 추가할 때 Operator의 signing key가 필요하다. 초기에 이 키의 백업을 만들지 않았다가 분실하는 사고가 있었다. 결과적으로 Operator를 전부 재생성하고 모든 워커의 creds를 일괄 교체했다. 서비스 다운타임은 약 60초.

# 재생성 절차
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

새 워커 추가: 전체 절차

이 시스템이 완성된 이후 새 워커를 추가하는 절차는 단순하다.

1단계: 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

2단계: 미리보기

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

3단계: 실제 배포

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

끝이다. 템플릿 렌더링, SSH 배포, NATS 자격증명 발급, 서비스 등록까지 한 명령으로 처리된다.

다음 단계

현재 시스템은 워커가 태스크를 독립적으로 처리하는 구조다. 앞으로 만들고 싶은 것:

라우팅 정책: 태스크 특성에 따라 적합한 워커를 자동 선택 (Go 코드 → claude-go-dev, 비용 최우선 → ZAI 경량 티어)
결과 비교 대시보드: fan-out 결과를 나란히 보여주는 UI
비용 추적: 워커별 API 호출 비용 집계

코드는 GitHub에 공개되어 있다.

에이전트 개발의 다음 단계: 제어 흐름(Control Flow) 도입하기

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

에이전트 개발의 다음 단계: 제어 흐름(Control Flow) 도입하기

최근 ‘Agents need control flow, not more prompts’라는 글을 보며 깊이 공감했습니다. 초기 LLM 기반 에이전트를 개발할 때는 프롬프트 엔지니어링이 곧 개발의 전부인 것처럼 느껴졌습니다. 하지만 시스템이 복잡해지고 ZeroClaw와 같은 멀티 에이전트 런타임을 다루게 되면서, ‘프롬프트’가 아닌 ‘구조’가 핵심임을 절실히 깨닫게 되었습니다.

이번 글에서는 복잡한 프롬프트를 덜어내고, 확장 가능한 에이전트 시스템을 위해 **제어 흐름(Control Flow)**을 아키텍처에 도입하는 방법을 실제 코드 예제와 함께 정리해 보겠습니다.

문제 정의: 프롬프트 한계와 ‘의존성 지옥’

단일 에이전트에게 “A 작업을 하고, 결과가 양수면 B를, 음수면 C를 실행한 뒤, 마지막으로 D를 요약해"라고 프롬프트로 지시하는 것은 쉽지 않습니다. LLM은 문맥을 잃어버리거나, 논리적 분기(if/else)를 무시하고 직행해버리는 경우가 빈번하기 때문입니다.

특히 [ZeroClaw] 멀티 에이전트 아키텍처 설계안에서 논의된 것처럼, 여러 에이전트가 협력하는 환경에서는 프롬프트만으로는 다음과 같은 문제가 발생합니다.

비결정성(Non-determinism): 같은 입력이라도 LLM이 다른 경로를 선택할 수 있습니다.
디버깅 난이도: 에러가 발생했을 때 프롬프트의 어느 부분이 잘못된 지 찾기 어렵습니다.
확장성 부족: 새로운 단계를 추가할 때마다 기존의 거대한 프롬프트를 수정해야 합니다.

해결책: 그래프 기반 제어 흐름 (Graph-based Control Flow)

해결책은 LLM에게 “무엇(What)“을 할지 결정하게 하고, “어떻게(How)” 실행할지는 외부의 상태 머신(State Machine)이나 그래프 워크플로우에 위임하는 것입니다. 이를 통해 우리는 에이전트의 사고 자체를 제어하는 것이 아니라, 에이전트 간의 데이터 흐름과 실행 순서를 제어하게 됩니다.

Rust와 같은 안정적인 언어로 이러한 런타임을 구성하면 [ZeroClaw]에서 목표로 하는 고성능 및 안정성을 확보할 수 있습니다.

구현 예제: Rust로 간단한 상태 머신 러너 만들기

복잡한 프레임워크 없이, Rust의 Enum을 활용해 간단한 에이전트 워크플로우를 구현해 보겠습니다. 이 코드는 에이전트가 수행해야 할 단계(Step)를 정의하고, 이전 단계의 결과에 따라 다음 단계를 결정하는 구조입니다.

// 1. 에이전트의 상태와 실행 컨텍스트 정의
#[derive(Debug, Clone)]
struct AgentContext {
 current_data: String,
 step_count: usize,
}

// 2. 워크플로우의 각 단계(Step) 정의
enum WorkflowStep {
 Initialize,
 ProcessData,
 ValidateResult, // 결과에 따라 다음 단계가 결정됨
 Finalize,
 Complete,
}

// 3. 각 단계별 실행 로직 구제화
impl WorkflowStep {
 fn execute(&self, ctx: &mut AgentContext) -> WorkflowStep {
 match self {
 WorkflowStep::Initialize => {
 println!("[Step 1] 데이터 초기화 중...");
 ctx.current_data = "Sample Input Data".to_string();
 ctx.step_count += 1;
 WorkflowStep::ProcessData
 },
 WorkflowStep::ProcessData => {
 println!("[Step 2] LLM을 통해 데이터 처리 중: {}", ctx.current_data);
 // 실제로는 여기서 MCP 클라이언트 등을 호출하여 LLM 추론을 수행
 ctx.current_data = format!("Processed: {}", ctx.current_data);
 ctx.step_count += 1;
 WorkflowStep::ValidateResult
 },
 WorkflowStep::ValidateResult => {
 println!("[Step 3] 결과 검증 중...");
 // 비즈니스 로직: 예를 들어 결과 길이가 10보다 작으면 재시작(혹은 에러 처리)
 if ctx.current_data.len() < 10 {
 println!("데이터가 부족하여 초기화 단계로 돌아갑니다.");
 WorkflowStep::Initialize // 루프 구조
 } else {
 println!("검증 통과. 완료 단계로 이동합니다.");
 WorkflowStep::Finalize
 }
 },
 WorkflowStep::Finalize => {
 println!("[Step 4] 최종 결과 저장: {}", ctx.current_data);
 WorkflowStep::Complete
 },
 WorkflowStep::Complete => {
 println!("워크플로우 완료.");
 WorkflowStep::Complete // 종료 상태 유지
 }
 }
 }
}

// 4. 메인 실행 루프 (Runner)
fn run_agent_workflow() {
 let mut ctx = AgentContext {
 current_data: String::new(),
 step_count: 0,
 };
 
 let mut current_step = WorkflowStep::Initialize;
 
 // 최대 10회 반복 방지 (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();
}

코드를 통한 얻는 이점

위의 예제처럼 단순히 match 문과 Enum을 사용하더라도 얻을 수 있는 효과는 큽니다.

명확한 흐름 시각화: 코드만 보고도 시스템이 어떻게 흘러가는지 파악할 수 있습니다. [Discord MCP Gateway 아키텍처]처럼 복잡한 요청을 처리할 때 유지보수성이 크게 향상됩니다.
상태 관리: AgentContext 구조체를 통해 메모리 상태를 명시적으로 관리합니다. LLM의 컨텍스트 윈도우가 터지더라도 Rust 런타임은 현재 단계를 정확히 알고 있습니다.
에러 핸들링: 특정 단계에서 실패했을 때, 프롬프트 재시도가 아니라 코드 레벨에서 Retry 로직이나 Fallback 단계로 쉽게 넘어갈 수 있습니다.

결론: 에이전트는 소프트웨어다

우리는 LLM을 ‘마법’처럼 다루는 시대를 지나, LLM을 ‘하나의 모듈’로 바라보는 시대로 넘어가고 있습니다. [Cloud Monitor]나 [LLM 설정 개선] 프로젝트에서 겪었던 시행착오들은 결국 견고한 소프트웨어 아키텍처 위에 AI를 얹어야 한다는 것을 보여줍니다.

프롬프트를 더 길게 작성하는 대신, Rust나 Python으로 제어 흐름을 명확히 정의하는 런타임을 구축해 보세요. 에이전트의 행동이 예측 가능해지고, 시스템이 튼튼해지는 것을 느끼실 수 있을 것입니다.

다음 포스트에서는 이러한 제어 흐름 위에서 실제로 여러 LLM 호출을 병렬로 처리하여 성능을 극대화하는 방법에 대해 다루어보겠습니다.

Redis Array의 진화: 대규모 데이터 처리를 위한 아키텍처 분석

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

Redis Array의 진화: 대규모 데이터 처리를 위한 아키텍처 분석

안녕하세요! 최근 Hacker News를 통해 흥미로운 기사 하나를 접하게 되었습니다. 바로 Redis의 핵심 개발자 중 한 명인 Oran Agra가 작성한 **“Redis array: short story of a long development process”**입니다. 단순히 기능 하나가 추가된 이야기가 아니었습니다. 이는 25년 된 레거시 코드를 건드리면서 성능을 유지하고, 안정성을 확보하며, 거대한 코드베이스를 밤새 포맷팅했던 개발자들의 집념의 기록이었습니다.

오늘은 이 기사를 바탕으로, Redis 내부에서 Array(배열) 자료구조가 어떻게 진화해왔는지, 그리고 우리가 대규모 시스템을 설계할 때 배울 수 있는 교훈은 무엇인지 깊이 있게 분석해보겠습니다.

1. 문제 제기: 25년 된 레거시 코드의 굴레

Redis의 LIST 자료구조는 내부적으로 QuickList를 사용합니다. QuickList는 양방향 연결 리스트인 ziplist와 linkedlist의 장점을 결합한 구조입니다. 하지만 수천만 개의 요소를 가진 거대한 리스트를 다룰 때, 메모리 파편화(memory fragmentation)와 캐시 미스(cache miss)가 심각한 성능 저하를 일으키는 문제가 있었습니다.

특히, 배열(Array) 타입의 데이터를 처리할 때 기존의 구조는 다음과 같은 병목이 있었습니다.

메모리 오버헤드: 포인터 연결로 인한 추가 메모리 사용.
순차 접근 비용: 캐시 라인을 효율적으로 사용하지 못해 발생하는 지연.

개발팀은 이를 해결하기 위해 C 언어 수준에서 내부 구조를 뜯어고치기로 결심합니다. 여기서 가장 큰 난관은 바로 **“변경하지 않으면 안 되는 레거시 코드”**였습니다.

2. 해결 과정: Formatting a 25M-line Codebase

기사에서 가장 인상 깊었던 부분은 **“Formatting a 25M-line codebase overnight”**입니다. 2,500만 라인에 달하는 코드를 포맷팅하고 리팩토링하는 과정은 단순한 기술적 도전을 넘어 체스와 같은 전략이 필요했습니다.

2.1. 리팩토링을 위한 사전 준비

대규모 리팩토링 시 가장 두려운 것은 **“회귀(Regression)”**입니다. 배열 구조를 변경하는 과정에서 수백 개의 Redis 명령어(LPUSH, RPUSH, LINDEX 등)가 영향을 받을 수 있기 때문입니다.

이를 해결하기 위해 팀은 다음과 같은 접근 방식을 취했습니다.

테스트 커버리지 확대: 기존 명령어에 대한 단위 테스트(Unit Test)를 통과하는지 확인.
CI/CD 파이프라인 강화: 코드 변경 시 즉시 성능 저하가 발생하는지 감시하는 벤치마킹 스크립트 배치.

2.2. Redis Array의 새로운 구조

개선된 Array 구조는 단순히 메모리를 할당하는 방식에서 벗어나, 데이터 지역성(Locality)을 극대화하는 방향으로 변경되었습니다. 핵심은 **“연속된 메모리 블록을 최대한 활용하되, 필요시 분할하여 관리한다”**는 것입니다.

이를 통해 다음과 같은 이점을 얻었습니다.

CPU 캐시 히트율 향상: 연속된 메모리 접근으로 인해 L1/L2 캐시 적중률이 크게 향상되었습니다.
메모리 절약: 불필요한 포인터 연결을 줄여 실제 데이터 저장 공간을 확보했습니다.

3. 실전 가이드: Redis에서 효율적인 배열 사용하기

이론적인 배경은 충분하니, 이제 실제로 어떻게 적용할 수 있는지 코드로 살펴보겠습니다.

3.1. 기존 리스트 사용의 문제점

먼저, 수천만 개의 아이템을 리스트에 넣는 기존 방식을 생각해봅시다. 이는 QuickList 기반으로 동작하며, 아이템 수가 늘어날수록 점프 횟수가 늘어납니다.

# 기존 방식 (QuickList based)
# 10,000,000개의 아이템 추가 (메모리 및 속도 저하 발생 가능)
for i in {1..10000000}; do
 redis-cli LPUSH my_huge_list "item:$i"
done

3.2. Stream과 Hash를 활용한 최적화

Redis Array의 내부 개선은 사용자에게 투명하게 적용되지만, 우리가 설계를 할 때는 **“데이터의 크기”**와 **“접근 패턴”**을 고려해야 합니다. 단순히 순서대로 저장만 하면 된다면 최신 버전의 Redis를 쓰는 것만으로도 이득을 볼 수 있습니다.

하지만 만약 배열 안의 데이터를 검색하거나 수정해야 한다면 LIST 대신 HASH를 사용하는 것이 좋습니다.

import redis
import time

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

# 시나리오: 로그 데이터 저장 (대규모)
# 1. List 사용 (순차 보관용)
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. Hash 사용 (검색 및 수정용)
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__":
 # 10만 개 데이터 삽입 테스트
 push_to_list(100000)
 push_to_hash(100000)

실행 결과 분석: 최신 Redis 버전(7.x 이상)에서는 내부적으로 Array 구조가 최적화되어 있어 LPUSH 속도가 매우 빠릅니다. 하지만 특정 인덱스의 데이터를 자주 조회해야 한다면 LINDEX는 O(N)의 복잡도를 가지므로, HGET을 쓰는 O(1) 방식이 훨씬 유리합니다.

4. 결론: 개발 문화와 기술의 조화

Redis Array의 개발 과정은 우리에게 중요한 교훈을 줍니다.

성능은 무료가 아니다: 25년 된 코드를 개선하기 위해서는 그에 상응하는 리팩토링과 테스트 비용이 따른다.
도구의 투자: 2,500만 라인의 코드를 포맷팅할 수 있는 자동화 도구와 CI/CD 환경이 있었기에 가능한 작업이었다.

우리가 시스템을 설계할 때, 단순히 “빠르다"는 것만 넘어서 “어떻게 유지보수 가능한 성능을 낼 것인가"를 고민해야 합니다. Redis 팀이 보여준 것처럼, 때로는 아키텍처의 근간을 흔드는 대규모 개선을 두려워하지 말아야 할 때입니다.

5. 참고 자료

감사합니다!

[AgentForge] 블로그 자동화 서비스 전체 아키텍처 — AI 댓글, 번역, 포스트 생성까지

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

블로그를 운영하면서 가장 번거로운 작업 세 가지가 있습니다. 댓글에 답하기, 영문 번역 유지하기, 그리고 꾸준히 글 쓰기. AgentForge 프로젝트에서는 이 세 가지를 모두 AI 에이전트로 자동화했습니다.

이 글에서는 2개 서버에 걸쳐 동작하는 블로그 자동화 서비스의 전체 아키텍처를 정리합니다.

시스템 토폴로지

┌─────────────────────┐ HTTPS ┌─────────────────────┐
│ arm1 서버 │ ──────────────▶ │ ec1 서버 │
│ (에이전트 오퍼레이터) │ │ (블로그 호스팅) │
├─────────────────────┤ ├─────────────────────┤
│ 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) │
└─────────────────────┘ └─────────────────────┘

서버	역할	핵심 서비스
arm1	에이전트 오퍼레이터	`blog-agent.service` — Flask + Scheduler + LLM Client
ec1	블로그 호스팅 + API	Hugo (nginx) + `blog-api.service` (FastAPI)

두 서버 간 통신은 HTTPS API 호출만 가능합니다. arm1에서 ec1로의 SSH 접속은 차단되어 있어, 모든 연동은 Blog API를 통해 이루어집니다.

arm1: 통합 블로그 에이전트

왜 통합했는가

초기에는 댓글 응답, 번역, 포스트 생성이 각각 독립 프로세스(3개 systemd 서비스)로 운영되었습니다. 문제는:

Claude Code CLI(--print) 호출 방식으로 응답 시간 9.7초, 디스크 688MB 소모
systemd 유닛 6개 관리 부담
프로세스 간 상태 공유 불가

이를 1개 프로세스로 통합하면서 직접 LLM API 호출로 전환했습니다. 결과:

지표	Before	After
응답 시간	9.7초	1.7초
디스크 사용	688MB	~50MB
systemd 유닛	6개	1개
프로세스	3개	1개

아키텍처

class BlogAgent:
 """1 프로세스 = 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
 
 # 핸들러
 self.comment = CommentHandler(self.llm, self.config)
 self.translate = TranslateHandler(self.api)
 self.post_gen = PostGenerator(self.llm, self.api)
 
 # 스케줄러
 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)

모듈별 동작

1. CommentHandler — AI 댓글 응답

GitHub Discussions의 Webhook 이벤트를 수신하여 자동으로 AI 댓글을 생성합니다.

[사용자 댓글] → GitHub Webhook → arm1 Flask → CommentHandler
 → LLM 호출 (ZAI glm-4.7) → 답변 생성 → GitHub API로 댓글 게시

트리거: Webhook 이벤트 기반 (실시간)
필터링: 블로그 소유자 댓글, AI 생성 댓글은 건너뜀
보안: HMAC-SHA256 Webhook 시크릿 검증, Flask-Limiter 적용

2. TranslateHandler — 자동 번역 트리거

6시간마다 ec1의 Blog API에 번역 동기화를 요청합니다.

[Scheduler 6h] → TranslateHandler.check_and_sync()
 → POST /translate/sync → ec1 Blog API가 실제 번역 수행

arm1은 번역을 직접 수행하지 않고, ec1 API에 트리거만 보냅니다. 실제 번역 로직은 ec1의 translator.py에 있습니다.

3. PostGenerator — 자동 포스트 생성

매일 오전 9시에 기술 블로그 포스트를 자동 생성합니다.

[Scheduler 09:00 KST] → PostGenerator.generate_and_publish()
 → 기존 주제 수집 → RSS 트렌드 참조 → LLM으로 콘텐츠 생성
 → 중복 검사 → Blog API로 게시

중복 방지가 핵심입니다. difflib.SequenceMatcher로 새 제목과 최근 100개 기존 제목의 유사도를 비교합니다:

def _is_duplicate_title(self, new_title, existing_titles):
 """threshold 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 번역 시스템

Gemini로의 전환

초기에는 ZAI(glm-4.7)로 번역을 수행했으나, 치명적인 문제가 발생했습니다:

glm-4.7은 reasoning 모델로, max_tokens 예산을 reasoning_content(내부 사고 과정)에 먼저 소진합니다. max_tokens=256이면 reasoning에 256토큰을 모두 쓰고, 실제 content는 빈 문자열이 됩니다.

이로 인해 9개 영문 게시글의 제목이 빈 문자열로 번역되는 사고가 발생했습니다.

해결책: Gemini 2.5 Flash Lite로 교체.

항목	ZAI (이전)	Gemini (현재)
모델	glm-4.7 (reasoning)	gemini-2.5-flash-lite
번역 시간	~30초/포스트	~8초/포스트
비용	API 유료	무료 (1,500건/일)
빈 응답 문제	발생	없음

OpenAI-Compatible 엔드포인트

Gemini는 OpenAI 호환 API를 제공합니다. 기존 코드를 한 줄도 바꾸지 않고 base URL만 교체하면 됩니다:

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

번역 매칭 로직

한국어↔영어 게시글 페어링은 날짜 접두사 매칭을 사용합니다:

ko: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
en: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
 ↑ 같은 접두사 = 같은 게시글

slug의 언어가 다를 수 있지만, YYYY-MM-DD-NNN 부분이 같으면 같은 게시글로 인식합니다. 이 방식의 전제 조건은 같은 날짜에 같은 번호가 2개 이상 존재하면 안 된다는 것입니다.

Title-in-Body 번역 기법

제목을 별도 API 호출로 번역하면 reasoning 모델에서 빈 결과가 나오는 문제가 있었습니다. 해결책은 제목을 본문 첫 줄에 포함시키는 것:

# 번역 요청 시
prompt = f"# {original_title}\n\n{original_body}"

# 번역 결과에서 제목 추출
if translated.lstrip().startswith("# "):
 lines = translated.lstrip().split("\n", 1)
 extracted_title = lines[0].lstrip("# ").strip()
 translated_body = lines[1].lstrip("\n")

하나의 API 호출로 제목과 본문을 동시에 번역하므로, 맥락이 보존되고 토큰도 절약됩니다.

LLM 전략: 역할별 모델 분리

하나의 LLM으로 모든 작업을 처리하지 않습니다. 작업 성격에 맞춰 모델을 분리했습니다.

작업	서버	모델	이유
댓글 AI 응답	arm1	ZAI glm-4.7	대화형, 한국어 품질 우수
포스트 생성	arm1	ZAI glm-4.7	긴 글 생성, 창의성 필요
번역 (ko→en)	ec1	Gemini Flash Lite	비추론형, 빠르고 무료

핵심 원칙: reasoning 모델은 번역에 쓰지 않는다. reasoning 모델은 내부 사고에 토큰을 소비하므로, 단순 변환 작업에는 비추론형 모델이 적합합니다.

모니터링과 운영

헬스체크 엔드포인트

# arm1 에이전트
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"}

관찰 포인트

지표	정상 범위	알림 조건
arm1 uptime	>0	서비스 다운
scheduler_jobs	2	≠ 2
번역 동기화	ko=en 개수 일치	차이 발생
포스트 생성	매일 1건	24시간 이상 미생성

교훈과 운영 팁

1. Reasoning 모델의 함정

max_tokens가 reasoning과 content를 합산한다는 것을 문서에서 명시하지 않는 경우가 많습니다. 빈 응답이 나오면 finish_reason을 확인하세요 — "length"라면 토큰 예산 부족입니다.

2. OpenAI-Compatible 패턴의 가치

번역 제공자를 ZAI에서 Gemini로 바꿀 때 코드 변경이 base URL 1줄이었습니다. 처음부터 OpenAI-compatible 인터페이스로 추상화하면 LLM 교체 비용이 극적으로 줄어듭니다.

3. 날짜 접두사 매칭의 제약

YYYY-MM-DD-NNN 패턴에서 같은 날짜에 같은 번호가 2개 이상 존재하면 번역 매칭이 깨집니다. PostGenerator에서 새 게시글 생성 시 해당 날짜의 마지막 번호 + 1을 확인하는 로직이 필수입니다.

4. 통합 프로세스의 이점

3개 독립 서비스를 1개로 통합하면서 얻은 것:

상태 공유 (LLM 클라이언트, 설정, API 클라이언트를 한 번만 초기화)
배포 단순화 (systemd 유닛 1개)
디버깅 용이 (로그가 한 곳에 모임)

향후 계획

arm1 에이전트의 LLM도 Gemini로 통합 검토
댓글 품질 평가 파이프라인 (자동 생성 댓글의 적절성 모니터링)
번역 품질 자동 검증 (역번역 비교)
AgentForge 프레임워크를 통한 에이전트 간 협업 확대

블로그 자동화는 “완전 자동"이 아니라 “최소 개입"을 목표로 합니다. AI가 생성한 콘텐츠를 사람이 검토하고, 시스템이 이상 징후를 감지하면 운영자에게 알리는 구조가 안정적인 운영의 핵심입니다.

[Discord Decision MCP] 아키텍처 설계문서

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

Discord Decision MCP — 아키텍처 설계문서

1. 프로젝트 개요

1.1 목적

Claude Code가 tmux Teammate 모드로 자율 작업 중, 사용자 결정이 필요한 시점에 Discord를 통해 질문하고 응답을 받아 작업을 재개하는 MCP (Model Context Protocol) 서버입니다.

1.2 핵심 특징

특징	설명
프로젝트당 Bot 1개	각 프로젝트는 독립된 Discord Bot 사용
무한 대기 기본값	Timeout 없이 사용자 응답 대기 (Claude가 독단 진행 금지)
상태 영속화	프로세스 재시작 후에도 대기 상태 복원
한국어 친화적	한글 선택지, Yes/No 응답 지원
MCP 기반 통신	모든 Discord 통신은 MCP Tool을 통해 이루어짐

1.3 버전 정보

버전: 1.0.0
Python 요구사항: >= 3.11
MCP 프레임워크: FastMCP >= 0.1.0

2. 디렉토리 구조

discord-decision/
├── discord_mcp/ # 메인 패키지
│ ├── __init__.py
│ ├── server.py # MCP 서버 진입점
│ ├── config.py # 환경변수 설정 관리
│ │
│ ├── bot/ # Discord API 클라이언트
│ │ ├── __init__.py
│ │ ├── client.py # REST API 클라이언트 (httpx)
│ │ └── gateway.py # WebSocket 게이트웨이 (수신 전용)
│ │
│ ├── decision/ # 결정 요청 관리
│ │ ├── __init__.py
│ │ ├── manager.py # 결정 요청 생명주기 관리
│ │ ├── poller.py # Discord Polling 및 응답 대기
│ │ ├── parser.py # 사용자 응답 파싱
│ │ └── state.py # 상태 영속화 (JSON 파일)
│ │
│ ├── tools/ # MCP Tools 구현
│ │ ├── __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 메시지 템플릿
│ │
│ └── daemon/ # 감시 데몬
│ ├── __init__.py
│ ├── watcher.py # Discord 채널 감시 (discord-watch CLI)
│ └── inbox.py # Inbox 파일 관리
│
├── scripts/ # 유틸리티 스크립트
│ └── start-discord-watch.sh
│
├── tests/ # 테스트 스위트
│ ├── __init__.py
│ ├── test_parser.py
│ └── test_state.py
│
├── CLAUDE.md # Claude Code 프로젝트 지침
├── README.md # 프로젝트 설명
├── pyproject.toml # 프로젝트 설정 및 의존성
└── mcp.json.example # MCP 설정 예시

3. 주요 모듈 설명

3.1 서버 진입점 (`server.py`)

역할: FastMCP 서버 생성 및 MCP Tool 등록

mcp = FastMCP(name="discord-decision-mcp")
# Tool 등록
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)

실행 방법:

discord-mcp # 또는 python -m discord_mcp.server

3.2 설정 관리 (`config.py`)

역할: 환경변수에서 설정값 로드

환경변수	설명	기본값
`DISCORD_BOT_TOKEN`	Discord Bot Token (“Bot " 접두사 포함)	필수
`DISCORD_CHANNEL_ID`	기본 질문 채널 ID	필수
`PROJECT_NAME`	question_id 생성에 사용	“project”
`PENDING_DIR`	상태 파일 저장 경로	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling 간격 (초)	5

3.3 Discord API 클라이언트 (`bot/`)

3.3.1 REST API 클라이언트 (`client.py`)

역할: Discord REST API 호출 (httpx 기반)

주요 메서드:

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)

특징:

Rate limit 자동 처리 (429 응답 시 재시도)
싱글턴 패턴 (get_client())

3.3.2 WebSocket 게이트웨이 (`gateway.py`)

역할: Discord Gateway WebSocket 연결 (수신 전용)

특징:

MESSAGE_CREATE 이벤트 실시간 수신
Polling 방식의 지연을 5초 → 즉시로 단축
Gateway 없이도 시스템 정상 동작 (Polling fallback)
자동 재연결 (Exponential backoff)

class GatewayClient:
 async def run() # 이벤트 수신 시작
 async def stop() # 연결 종료

3.4 결정 요청 관리 (`decision/`)

3.4.1 DecisionManager (`manager.py`)

역할: 결정 요청의 전체 생명주기 조율

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

흐름:

중복 질문 확인
Thread 생성 (또는 기존 Thread 재사용)
상태 파일 생성 (~/.claude/pending_decisions/{question_id}.json)
Poller 실행하여 응답 대기
SIGHUP 시그널 핸들러로 disconnected 상태 표시

3.4.2 DecisionPoller (`poller.py`)

역할: Discord 채널을 polling하여 응답 대기

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

특징:

기본값: 무한 대기 (timeout_seconds=None)
tmux pane에 실시간 대기 상태 표시 (ANSI escape)
모호한 응답 시 최대 2회 재질문

3.4.3 응답 파서 (`parser.py`)

역할: 사용자 Discord 응답 파싱

지원 패턴:

선택지 매칭: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
긍정/부정: “yes”, “네”, “예”, “no”, “아니요”
자연어: 15자 이상 또는 한글 3자 이상

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str # 재질문 메시지 생성

3.4.4 상태 저장소 (`state.py`)

역할: 결정 요청 상태를 JSON 파일로 영속화

상태 파일 위치: ~/.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	블로킹	설명
`discord_ask_decision`	✅	사용자 결정 요청
`discord_notify`	❌	진행 상황 알림
`discord_report_progress`	❌	작업 완료 리포트
`discord_check_pending`	❌	미해결 질문 확인
`discord_read_inbox`	❌	Inbox 메시지 조회
`discord_clear_inbox`	❌	Inbox 메시지 삭제

3.6 감시 데몬 (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

역할: Discord 채널을 감시하여 새 메시지를 inbox 파일에 기록

실행 방법:

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

특징:

지정된 채널(들)을 주기적으로 polling
새로운 사용자 메시지 감지 시 inbox에 기록
tmux pane에 상태 표시

3.6.2 InboxStore (`inbox.py`)

역할: Discord 메시지를 저장하는 JSON 파일 기반 저장소

Inbox 파일 위치: ~/.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() # 읽은 메시지 삭제

4. 데이터 흐름도

4.1 결정 요청 흐름

┌─────────────────┐
│ Claude Code │
└────────┬────────┘
 │ discord_ask_decision()
 ▼
┌─────────────────────────────────────┐
│ MCP Server (server.py) │
│ ┌───────────────────────────────┐ │
│ │ DecisionManager.ask() │ │
│ │ 1. 중복 확인 │ │
│ │ 2. Thread 생성 │ │
│ │ 3. 상태 파일 저장 │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 ▼
┌─────────────────────────────────────┐
│ DecisionPoller.wait() │
│ ┌───────────────────────────────┐ │
│ │ Polling 루프 │ │
│ │ 1. tmux 상태 업데이트 │ │
│ │ 2. Discord API 호출 │ │
│ │ 3. 응답 파싱 │ │
│ │ 4. 모호하면 재질문 │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 │
 ┌─────────┴─────────┐
 ▼ ▼
┌───────────────────┐ ┌──────────────────┐
│ Discord REST API │ │ Discord Thread │
│ (client.py) │ │ │
└───────────────────┘ └────────┬─────────┘
 │
 ┌────────▼────────┐
 │ 사용자 응답 │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ parser.py │
 │ - 선택지 매칭 │
 │ - 모호성 감지 │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ store.resolve()│
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ PollResult │
 │ 반환 │
 └─────────────────┘

4.2 감시 데몬 흐름

┌─────────────────────────────────────────────┐
│ DiscordWatcher (daemon/watcher.py) │
│ ┌───────────────────────────────────────┐ │
│ │ 1. 초기 메시지 ID 설정 │ │
│ │ 2. 주기적 Polling (기본 10초) │ │
│ │ 3. 새 메시지 감지 │ │
│ │ 4. InboxStore.add_message() │ │
│ └───────────────────┬───────────────────┘ │
└──────────────────────┼──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ ~/.claude/discord_inbox.json │
│ { │
│ "last_message_id": "...", │
│ "messages": [ │
│ { "message_id": "...", ... } │
│ ] │
│ } │
└──────────────────────┬──────────────────────┘
 ▲
 │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────┘

4.3 세션 복원 흐름

┌─────────────────────────────────────────────┐
│ Claude Code 세션 시작 │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ discord_check_pending() │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ DecisionManager.restore_pending() │
│ ┌───────────────────────────────────────┐ │
│ │ 1. ~/.claude/pending_decisions/*.json │ │
│ │ 2. Discord API로 Thread 확인 │ │
│ │ 3. 답변 있으면 → 자동 해결 │ │
│ │ 4. 답변 없으면 → 재시작 알림 │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

5. MCP 도구 목록

5.1 discord_ask_decision

설명: 사용자 결정이 필요할 때 Discord Thread에 질문 전송 후 응답 대기 (블로킹)

파라미터:

이름	타입	필수	설명
`question`	string	✅	질문 내용
`context`	string	✅	현재 작업 상황
`options`	string[]	❌	선택지 목록 (빈 배열이면 자유 응답)
`timeout_seconds`	float	❌	대기 Timeout (null이면 무한 대기)
`thread_id`	string	❌	기존 Thread ID (null이면 새 Thread 생성)

반환값:

{
 "success": true,
 "answer": "A) 지금 실행",
 "selected_option": "A) 지금 실행",
 "question_id": "project_20260301_abc123",
 "timed_out": false,
 "aborted": false
}

5.2 discord_notify

설명: 진행 상황을 Discord에 알림 (논블로킹)

파라미터:

이름	타입	필수	설명
`message`	string	✅	알림 메시지
`level`	string	❌	info/warning/success/error (기본값: info)
`thread_id`	string	❌	전송할 Thread ID (null이면 기본 채널)

5.3 discord_report_progress

설명: 작업 완료 또는 단계 완료 시 결과 리포트 (논블로킹)

파라미터:

이름	타입	필수	설명
`title`	string	✅	리포트 제목
`summary`	string	✅	작업 결과 요약
`details`	string[]	❌	세부 항목 목록
`thread_id`	string	❌	전송할 Thread ID

5.4 discord_check_pending

설명: 세션 시작 시 미해결 질문 확인 (논블로킹)

파라미터: 없음

반환값:

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

5.5 discord_read_inbox

설명: Inbox에 저장된 메시지 조회 (논블로킹)

파라미터:

이름	타입	기본값	설명
`unread_only`	boolean	true	읽지 않은 메시지만 반환
`mark_read`	boolean	false	조회한 메시지를 읽음으로 표시

5.6 discord_clear_inbox

설명: Inbox 메시지 삭제 (논블로킹)

파라미터:

이름	타입	기본값	설명
`read_only`	boolean	true	읽은 메시지만 삭제

6. 의존성 정보

6.1 핵심 의존성

패키지	버전	용도
`fastmcp`	>= 0.1.0	MCP 서버 프레임워크
`httpx`	>= 0.27.0	비동기 HTTP 클라이언트
`websockets`	>= 12.0	WebSocket 클라이언트
`python-dotenv`	>= 1.0.0	환경변수 로드
`pydantic`	>= 2.0.0	데이터 모델 검증
`anyio`	>= 4.0.0	비동기 실행

6.2 개발 의존성

패키지	용도
`pytest`	테스트 프레임워크
`pytest-asyncio`	비동기 테스트 지원
`pytest-mock`	Mock 지원
`respx`	httpx mocking

6.3 CLI 명령어

discord-mcp # MCP 서버 실행
discord-watch # 감시 데몬 실행

7. 상태 파일 형식

7.1 결정 상태 파일

위치: ~/.claude/pending_decisions/{question_id}.json

{
 "question_id": "project_20260301_abc123",
 "project": "my-project",
 "question": "DB 마이그레이션을 실행할까요?",
 "context": "v1→v2 스키마 변경",
 "options": ["A) 지금 실행", "B) 스테이징 먼저", "C) 보류"],
 "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 파일

위치: ~/.claude/discord_inbox.json

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

8. 아키텍처 원칙

8.1 설계 원칙

싱글톤 패턴: DiscordClient, StateStore, InboxStore는 모듈 레벨 싱글턴
상태 영속화: 모든 결정 요청 상태는 파일로 영속화
무한 대기 기본값: Claude가 독단적으로 진행하지 않도록 timeout 기본값은 None
재질문 제한: 모호한 응답은 최대 2회까지만 재질문
Rate Limit 처리: Discord API 429 응답 시 자동 대기 후 재시도

8.2 에러 handling

상황	처리 방법
Discord API 429	자동 대기 후 재시도 (최대 5회)
WebSocket 연결 끊김	Exponential backoff로 재연결
응답 파싱 실패	최대 2회 재질문 후 중단
Timeout 발생	작업 중단 알림 후 aborted 상태
세션 끊김 (SIGHUP)	disconnected 상태로 저장

문서 버전: 1.0.0 마지막 수정: 2026-03-02

영어 버전: English Version

[ZeroClaw] 2026 상반기 발전방향 회의록

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

ZeroClaw 2026 상반기 발전방향 팀 회의록

회의 일시: 2026-02-28 참석자: 아키텍트, 보안 리드, 프로덕트 오너, DevOps 리드 회의 장소: ZeroClaw 개발팀 회의실 작성자: ZeroClaw Team

1. 회의 개요

본 회의는 ZeroClaw 프로젝트의 2026년 상반기 발전방향을 논의하고, 각 영역별 로드맵과 우선순위를 수립하기 위해 개최되었다.

1.1 회의 안건

멀티 에이전트 아키텍처 발전 방향
보안 강화 및 컴플라이언스 대응
제품 경쟁력 강화 및 사용자 경험 개선
DevOps 및 인프라 고도화
종합 로드맵 및 우선순위 합의

2. 아키텍처 발전방향 논의

2.1 아키텍트 발언

“현재 ZeroClaw는 Phase 1(인프로세스 위임)을 완료하고 Phase 2(파일 기반 멀티 에이전트) 구현 중에 있습니다. 2026년 상반기에는 다음과 같은 기술적 목표를 달성해야 합니다.”

2.1.1 멀티 에이전트 오케스트레이션 고도화

제안 사항:

DAG 기반 워크플로우 실행 엔진 구현
순차/병렬/조건/반복 실행 패턴 지원
에이전트 간 작업 분배 알고리즘 개선

우선순위: 높음 (P1)

// 제안하는 워크플로우 구조
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 통신 프로토콜 개선

제안 사항:

현재 stdout 기반 통신을 구조화된 IPC로 전환
Unix Socket, gRPC, WebSocket 다중 전송 계층 지원
메시지 직렬화 최적화 (JSON → MessagePack/CBOR)

우선순위: 중간 (P2)

2.1.3 확장성 및 모듈화

제안 사항:

플러그인 아키텍처 도입 검토
Wasm 실행 모드 구현 (샌드박싱 강화)
외부 에이전트 등록 API 제공

우선순위: 낮음 (P3)

2.1.4 성능 최적화

제안 사항:

Zero-copy 메시지 전달
연결 풀링 및 캐싱 전략
비동기 I/O 최적화

우선순위: 중간 (P2)

2.2 토의 내용

보안 리드:

“IPC 프로토콜 개선 시 보안 채널 적용이 선행되어야 합니다. 에이전트 간 통신에 대한 암호화와 인증이 필요합니다.”

프로덕트 오너:

“사용자 관점에서는 에이전트 정의가 더 직관적이어야 합니다. YAML 스키마를 단순화하는 것도 고려해봅시다.”

DevOps 리드:

“성능 최적화 작업은 관찰성 향상과 병행되어야 합니다. 메트릭 수집이 먼저 확보되어야 최적화 효과를 측정할 수 있습니다.”

3. 보안 발전방향 논의

3.1 보안 리드 발언

“ZeroClaw는 이미 강력한 보안 기반을 갖추고 있으나, OWASP Top 10 관점에서 보완이 필요한 영역이 있습니다. 특히 샌드박스 격리와 감사 로깅 강화가 시급합니다.”

3.1.1 샌드박스 강화

현재 문제점:

Docker 샌드박스: --read-only, --cap-drop, seccomp 미적용
Firejail: 네트워크 격리 미적용 (--net=none 누락)

제안 사항:

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

우선순위: 높음 (P1)

3.1.2 감사 로깅 강화

제안 사항:

로그 서명 (Log Signing) 도입으로 변조 방지
실시간 보안 알림 웹훅 연동
Prometheus 메트릭 노출

우선순위: 중간 (P2)

3.1.3 SSRF 방어

제안 사항:

외부 요청 시 HTTPS 강제
사설 IP 대역 차단
도메인 허용목록 검증 강화

우선순위: 중간 (P2)

3.1.4 TOCTOU 취약점 수정

제안 사항:

경로 검증과 정규화를 원자적으로 수행
심볼릭 링크 레이스 컨디션 방지

우선순위: 높음 (P1)

3.2 토의 내용

아키텍트:

“샌드박스 강화는 Wasm 실행 모드와 연계하여 진행하면 더 강력한 격리를 제공할 수 있습니다.”

DevOps 리드:

“Prometheus 메트릭은 Grafana 대시보드와 연동하여 운영 가시성을 크게 개선할 수 있습니다.”

프로덕트 오너:

“보안 강화로 인한 사용자 경험 저하가 없도록 기본값은 안전하게, 고급 사용자는 유연하게 설정할 수 있어야 합니다.”

4. 제품 발전방향 논의

4.1 프로덕트 오너 발언

“ZeroClaw의 핵심 가치는 ‘고성능’, ‘확장성’, ‘보안’입니다. 2026년 상반기에는 이를 더욱 강화하면서 사용자 경험을 개선해야 합니다.”

4.1.1 사용자 경험 개선

CLI 개선:

zeroclaw agent list 출력 개선 (테이블 포맷)
대화형 에이전트 실행 모드
진행 상황 시각화

설정 단순화:

에이전트 정의 YAML 스키마 단순화
sensible defaults 제공
설정 검증 및 오류 메시지 개선

우선순위: 높음 (P1)

4.1.2 문서화 및 온보딩 강화

제안 사항:

Quickstart 가이드 개선
API 참조 문서 자동 생성
예제 시나리오 확장
다국어 문서 (한국어, 일본어, 중국어)

우선순위: 중간 (P2)

4.1.3 커뮤니티 성장 전략

제안 사항:

CONTRIBUTING.md 개선
Good first issue 라벨링
정기 릴리즈 노트 발행
Discord/Slack 커뮤니티 채널

우선순위: 중간 (P2)

4.1.4 차별화 포인트 강화

제안 사항:

하드웨어 페리퍼럴 지원 강화 (STM32, RPi)
특화 도메인 에이전트 템플릿
성능 벤치마크 공개

우선순위: 낮음 (P3)

4.2 토의 내용

아키텍트:

“CLI 개선은 ergonomics 측면에서 중요합니다. structopt 대신 clap 4.x로 업그레이드하는 것도 검토해봅시다.”

보안 리드:

“다국어 문서 작성 시 보안 관련 내용은 정확한 번역이 중요합니다. 용어집을 먼저 작성하는 것을 권장합니다.”

DevOps 리드:

“커뮤니티 채널은 GitHub Discussions부터 시작하는 것이 좋습니다. 별도 인프라 없이 시작할 수 있습니다.”

5. DevOps 발전방향 논의

5.1 DevOps 리드 발언

“안정적인 배포와 운영을 위해 CI/CD 파이프라인과 모니터링 시스템을 고도화해야 합니다.”

5.1.1 CI/CD 파이프라인 고도화

현재 상태:

GitHub Actions 기반 CI
cargo fmt, clippy, test 자동화
Docker 빌드

제안 사항:

cargo audit 통합 (취약점 스캔)
크로스 플랫폼 빌드 (Linux, macOS, Windows)
릴리즈 자동화 (cargo-release)
배포 전 스모크 테스트

우선순위: 높음 (P1)

# 제안하는 CI 워크플로우
- 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 모니터링 및 관찰성

제안 사항:

Prometheus 메트릭 엔드포인트
Grafana 대시보드 템플릿
분산 추적 (OpenTelemetry)
로그 집계 (ELK/Loki)

우선순위: 중간 (P2)

5.1.3 배포 자동화 및 롤백

제안 사항:

Blue-Green 배포 지원
자동 롤백 임계값 설정
Canary 릴리즈 옵션

우선순위: 중간 (P2)

5.1.4 개발 환경 개선

제안 사항:

devcontainer 구성
git hooks 자동 설정
개발용 설정 프로파일

우선순위: 낮음 (P3)

5.2 토의 내용

아키텍트:

“OpenTelemetry 통합은 멀티 에이전트 추적에 필수적입니다. 에이전트 간 호출 체인을 시각화할 수 있어야 합니다.”

보안 리드:

“cargo audit은 CI에 반드시 포함되어야 합니다. 또한 의존성 라이선스 검사도 추가하는 것이 좋습니다.”

프로덕트 오너:

“devcontainer는 신규 기여자 온보딩에 큰 도움이 될 것입니다. 우선순위를 높여도 좋습니다.”

6. 종합 로드맵 및 우선순위

6.1 2026년 상반기 로드맵

Q1 (3월-4월)

항목	담당	우선순위
Docker/Firejail 샌드박스 강화	보안	P1
TOCTOU 취약점 수정	보안	P1
CI/CD 보안 스캔 통합	DevOps	P1
CLI 개선 및 UX 향상	프로덕트	P1
DAG 기반 워크플로우 엔진	아키텍트	P1

Q2 (5월-6월)

항목	담당	우선순위
IPC 통신 프로토콜 개선	아키텍트	P2
감사 로깅 강화	보안	P2
SSRF 방어 구현	보안	P2
Prometheus 메트릭 노출	DevOps	P2
문서화 및 온보딩 개선	프로덕트	P2
커뮤니티 인프라 구축	프로덕트	P2

6.2 합의된 원칙

보안 우선: 모든 새로운 기능은 보안 리뷰를 거쳐야 함
점진적 배포: 큰 변경은 단계적으로 롤아웃
롤백 가능: 모든 변경은 쉽게 롤백 가능해야 함
문서 동기화: 기능 변경 시 문서 업데이트 필수
테스트 커버리지: 새로운 코드는 테스트 필수

6.3 리스크 및 대응

리스크	확률	영향	대응 방안
샌드박스 호환성 문제	중간	높음	폴백 메커니즘 구현
성능 회귀	낮음	중간	벤치마크 자동화
의존성 취약점	중간	높음	cargo audit 자동화
문서 부실	높음	중간	문서 PR 필수화

7. 결론 및 다음 단계

7.1 회의 결론

아키텍처: 멀티 에이전트 오케스트레이션 고도화를 최우선으로 진행
보안: 샌드박스 강화와 TOCTOU 수정을 즉시 착수
제품: CLI UX 개선으로 사용자 경험 향상
DevOps: CI/CD 보안 강화와 모니터링 기반 구축

7.2 액션 아이템

#	항목	담당자	기한
1	Docker 샌드박스 보안 프로필 적용	보안 리드	2026-03-07
2	TOCTOU 경로 검증 수정	보안 리드	2026-03-10
3	CI cargo audit 통합	DevOps 리드	2026-03-05
4	CLI agent list 개선	프로덕트 오너	2026-03-12
5	워크플로우 엔진 설계 문서	아키텍트	2026-03-15

7.3 다음 회의 일정

일시: 2026-03-14 10:00
안건: Q1 진행 상황 리뷰 및 Q2 상세 계획

부록: 참고 문서

docs/project/multi-agent-architecture-design.md - 멀티 에이전트 아키텍처 설계
docs/project/multi-agent-communication-protocols.md - 통신 프로토콜 설계
docs/security/security-improvements.md - 보안 개선 보고서
CLAUDE.md - 엔지니어링 프로토콜

회의록 작성일: 2026-02-28 승인자: ZeroClaw Team Lead 배포: ZeroClaw 개발팀 전체

영어 버전: English Version

[ZeroClaw] 멀티 에이전트 아키텍처 설계안

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

ZeroClaw 멀티 에이전트 아키텍처 설계안

개요

ZeroClaw의 멀티 에이전트 아키텍처는 단일 에이전트 모델에서 진화하는 고급 협력 시스템을 구현합니다.

현재 상태

Phase 1: In-Process Delegation (완료)
Phase 2: File-Based Multi-Agent Architecture (개발 중)

1. 설계 철학

원칙	적용
KISS	단순 통신 프로토콜
YAGNI	필수 기능만 구현
SRP	단일 책임 에이전트
Secure	최소 권한 원칙

2. 아키텍처 구조

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

3. 에이전트 정의

agent:
 id: "researcher"
 name: "Research Agent"
 
execution:
 mode: subprocess

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

4. CLI 명령어

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

5. 보안

모드	격리	용도
Subprocess	프로세스	신뢰된 에이전트
Docker	컨테이너	파일 작업
Wasm	메모리	높은 보안

영어 버전: English Version

[Multi-Agent] 파일 기반 아키텍처 설계

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

파일 기반 멀티 에이전트 아키텍처 설계

상태: 설계 제안 작성자: multi-agent-architect 날짜: 2026-02-24 유형: 대안 아키텍처 (프로세스-단위-에이전트)

개요

이 문서는 각 에이전트가 별도의 설정 파일로 정의되고 독립적인 프로세스로 실행되는 파일 기반, 프로세스-단위-에이전트 아키텍처를 정의합니다. 에이전트는 필요시 호출되어 메인 코디네이터 에이전트에게 결과를 보고합니다.

핵심 원칙

파일 기반 에이전트 정의: 각 에이전트는 agents/ 디렉토리의 .toml 파일
프로세스 격리: 각 에이전트는 자체 프로세스에서 실행
온디맨드 호출: 메인 에이전트가 필요시 서브프로세스 에이전트 생성
보고 프로토콜: IPC를 통한 구조화된 결과 보고
제로-설정 디스커버리: 에이전트 정의 자동 감지

1. 에이전트 정의 파일 구조

1.1 디렉토리 레이아웃

~/.zeroclaw/
├── config.toml # 메인 설정
├── agents/ # 에이전트 정의 디렉토리
│ ├── researcher.toml # 리서치 에이전트
│ ├── coder.toml # 코드 생성 에이전트
│ ├── tester.toml # 테스팅 에이전트
│ ├── reviewer.toml # 코드 리뷰 에이전트
│ └── summarizer.toml # 요약 에이전트
├── agents.d/ # 선택사항: 추가 에이전트 디렉토리
│ └── custom/
│ └── my_agent.toml
└── workspace/ # 공유 워크스페이스

1.2 에이전트 파일 스키마

# agents/researcher.toml

# 에이전트 메타데이터
[agent]
id = "researcher"
name = "Research Agent"
version = "1.0.0"
description = "Conducts research on given topics using web search and knowledge bases"

# 실행 설정
[agent.execution]
# 에이전트 실행 방식: "subprocess" | "wasm" | "docker"
mode = "subprocess"

# 실행 명령어 (템플릿 변수: {agent_id}, {workspace}, {config_dir})
command = "zeroclaw"
args = [
 "agent",
 "run",
 "--agent-id", "{agent_id}",
 "--config", "{config}/agents/researcher.toml",
 "--workspace", "{workspace}"
]

# 서브프로세스 작업 디렉토리
working_dir = "{workspace}"

# 서브프로세스 환경변수
[agent.execution.env]
ZEROCLAW_AGENT_MODE = "worker"
ZEROCLAW_AGENT_ID = "researcher"

# 프로바이더 설정 (메인 설정 오버라이드)
[provider]
name = "openrouter"
model = "anthropic/claude-sonnet-4-6"
api_key = null # 메인에서 상속, 또는 에이전트별 키 설정
temperature = 0.3
max_tokens = 4096

# 이 에이전트에서 사용 가능한 도구
[[tools]]
name = "web_search"
enabled = true

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

# 이 에이전트에서 명시적으로 거부된 도구
[[tools.deny]]
name = "shell"
reason = "Research agent should not execute shell commands"

# 시스템 프롬프트
[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]
backend = "shared" # "shared" | "isolated"
category = "research"

# 보고 설정
[reporting]
mode = "ipc"
format = "json" # "json" | "markdown" | "both"
timeout_seconds = 300

# 재시도 설정
[retry]
max_attempts = 3
backoff_ms = 1000

2. 에이전트 레지스트리

AgentRegistry는 에이전트 정의를 발견하고 관리합니다:

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. 프로세스 간 통신 (IPC)

태스크 메시지 (메인 → 에이전트)

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>>,
}

결과 메시지 (에이전트 → 메인)

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. 보안 고려사항

실행 모드	격리 수준	사용 사례
Subprocess	프로세스 수준	신뢰할 수 있는 에이전트
Docker	컨테이너	신뢰할 수 없는, 파일 작업
Wasm	메모리 전용	높은 보안 요구사항

5. CLI 명령어

# 사용 가능한 에이전트 목록
zeroclaw agent list

# 에이전트 상세 정보
zeroclaw agent show <agent_id>

# 에이전트 직접 실행 (테스트용)
zeroclaw agent run --agent-id researcher --prompt "Research X"

# 템플릿에서 새 에이전트 생성
zeroclaw agent create --id my-agent --name "My Agent"

# 에이전트 정의 검증
zeroclaw agent validate <agent_id>

6. 성공 기준

에이전트 정의 파일 로드 시 검증
서브프로세스 에이전트 생성 및 태스크 완료
IPC 프로토콜 1GB 이상 데이터 지원
메인 에이전트가 도구를 통해 워커 에이전트 호출 가능
실패한 에이전트가 메인 에이전트 크래시 유발하지 않음
에이전트별 보안 정책 적용
에이전트 관리 CLI 명령어

영어 버전: English Version

[ZeroClaw] 코드베이스 아키텍처 분석

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

ZeroClaw 코드베이스 아키텍처 분석 보고서

2026년 2월 26일 작성

개요

ZeroClaw는 Rust로 작성된 고성능 자율 에이전트 런타임입니다. 이 보고서는 코드베이스 구조와 보안 아키텍처에 대한 분석 결과를 정리합니다.

1. 핵심 아키텍처 패턴

ZeroClaw는 **트레이트 기반 확장성(Trait-driven extensibility)**을 핵심 설계 원칙으로 채택하고 있습니다.

1.1 주요 트레이트 (7개)

트레이트	위치	역할
`Provider`	src/providers/traits.rs	AI 모델 프로바이더 인터페이스
`Channel`	src/channels/traits.rs	통신 채널 인터페이스
`Tool`	src/tools/traits.rs	도구 실행 인터페이스
`Memory`	src/memory/traits.rs	메모리 백엔드 인터페이스
`Observer`	src/observability/traits.rs	관측 가능성 인터페이스
`RuntimeAdapter`	src/runtime/traits.rs	런타임 어댑터 인터페이스
`Peripheral`	src/peripherals/traits.rs	하드웨어 주변장치 인터페이스

2. 보안 아키텍처

ZeroClaw는 다층 방어(Defense-in-Depth) 전략을 통해 보안을 구현합니다.

2.1 보안 레이어 (6개)

SecurityPolicy Core - 자율성 수준 관리
Gateway Security - Bearer 토큰 인증
Tool Validation - 인젝션 방지
Runtime Sandbox - Landlock/Firejail/Docker
Secret Management - ChaCha20-Poly1305
Audit Logging - 이벤트 추적

2.2 핵심 보안 경계

명령어 허용 목록: 15개
속도 제한: 20회/시간
환경 변수: 8개만 허용

3. 멀티 에이전트 시스템

구현 로드맵

Phase	기간	내용
1	1주	코어 트레이트, DelegateTool 확장
2	2-3주	Docker/Wasm 실행 모드
3	4주+	분산 메시지 버스, 합의 알고리즘

결론

ZeroClaw는 확장성, 보안, 성능, 유지보수성 측면에서 우수한 아키텍처를 가지고 있습니다.

이 보고서는 ZeroClaw 개발 팀의 협업 분석 결과를 바탕으로 작성되었습니다.

영어 버전: English Version

[Multi-Agent] 통신 플랫폼 설계 고찰

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

들어가며

AI 에이전트 시스템이 발전하면서 단일 에이전트에서 멀티 에이전트 시스템으로의 전환이 가속화되고 있습니다. 이 글에서는 멀티 에이전트 간의 효율적인 통신을 위한 플랫폼 아키텍처를 설계하는 방법에 대해 고찰합니다.

1. 아키텍처 개요

멀티 에이전트 플랫폼은 크게 Orchestrator, Message Bus, 그리고 다양한 특화된 에이전트들로 구성됩니다.

Multi-Agent Architecture

핵심 컴포넌트

컴포넌트	역할
Orchestrator	태스크 조율, 에이전트 스케줄링
Message Bus	에이전트 간 통신 중계
State Store	공유 상태 관리
Task Queue	우선순위 기반 작업 큐
Agents	특화된 작업 수행

2. 통신 프로토콜 설계

에이전트 간 통신은 비동기 메시지 패싱을 기반으로 설계합니다.

Message Protocol

통신 흐름

Publish: 에이전트가 태스크 요청을 메시지 버스에 발행
Route: 버스가 적절한 에이전트에게 메시지 라우팅
Accept: 대상 에이전트가 태스크 수락
Acknowledge: 버스가 요청자에게 수락 확인
Execute: 에이전트가 실제 작업 수행
Result: 결과를 버스에 발행
Deliver: 버스가 결과를 요청자에게 전달

3. 메시지 구조

확장 가능하고 타입 안전한 메시지 구조를 설계합니다.

Message Structure

메시지 엔벌로프

{
 "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": "..."
 }
 }
}

메시지 타입

타입	용도
`TASK_REQUEST`	작업 요청
`TASK_RESULT`	작업 결과
`STATUS_UPDATE`	상태 변경 알림
`HEARTBEAT`	생존 확인
`QUERY`	정보 조회
`RESPONSE`	조회 응답

4. 에이전트 상태 관리

각 에이전트는 명확한 상태 머신을 가집니다.

State Management

상태 전이

IDLE → RECEIVING → PROCESSING → EXECUTING → COMPLETED → IDLE
 ↘ ↘ ↘
 ERROR ──────→ retry ──→ IDLE

상태별 동작

상태	동작
IDLE	새 태스크 대기
RECEIVING	메시지 수신 및 검증
PROCESSING	태스크 분석 및 준비
EXECUTING	실제 작업 수행
COMPLETED	결과 전송 및 정리
ERROR	오류 처리 및 재시도

5. 통신 패턴

5.1 Request-Response

동기식 1:1 통신 패턴입니다.

# 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)

비동기식 1:N 통신 패턴입니다.

# Subscribe
@bus.subscribe("research.completed")
async def handle_research_result(message):
 # 연구 결과 처리
 pass

# Publish
await bus.publish(
 topic="research.completed",
 message=ResearchResult(data={...})
)

5.3 Broadcast

전체 에이전트에게 알림을 보낼 때 사용합니다.

# Broadcast
await bus.broadcast(
 message=SystemAlert(
 level="warning",
 message="High load detected"
 )
)

6. 핵심 설계 원칙

6.1 느슨한 결합 (Loose Coupling)

에이전트는 서로의 내부 구현을 알지 못해야 합니다. 메시지 인터페이스를 통해서만 통신합니다.

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)

수평적 확장: 동일한 역할의 에이전트를 추가
로드 밸런싱: 메시지 버스에서 자동 분배
샤딩: 태스크 타입별로 에이전트 그룹 분리

6.4 관찰 가능성 (Observability)

# 메트릭 수집
@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. 구현 고려사항

7.1 메시지 직렬화

포맷	장점	단점
JSON	가독성, 호환성	크기, 성능
Protocol Buffers	성능, 스키마	복잡성
MessagePack	JSON 호환, 크기	도구 지원

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)

처리 실패한 메시지를 별도 큐로 이동시켜 분석 및 재처리합니다.

8. 결론

멀티 에이전트 통신 플랫폼은 다음 요소들이 핵심입니다:

유연한 메시지 구조: 다양한 통신 시나리오 지원
명확한 상태 관리: 예측 가능한 에이전트 동작
다양한 통신 패턴: 요청-응답, 발행-구독, 브로드캐스트
내결함성 설계: 재시도, 타임아웃, 에러 처리

이러한 원칙들을 기반으로 확장 가능하고 신뢰할 수 있는 멀티 에이전트 시스템을 구축할 수 있습니다.

참고 자료

영어 버전: English Version

Architecture on Yarang's Tech Lair

MCP 통합 가이드: ZeroClaw 런타임에서 Discord MCP 연동하기

1. 아키텍처 설계: 단일 채널에서의 이중 통신

2. 필수 의존성 및 설정 (Rust)

3. MCP 클라이언트 구현

4. ZeroClaw 에이전트와의 통합

5. 효율성 및 보안 고려사항 (Architecture Insights)

마무리하며

ZeroClaw 에이전트 런타임: 고성능 멀티 에이전트 통신을 위한 TCP/IP 아키텍처 구현

기존 통신의 문제점과 ZeroClaw의 접근

Rust Tokio를 활용한 비동기 서버 구조

1. 기본 메시지 구조 정의

2. 비동기 TCP 핸들러 구현

팀 에이전트 통신과 프로토콜 설계

결론: 확장 가능한 에이전트 시스템을 향하여

참고 코드 및 리소스

Zero-Touch OAuth 구현을 위한 MCP 인증 아키텍처 설계

왜 Zero-Touch인가?

아키텍처 설계

구현 단계 1: 서버 사이드 (blog-api-server)

구현 단계 2: 클라이언트 사이드 (MCP Client)

ZeroClaw 런타임 통합 고찰

마치며

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

JWT의 달콤한 함정

1. 폐기 불가능성(Revocation Problem)

2. 토큰 크기와 부하

세션 기반 인증으로의 회귀

사전 준비

구현 코드 (Go)

코드 설명 및 적용 팁

결론: 무엇을 선택해야 할까?

Rust로 구축하는 고성능 에이전트 런타임: ZeroClaw 아키텍처 심층 분석

Rust로 구축하는 고성능 에이전트 런타임: ZeroClaw 아키텍처 심층 분석

1. 왜 Rust인가? (Safe Concurrency)

2. 통신 프로토콜 설계: 파일 기반 vs 메모리 기반

2.1. 요청-응답 패턴 구현

3. MCP와의 연동: 브릿지 패턴

4. 2026 상반기 로드맵: 고도화 방향

결론

MCP 기반 멀티 에이전트 시스템의 통신 프로토콜 설계와 Rust 구현

1. 문제 정의: 왜 통신 프로토콜인가?

2. 프로토콜 설계: 요청, 작업, 완료

3. Rust로 구현하는 ZeroClaw 통신 계층

3.1. 메시지 정의 (JSON-RPC 기반)

3.2. 에이전트 런타임 구조

4. 결론 및 다음 단계

참고자료

[ZeroClaw] 비동기 에이전트 런타임을 위한 Rust 채널 기반 IPC 설계

[ZeroClaw] 비동기 에이전트 런타임을 위한 Rust 채널 기반 IPC 설계

1. 기존 아키텍처의 문제점과 비동기 설계의 필요성

2. Rust의 tokio::sync::mpsc를 활용한 이벤트 루프 구조

핵심 설계 포인트

3. 실전 코드: 구체적인 구현 예제

Step 1: 메시지 프로토콜 정의

Step 2: 에이전트 구조체 및 러너(Runner) 구현

Step 3: 메인 런타임 및 채널 연결

4. ZeroClaw 프로젝트 적용 효과

마치며

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

1. ZeroClaw 아키텍처와 MCP의 결합

2. 핵심 구조: 비동기 요청 라우팅

2.1. Cargo.toml 설정

2.2. MCP 메시지 구조 정의

3. 경량화된 요청 핸들러 구현

4. 고급 최적화: ZeroClow 통합

5. 결론

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

1. MCP 서버의 핵심 요구사항

2. 아키텍처 설계: ZeroClaw 스타일

3. 실전 코드 예제

3.1. 의존성 설정 (Cargo.toml)

3.2. 핸들러 트레이트 정의

3.3. 로그 읽기 도구 구현

3.4. 메인 루프 및 JSON-RPC 서버

4. 최적화 및 배포 고려사항

5. 결론

2. Rust의 `tokio::sync::mpsc`를 활용한 이벤트 루프 구조

3.1. 의존성 설정 (`Cargo.toml`)