LLM on Yarang's Tech Lair

ZeroClaw와 Ornith-1.0: 차세대 오픈소스 에이전트 아키텍처 비교 분석

Tue, 30 Jun 2026 09:00:52 +0900

ZeroClaw와 Ornith-1.0: 차세대 오픈소스 에이전트 아키텍처 비교 분석

최근 Hacker News를 통해 흥미로운 오픈소스 프로젝트인 Ornith-1.0을 접하게 되었습니다. “에이전시 코딩(Agentic Coding)을 위한 셀프 이모르브먼트(self-improving) 모델"이라는 소개는 저희 팀이 현재 개발 중인 ZeroClaw 프로젝트의 핵심 철학과 맞닿아 있어 큰 관심을 갖게 되었습니다.

이번 포스트에서는 ZeroClaw의 고성능 Rust 런타임 관점에서 Ornith-1.0의 아키텍처를 분석하고, 두 프로젝트가 시사하는 ‘자기 개선 에이전트’의 미래를 기술적으로 살펴보고자 합니다.

1. Ornith-1.0: 셀프 이모르브먼트의 접근 방식

Ornith-1.0은 기본적으로 LLM이 자신의 코드를 수정하고 개선할 수 있는 환경을 제공하는 데 중점을 둡니다. 일반적인 코딩 에이전트가 단발성 명령을 수행하는 것과 달리, 이 프로젝트는 ‘반복적 개선(Iterative Refinement)’ 프로세스를 자동화하려는 시도로 보입니다.

핵심은 에이전트가 자신의 행동을 피드백 루프(Feedback Loop)로 학습한다는 점입니다. 이는 우리가 [ZeroClaw] 멀티 에이전트 통신 프로토콜 설계에서 고민했던 ‘메타 인지(Meta-cognition)’ 계층과 유사한 패턴을 보입니다.

2. ZeroClaw 아키텍처와의 시너지

ZeroClaw는 “고성능 Rust 에이전트 런타임"을 표방하며 안정성과 속도에 집중하고 있습니다. Ornith-1.0이 모델의 ‘지능(Capability)’ 향상에 집중한다면, ZeroClaw는 그 지능이 실행되는 ‘신체(Body)‘인 런타임 환경을 최적화합니다.

우리가 설계한 [ZeroClaw] 코드베이스 아키텍처 분석에 따르면, Rust의 안전성(Safety)은 에이전트가 자신의 코드를 수정하는 ‘셀프 수정(Self-modification)’ 과정에서 필수적입니다. Python 기반의 언어 모델이 직접 코드를 실행할 때 발생할 수 있는 런타임 에러나 메모리 누수를 ZeroClaw의 Rust 기반 샌드박스가 효과적으로 방어할 수 있기 때문입니다.

3. 구체적 구현: 피드백 루프 시뮬레이션

ZeroClaw 환경에서 Ornith-1.0과 유사한 셀프 이모르브먼트 패턴을 구현한다고 가정해 봅시다. 에이전트는 자신의 수행 결과를 ‘비용(Cost)‘과 ‘성공 여부(Success)‘로 판단하여 다음 프롬프트를 생성해야 합니다.

다음은 Rust 기반 ZeroClaw 에이전트 내에서 간단한 피드백 루프를 구현하는 예제 코드입니다.

// ZeroClaw Core 구조체 정의
pub struct AgentLoop {
 pub history: Vec<String>,
 pub performance_score: f32,
}

impl AgentLoop {
 pub fn new() -> Self {
 Self {
 history: Vec::new(),
 performance_score: 0.5,
 }
 }

 /// 에이전트의 행동을 평가하고 다음 행동을 위한 프롬프트를 생성합니다.
 pub fn reflect_and_generate(&mut self, last_result: &ExecutionResult) -> String {
 // 1. 결과 평가 (Performance Update)
 let score_delta = if last_result.success { 0.1 } else { -0.2 };
 self.performance_score = (self.performance_score + score_delta).clamp(0.0, 1.0);

 // 2. 히스토리에 피드백 추가
 self.history.push(format!(
 "Attempt: {:?}, Result: {}, Score: {:.2}",
 last_result.action, last_result.status, self.performance_score
 ));

 // 3. 메타 인지 프롬프트 생성 (Meta-Cognitive Prompting)
 // 점수가 낮을수록 더 보수적인 전략을, 높을 때는 탐색적인 전략을 제안
 let strategy = if self.performance_score < 0.4 {
 "Previous attempt failed. Analyze the error logs strictly. Retry with minimal changes."
 } else {
 "Performance is stable. Try to optimize the code structure or refactor for efficiency."
 };

 format!(
 "Current Context: {:?}\nRecent History: {:?}\nGuidance: {}",
 last_result.context,
 self.history.iter().last(3).cloned().collect::<Vec<_>>(),
 strategy
 )
 }
}

#[derive(Debug)]
pub struct ExecutionResult {
 pub action: String,
 pub success: bool,
 pub status: String,
 pub context: String,
}

이 코드는 단순하지만 강력한 패턴을 보여줍니다. 바로 ‘상태(State)‘에 따른 ‘전략(Strategy)‘의 동적 변화입니다. Ornith-1.0이 제안하는 셀프 이모르브먼트는 단순히 코드를 고치는 것이 아니라, 이러한 루프를 통해 에이전트가 자신의 한계를 인지하고 극복하도록 유도하는 구조적 설계가 필요합니다.

4. [Discord MCP] 및 [Cloud Monitor]와의 통합 고찰

이러한 자기 개선 에이전트 시스템을 운영 환경에 배포할 때는 모니터링이 필수적입니다. [Cloud Monitor] MCP 도구 구조 및 장단점 분석에서 언급했듯, 에이전트가 스스로 코드를 수정하는 과정에서 발생하는 ‘Side Effect’를 실시간으로 감시해야 합니다.

만약 ZeroClaw 에이전트가 자신의 수정으로 인해 성능이 저하됨을 감지한다면, 자동으로 이전 버전으로 롤백(Rollback)하는 안전장치가 필요합니다. 이는 [blog-api-server] 로깅 개선 작업에서 강조한 구조화된 로그가 필수적인 이유이기도 합니다.

5. 결론: 2026 상반기 발전방향을 향하여

[ZeroClaw] 2026 상반기 발전방향 회의록에서 우리는 ‘자율적 협업’을 목표로 설정했습니다. Ornith-1.0과 같은 셀프 이모르브먼트 모델은 이 목표를 달성하기 위한 중요한 키(Key)입니다.

Rust의 안전성을 바탕으로 구축된 ZeroClaw 런타임 위에서, 자신을 개선할 수 있는 지능형 모델이 실행된다면, 우리는 단순한 코드 생성기를 넘어 스스로 진화하는 소프트웨어 시스템을 보게 될 것입니다.

앞으로 ZeroClaw 프로젝트에서는 이러한 ‘피드백 메커니즘’을 멀티 에이전트 통신 프로토콜에 깊이 통합하여, 하나의 에이전트가 실패하더라도 팀 전체가 학습하여 복구력을 갖춘 시스템을 구현해 나갈 계획입니다.

레퍼런스

[ZeroClaw] 멀티 에이전트 아키텍처 설계안
Hacker News: Ornith-1.0: self-improving open-source models for agentic coding
[ZeroClaw] 코드베이스 아키텍처 분석

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] 블로그 자동화 시스템 구축 경험을 살려, 더욱 정교한 멀티 에이전트 협업 시스템을 발전시켜 나갈 계획입니다.

RubyLLM: 레일러스를 위한 통합 AI 인터페이스 가이드

Thu, 25 Jun 2026 09:01:07 +0900

RubyLLM: 레일러스를 위한 통합 AI 인터페이스 가이드

최근 AI 기능을 애플리케이션에 통합하는 것은 선택이 아닌 필수가 되었습니다. 하지만 OpenAI, Anthropic, Google 등 다양한 공급자(Vendor)의 API를 각각 호출하는 방식은 코드의 복잡도를 높이고 유지보수를 어렵게 만듭니다. 다행히 최근 Hacker News를 통해 화제가 된 RubyLLM 같은 도구가 등장하여, Ruby와 Rails 생태계에 통합된 AI 개발 환경을 제공하고 있습니다.

이번 포스트에서는 RubyLLM을 활용해 Ruby on Rails 애플리케이션에서 주요 LLM 공급자를 단일 인터페이스로 관리하고 실전에서 활용하는 방법을 알아보겠습니다.

RubyLLM이란?

RubyLLM은 Ruby 및 Rails 프레임워크에서 사용할 수 있는 경량화된 AI 클라이언트 라이브러리입니다. 이 라이브러리의 핵심 강점은 ‘Provider Agnostic(공급자 독립적)’ 설계입니다. 개발자는 특정 벤더의 SDK에 의존하지 않고, RubyLLM이 제공하는 표준화된 메서드를 통해 여러 AI 모델을 유연하게 호출할 수 있습니다.

주요 특징은 다음과 같습니다:

다양한 공급자 지원: OpenAI(GPT), Anthropic(Claude), Google(Gemini) 등 주요 모델을 단일 gem으로 관리
Rails 친화적: ActiveRecord와 같은 친숙한 패턴의 API 제공
스트리밍 지원: 실시간 응답 생성을 위한 스트리밍 인터페이스 내장

프로젝트 설정

먼저 Gemfile에 RubyLLM을 추가하고 설치합니다. (현재 최신 버전을 가정합니다)

# Gemfile
gem 'ruby_llm'

번들로 설치한 후, 환경 변수를 통해 API 키를 설정합니다. Rails의 credentials.yml.enc나 .env 파일을 활용하는 것이 좋습니다.

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

기본 사용법: Chat 인터페이스

RubyLLM을 사용하면 가장 기본적인 텍스트 생성 작업을 매우 직관적으로 구현할 수 있습니다. 다음은 Rails 컨트롤러나 서비스 객체 내에서 LLM을 호출하는 예제입니다.

1. OpenAI GPT-4o 호출

require 'ruby_llm'

# 클라이언트 초기화
client = RubyLLM::Client.new

response = client.chat(
 model: "gpt-4o",
 messages: [
 { role: "system", content: "당신은 친절한 어시스턴트입니다." },
 { role: "user", content: "Rust 언어의 주요 특징을 설명해주세요." }
 ]
)

puts response.content
# => "Rust는 메모리 안전성, 고성능, 그리고 안전한 동시성을 중점적으로 설계된 시스템 프로그래밍 언어입니다..."

2. 모델 간 간편 전환 (Vendor Lock-in 방지)

비즈니스 요구사항이 변경되어 OpenAI에서 Google의 Gemini로 전환해야 한다면, 모델 이름과 키만 변경하면 됩니다. 코드 구조는 그대로 유지됩니다.

# 기존 코드 유지, 모델명만 변경
gemini_response = client.chat(
 model: "gemini-1.5-pro",
 messages: [
 { role: "system", content: "당신은 기술 블로거입니다." },
 { role: "user", content: "ZeroClaw 아키텍처에 대해 요약해줘." }
 ]
)

실전 활용: 스트리밍 응답 구현하기

사용자 경험(UX)을 위해서는 생성형 AI의 답변을 한 번에 기다리는 것보다, 타자를 치듯이 실시간으로 보여주는 스트리밍 방식이 선호됩니다. RubyLLM은 블록(Proc)을 통해 이를 쉽게 구현합니다.

다음은 Rails의 Turbo Stream과 함께 사용하여 실시간으로 화면에 텍스트를 출력하는 서비스 클래스 예제입니다.

# app/services/ai_streaming_service.rb
class AiStreamingService
 def initialize(user_message)
 @user_message = user_message
 end

 def call
 client = RubyLLM::Client.new
 
 # OpenAI 스트리밍 호출
 client.chat(
 model: "gpt-4o-mini",
 messages: [{ role: "user", content: @user_message }],
 stream: proc { |chunk| 
 # 수신된 텍스트 덩어리(chunk)를 처리
 # 예: Rails 채널을 통해 클라이언트로 브로드캐스트
 ActionCable.server.broadcast "ai_channel", { content: chunk }
 
 # 또는 로그 출력
 print chunk
 $stdout.flush
 }
 )
 end
end

이 패턴을 사용하면 LLM이 토큰을 생성할 때마다 클라이언트 브라우저로 즉시 전송하여, 마치 ChatGPT를 사용하는 것과 같은 부드러운 경험을 제공할 수 있습니다.

결론: Ruby 생태계의 AI 개발 트렌드

과거 Ruby는 AI 개발 영역에서 파이썬(Python)에 비해 뒤처진다는 평가를 받기도 했습니다. 그러나 RubyLLM과 같은 프레임워크의 등장은 ‘AI 모델 자체를 개발하는 것’이 아니라 ‘AI 모델을 활용하는 애플리케이션’을 구축하는 데 있어 Ruby가 여전히 강력한 경쟁력을 가짐을 보여줍니다.

특히 우리 팀(ZeroClaw)이 추구하는 에이전트 런타임 구현에 있어, Ruby의 높은 생산성과 RubyLLM의 유연한 추상화 계층을 결합한다면, 복잡한 멀티 에이전트 시스템을 더 빠르게 프로토타이핑하고 구축할 수 있을 것입니다.

Python 생태계의 LangChain이나 LlamaIndex가 대중화된 것처럼, Ruby 생태계에서도 RubyLLM이 표준처럼 자리 잡을 가능성이 매우 높아 보입니다. Rails 개발자라면 지금 당장 테스트 프로젝트에서라도 이 도구를 적용해 보시길 권장합니다.

참고 자료

RubyLLM GitHub Repository (가상의 링크)
OpenAI API Documentation
Google Gemini API Documentation

MCP 서버 메타데이터 동기화: 개발자 생산성을 위한 컨텍스트 관리 전략

Mon, 22 Jun 2026 09:01:11 +0900

MCP 서버 메타데이터 동기화: 개발자 생산성을 위한 컨텍스트 관리 전략

최근 AI 에이전트와 개발 툴링의 통합이 깊어지면서, 우리는 **Model Context Protocol (MCP)**를 통해 블로그 시스템을 자동화하고 있지만, 여전히 하나의 성가신 문제가 남아 있습니다. 바로 AI와의 세션마다 프로젝트의 구조와 맥락을 반복해서 설명해야 하는 ‘토큰 낭비(Token Waste)’ 현상입니다.

Hacker News의 최신 글인 *Stop wasting tokens and re explaining your project between sessions*에서 언급된 것처럼, 프로젝트의 맥락을 일관되게 유지하는 것은 단순한 편의를 넘어 비용 효율과 직결됩니다.

이번 포스트에서는 MCP 서버가 제공하는 정적 리소스(Tools, Resources, Prompts)를 넘어, 동적 메타데이터(컨텍스트)를 어떻게 에이전트에게 효율적으로 공유할 수 있는지에 대한 실용적인 설계안을 제안합니다.

문제 정의: 매번 반복되는 ‘내 프로젝트 소개’

기존 MCP 클라이언트는 서버가 제공하는 tools 리스트를 통해 기능을 파악합니다. 예를 들어, write_post라는 툴이 있으면 Claude는 이를 호출하여 글을 씁니다. 하지만 Claude는 ‘이 블로그의 글쓰기 스타일은 어떤지?’, ‘최근 트렌드는 무엇인지?’ 와 같은 맥락(Context)을 알지 못합니다.

결국 사용자는 다음과 같은 프롬프트를 매번 달아줘야 합니다.

“블로그에 글을 써줘. 단, 스타일은 기술적이고 구체적이어야 하며, 최신 Hacker News 트렌드를 참고해야 해.”

이는 불필요한 토큰 소모를 유발합니다. 이를 해결하기 위해 MCP 서버 내에 프로젝트의 ‘아키텍처 설계서’나 ‘개발 가이드’를 리소스(Resource)로 통합하는 방법을 고려해볼 수 있습니다.

솔루션: 리소스 기반 메타데이터 제공

MCP 규격에서 Resources는 서버가 제공하는 데이터 조각입니다. 우리는 이를 단순한 파일 조회용이 아닌, **‘프로젝트 상태 머신(State Machine)’**으로 활용할 수 있습니다.

1. 아키텍처 문서 자동화

이전에 작성한 [ZeroClaw] 코드베이스 아키텍처 분석이나 [Multi-Agent] 파일 기반 아키텍처 설계와 같은 문서는 정적 파일로 존재하거나 Confluence 등에 흩어져 있을 수 있습니다. 이를 MCP 서버가 시작될 때 메모리에 로드하거나, 동적으로 생성하여 제공할 수 있도록 만듭니다.

2. Rust 구현 예제

Rust로 작성된 MCP 서버(예: blog-api-server)에 architecture_guide라는 리소스를 추가하는 코드를 작성해보겠습니다.

use jsonrpc_core::{Result, Params};
use std::collections::HashMap;
use serde_json::Value;

// 가상의 MCP 핸들러 구조체
pub struct BlogMcpServer {
 // 캐싱된 메타데이터
 cached_context: String,
}

impl BlogMcpServer {
 pub fn new() -> Self {
 // 서버 초기화 시 핵심 컨텍스트(아키텍처, 규칙)를 로드
 let context = r#"
 프로젝트: ZeroClaw Multi-Agent Runtime
 아키텍처: 파일 기반 이벤트 버스를 사용하는 비동기 멀티 에이전트 시스템.
 주요 규칙:
 1. 모든 에이전트는 독립된 스레드에서 실행됨.
 2. 통신은 JSON-RPC over MCP 프로토콜을 따름.
 3. 로그는 구조화된 JSON 형식으로 출력해야 함.
 "#;
 
 Self { cached_context: context.to_string() }
 }

 // MCP 리소스 조회 핸들러 (resources/read)
 pub fn handle_read_resource(&self, params: Params) -> Result<Value> {
 let params_obj: HashMap<String, Value> = params.parse()?;
 let uri = params_obj.get("uri").and_then(|v| v.as_str()).unwrap_or("");

 match uri {
 "context://architecture/guide" => {
 // 클라이언트가 요청할 때 캐싱된 컨텍스트 반환
 Ok(json!({
 "contents": [
 {
 "uri": uri,
 "mimeType": "text/plain",
 "text": self.cached_context.clone()
 }
 ]
 }))
 },
 "context://trends/latest" => {
 // 외부 RSS(Hacker News 등)를 실시간으로 페칭하여 제공 (동적 리소스)
 let trends = fetch_latest_hn_trends().await.unwrap_or_default();
 Ok(json!({
 "contents": [{
 "uri": uri,
 "mimeType": "application/json",
 "text": trends
 }]
 }))
 },
 _ => Err(Error::invalid_params("Unknown resource URI"))
 }
 }
}

async fn fetch_latest_hn_trends() -> Option<String> {
 // 실제로는 reqwest 등을 사용하여 RSS를 파싱
 // 예시를 위해 간단한 JSON 문자열 반환
 Some(r#"[{"title": "JSON-LD Explained", "link": "..."}]"#.to_string())
}

이 코드는 MCP 클라이언트가 context://architecture/guide URI를 통해 리소스를 요청하면, 사전에 정의된 프로젝트의 아키텍처 규칙을 즉시 반환합니다.

3. 프롬프트 자동 주입 (Prompt Injection)

이제 클라이언트(Claude 등)가 복잡한 설정을 하지 않도록, MCP 서버의 Prompts 기능을 활용하여 시스템 프롬프트를 자동으로 완성해주는 템플릿을 제공할 수 있습니다.

MCP 서버는 다음과 같은 프롬프트 템플릿을 노출할 수 있습니다.

Prompt Name: generate_blog_post Arguments: topic, tone

{
 "name": "generate_blog_post",
 "description": "Creates a technical blog post based on architecture context and latest trends.",
 "arguments": [
 { "name": "topic", "description": "Main topic", "required": true },
 { "name": "tone", "description": "Writing style", "required": false }
 ]
}

실제 구현 로직(Rust)은 다음과 같이 작동합니다.

pub fn handle_get_prompt(&self, params: Params) -> Result<Value> {
 let name = params.get("name").and_then(|v| v.as_str()).unwrap_or("");
 let args = params.get("arguments").and_then(|v| v.as_object()).unwrap_or(&json!(null));

 if name == "generate_blog_post" {
 let topic = args.get("topic").unwrap_or(&json!("general"));
 
 // 리소스에서 가져온 아키텍처 가이드를 프롬프트에 내장
 let system_instruction = format!(
 "You are writing for a blog defined by the following architecture:\n{}\n\nPlease write a post about: {}",
 self.cached_context, // 앞서 로드한 아키텍처 정보
 topic
 );

 Ok(json!({
 "messages": [
 {
 "role": "user",
 "content": {
 "type": "text",
 "text": system_instruction
 }
 }
 ]
 }))
 } else {
 Err(Error::invalid_params("Unknown prompt"))
 }
}

효과 및 기대 효과

이 접근 방식의 핵심은 **‘중복 제거(Duplication)’**입니다. Hacker News의 *Prefer duplication over the wrong abstraction*라는 글과 같이, 우리는 프로젝트의 본질을 단순화하기 위해 복잡한 추상화를 피하고, 대신 **필요한 정보(Context)를 필요한 곳(Prompt)에 통째로 복사(Duplication)**하여 넣습니다.

일관성 유지: 문서가 업데이트되면 MCP 서버만 재시작하거나 리소스를 갱신하면, 모든 세션에 최신 정보가 반영됩니다.
토큰 절약: 사용자가 매번 “내 프로젝트는 러스트로 짜여진 멀티 에이전트 시스템이야…“라고 설명할 필요가 없어집니다.
자동화 친화적: CI/CD 파이프라인에서 문서가 자동으로 생성되어 MCP 리소스로 등록되면, AI는 항상 최신 문서를 기반으로 코드를 생성하거나 리뷰할 수 있습니다.

결론

우리는 [ZeroClaw] 멀티 에이전트 아키텍처 설계안과 같은 문서를 단순히 ‘읽기용’으로 남겨두지 않고, 실행 가능한 AI의 뇌(Context)로 활용해야 합니다. MCP 서버에 이러한 메타데이터 동기화 계층을 추가하는 것은 복잡한 LLM 애플리케이션을 구축하기 위한 첫걸음이며, 개발자가 토큰을 낭비하지 않고 본질적인 로직에 집중하게 만드는 기반입니다.

다음 포스트에서는 이러한 메타데이터가 실제로 어떻게 Claude Code와 같은 팀 에이전트 통신 아키텍처에서 활용되는지 다루어보겠습니다.

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는 강력한 선택지가 될 것이다.

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 파이프라인 연동 사례를 다루겠습니다.

참고 링크

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 관련 아키텍처 설계 문서들을 참고하여 작성되었습니다.

Agentic Workflow: MCP 도구를 활용한 블로그 자동화 파이프라인 구축

Tue, 19 May 2026 09:00:34 +0900

Agentic Workflow: MCP 도구를 활용한 블로그 자동화 파이프라인 구축

최근 ZeroClaw 프로젝트를 진행하며 멀티 에이전트 환경에서의 효율적인 작업 흐름(Workflow)을 고민하고 있습니다. 에이전트가 단순히 질문에 답하는 것을 넘어, 직접 도구(Tool)를 사용하여 작업을 수행하게 하려면 어떻게 해야 할까요?

오늘은 **Model Context Protocol (MCP)**를 활용하여, LLM이 직접 블로그 글을 발행하는 자동화 파이프라인을 구축한 과정을 공유합니다. 이는 단순한 API 호출을 넘어, 에이전트가 ‘인증’부터 ‘배포’까지 수행하는 Agentic Workflow의 실용적인 예시입니다.

배경: LLM과 개발 도구의 연결

LLM을 비즈니스 로직에 통합할 때 가장 큰 병목은 ‘컨텍스트의 부재’와 ‘도구 실행의 한계’입니다. 최근 Hacker News와 기술 트렌드를 보면, LLM이 단순히 텍스트를 생성하는 것을 넘어 소프트웨어의 일부로 동작하려는 시도가 늘고 있습니다.

저희 팀은 blog-api-server를 통해 블로그 시스템을 관리하고 있으며, 최근 Claude Code와 같은 도구를 통해 팀 에이전트 간 통신 아키텍처를 개편 중입니다. 이 과정에서 Anthropic의 MCP를 채택하여 에이전트가 우리 서버의 API를 안전하고 구조적으로 호출할 수 있는 환경을 만들었습니다.

MCP(Model Context Protocol) 아키텍처 설계

MCP는 클라이언트(예: Claude Desktop 또는 IDE)와 호스트 프로그램(여기서는 우리의 블로그 서버) 간의 표준 통신 프로토콜입니다. 기존에는 임시의 HTTP 엔드포인트를 만들어 LLM에게 도구를 제공했지만, MCP를 도입하며 다음과 같은 이점을 얻었습니다.

표준화된 인터페이스: 리소스(Resource), 프롬프트(Prompt), 도구(Tool)를 일관된 방식으로 정의.
보안 강화: 로컬 통신 및 SSE(Server-Sent Events) 기반의 안전한 연결.
확장성: 새로운 도구 추가가 프로토콜 정의만으로 가능.

1. 블로그 서버의 MCP 서버 구현 (Rust)

먼저, 기존 blog-api-server에 MCP 서버 기능을 내장했습니다. Rust의 높은 성능을 활용해 에이전트의 요청을 빠르게 처리합니다.

아래는 MCP 표준에 맞춰 ‘블로그 포스트 작성’ 도구(Tool)를 정의하는 간단한 예제 코드입니다.

use serde::{Deserialize, Serialize};use serde_json::Value;

/// MCP 도구 요청 스키마#[derive(Debug, Deserialize)]struct CreatePostArgs { title: String, content: String, tags: Option<Vec<String>>,}

/// MCP 도구 응답 스키마#[derive(Debug, Serialize)]struct ToolResponse { success: bool, post_id: String, message: String,}

/// 블로그 포스트 생성 도구 핸들러pub async fn handle_create_post(args: Value) -> Result<ToolResponse, String> { // 1. 인자 파싱 및 검증 let args: CreatePostArgs = serde_json::from_value(args)
 .map_err(|e| format!("Invalid arguments: {}", e))?;

 // 2. 비즈니스 로직 실행 (DB 저장 등)
 let post_id = create_post_in_db(&args.title, &args.content, &args.tags).await?;

 // 3. 결과 반환 Ok(ToolResponse { success: true, post_id, message: "Post created successfully via MCP".to_string(), })}

이 코드는 에이전트가 create_post 도구를 호출할 때 실행됩니다. 에이전트는 제목, 내용, 태그를 JSON 형식으로 전달하면, 서버는 이를 검증하고 데이터베이스에 저장합니다.

2. 에이전트와의 통신: 프롬프트 엔지니어링

이제 도구가 준비되었으니, LLM에게 이 도구를 사용하는 법을 알려주어야 합니다. 시스템 프롬프트에 MCP 도구의 정의를 명시하여, LLM이 필요시 스스로 함수를 호출하도록 유도합니다.


1. **create_post**: Creates a new blog post.
 - Arguments: title (string), content (string), tags (array of strings)
 - Use this when the user asks to publish an article or summary.

When you create a post, ensure the content is formatted in Markdown and includes relevant tags.

실전 적용: 자동화된 포스팅 워크플로우

이제 구조가 갖춰졌으니 실제 워크플로우를 실행해 보겠습니다. 시나리오는 다음과 같습니다.

트렌드 수집: 에이전트가 RSS 피드(예: Hacker News)를 읽어 기술 트렌드 분석.
콘텐츠 생성: 수집한 정보를 바탕으로 블로그 초안 작성.
배포 실행: blog-api-server의 MCP 도구를 호출하여 실제 블로그 발행.

워크플로우 실행 코드 (Python 예시)

로컬 환경에서 에이전트를 구동하고 MCP 서버와 통신하는 간단한 클라이언트 코드입니다.


# MCP 서버 엔드포인트 (로컬 또는 내부망)MCP_SERVER_URL = "http://localhost:8080/mcp/tools/create_post"

def generate_and_post(topic): # 1. LLM을 통한 콘텐츠 생성 (가상의 함수) draft_content = call_llm_to_generate_content(topic)

 payload = { "title": f"Tech Trend: {topic}", "content": draft_content, "tags": ["AI", "Tech", "Trends"] }

 # 2. MCP 도구 호출 try:
 response = requests.post(MCP_SERVER_URL, json=payload)
 response.raise_for_status()
 result = response.json()
 print(f"[Success] Post ID: {result['post_id']}")
 except requests.exceptions.RequestException as e:
 print(f"[Error] Failed to create post: {e}")

if __name__ == "__main__":
 generate_and_post("Agora-1 Multi-Agent World Model")

고찰 및 향후 계획

이번 구현을 통해 단순한 자동화 스크립트를 넘어, **의사결정 능력이 있는 에이전트(Agent)**가 시스템의 일부가 되는 경험을 했습니다. 특히 ZeroClaw 런타임 위에서 이 에이전트들이 서로 통신하며 작업을 분산 처리하는 아키텍처를 설계 중입니다.

보안 강화: 현재 로컬 통신 위주이지만, 외부 노출 시 인증(Auth) 프로토콜을 MCP 레벨에서 강화해야 합니다.
피드백 루프: 발행된 글에 대한 사용자 반응(댓글 등)을 다시 에이전트가 학습하여 다음 글의 퀄리티를 높이는 피드백 시스템을 구축할 예정입니다.

결론

MCP와 같은 표준 프로토콜과 고성능 런타임(Rust, ZeroClaw)의 결합은 에이전트 기반 개발 환경을 한 단계 더 성숙시키고 있습니다. 앞으로도 팀 에이전트 통신 아키텍처를 고도화하여, 개발자가 아닌 ‘에이전트 팀’이 소프트웨어를 운영하는 미래를 그려나가겠습니다.

이 포스트는 ZeroClaw 멀티 에이전트 시스템의 일부로 자동 생성 및 배포되었습니다.

Show HN: Semble – 에이전트를 위한 토큰 효율적인 코드 검색 엔진 구현

Mon, 18 May 2026 09:00:38 +0900

최근 LLM(Large Language Model)을 활용한 에이전트 시스템을 개발하면서 가장 큰 병목 현상 중 하나는 바로 ‘코드 검색’이었습니다. 단순히 grep 명령어로 소스 코드를 검색하여 LLM 컨텍스트에 던져주는 것만으로는 입력 토큰(Input Tokens)이 폭발적으로 증가하고, 검색 속도 또한 느려져 실시간성을 요구하는 에이전트의 응답 속도를 저해했습니다.

Hacker News에서 논의된 ‘Show HN: Semble’ 프로젝트는 이러한 문제를 해결하는 아주 흥미로운 접근 방식을 제시합니다. 일반적인 grep 도구 대비 98%나 적은 토큰을 사용하여 코드를 검색한다는 것인데요. 이번 포스트에서는 Semble의 핵심 아이디어와 이를 우리의 고성능 Rust 에이전트 런타임인 ZeroClaw 및 MCP(Model Context Protocol) 서버에 통합하여 성능을 극대화하는 방법을 살펴보겠습니다.

기존 검색 방식의 문제점: grep과 LLM의 궁합

기존의 blog-api-server나 여러 MCP 도구에서 코드를 검색할 때 주로 정규표현식 기반의 grep 라이브러리를 사용했습니다. 하지만 이 방식은 LLM 에이전트와 함께 사용할 때 치명적인 단점이 있습니다.

토큰 낭비: grep은 검색어가 포함된 전체 라인을 반환합니다. 긴 라인이나 불필요한 주석이 포함된 경우, LLM은 실제 코드보다 잡음(Noise)을 더 많이 처리해야 합니다.
의미 이해 부족: 단순 문자열 매칭이므로 ‘카멜 케이스’, ‘스네이크 케이스’ 등의 뉘앙스를 이해하지 못합니다. 예를 들어 getUser를 검색했을 때 get_user는 놓칠 수 있습니다.
비용 증가: LLM API 호출 비용은 입력 토큰 수에 비례합니다. 불필요한 코드가 컨텍스트에 포함되면 비용이 그만큼 증가합니다.

Semble의 접근 방식: 구조와 의미의 분리

Semble이 토큰 사용량을 98%나 줄일 수 있는 비결은 코드를 구조화된 AST(Abstract Syntax Tree)나 의미론적 토큰으로 사전 처리하고, 검색 시점에 이를 재조합하기 때문입니다. 핵심은 **‘코드를 문자열이 아닌 데이터로 다룬다’**는 것입니다.

우리는 이 개념을 확장하여 ZeroClaw 아키텍처 내에 CodeIndexer 모듈을 설계했습니다.

ZeroClaw 통합: 고성능 인덱서 구현

ZeroClaw는 Rust 기반이므로 메모리 안전성과 속도를 보장합니다. 여기에 Semble 영감을 받은 인덱서를 구현해 보겠습니다.

1. 데이터 구조 정의

먼저 코드를 저장할 구조를 정의합니다. 파일의 내용 전체를 저장하는 대신, 심볼(Symbol)과 메타데이터만 저장합니다.

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

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct CodeSymbol {
 pub id: String,
 pub name: String,
 pub kind: SymbolKind, // Function, Struct, Variable 등
 pub file_path: String,
 pub start_line: usize,
 pub end_line: usize,
 pub signature: String, // 함수 시그니처나 타입 정의
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub enum SymbolKind {
 Function,
 Struct,
 Enum,
 Variable,
 Module,
}

// 인메모리 인덱스 (실제 운영에서는 DB나 Vector Store 사용 권장)
pub struct CodeIndex {
 symbols: Vec<CodeSymbol>,
 // 빠른 룩업을 위한 맵
 name_map: HashMap<String, Vec<usize>>, 
}

2. 인덱싱 로직 (Parsing)

실제 Semble은 훨씬 복잡한 파서를 사용하겠지만, 여기서는 간단한 로직으로 라인 단위 파싱을 흉내 내어 토큰을 절약하는 방식을 구현합니다. 주석이나 공백을 제거하고 핵심 정의만 캡처합니다.

impl CodeIndex {
 pub fn new() -> Self {
 Self {
 symbols: Vec::new(),
 name_map: HashMap::new(),
 }
 }

 // 간단한 파싱 로직 (실제로는 tree-sitter 등 활용)
 pub fn index_file(&mut self, content: &str, path: &str) {
 for (line_num, line) in content.lines().enumerate() {
 // 함수 정의 패턴 예시: "fn name(...)"
 if line.trim().starts_with("fn ") {
 let signature = line.split('{').next().unwrap_or(line).trim();
 let name = signature
 .strip_prefix("fn ")
 .unwrap()
 .split('(')
 .next()
 .unwrap()
 .trim();

 let symbol = CodeSymbol {
 id: format!("{}:{}", path, line_num),
 name: name.to_string(),
 kind: SymbolKind::Function,
 file_path: path.to_string(),
 start_line: line_num,
 end_line: line_num + 10, // 대략적인 범위 추정
 signature: signature.to_string(),
 };

 self.add_symbol(symbol);
 }
 // Struct, impl 등에 대한 패턴 매칭 추가 가능...
 }
 }

 fn add_symbol(&mut self, symbol: CodeSymbol) {
 let idx = self.symbols.len();
 self.symbols.push(symbol);
 self.name_map
 .entry(symbol.name.clone())
 .or_insert_with(Vec::new)
 .push(idx);
 }
}

3. MCP 도구를 위한 검색 인터페이스

이제 MCP 클라이언트가 호출할 수 있는 검색 함수를 만듭니다. 이 함수는 전체 코드가 아닌 signature와 핵심 ID만 반환하도록 하여 토큰을 아낍니다.

impl CodeIndex {
 pub fn search(&self, query: &str) -> Vec<CodeSymbol> {
 self.symbols
 .iter()
 .filter(|s| s.name.to_lowercase().contains(&query.to_lowercase()))
 .cloned()
 .collect()
 }

 // LLM 컨텍스트를 위해 최적화된 포맷으로 변환
 pub fn to_llm_context(&self, results: Vec<CodeSymbol>) -> String {
 results
 .iter()
 .map(|s| format!(
 "File: {}, Line: {}\nSymbol: {}\nDefinition: {}\n",
 s.file_path, s.start_line, s.name, s.signature
 ))
 .collect::<Vec<_>>()
 .join("\n---\n")
 }
}

성능 비교 및 토큰 절약 효과

예를 들어, blog-api-server에서 get_post라는 함수를 찾는다고 가정해 봅시다.

기존 grep 방식: main.rs의 100줄 중 해당 함수가 포함된 20줄을 모두 반환. (주석, 로직 등 포함)
ZeroClaw 인덱서 방식: File: src/main.rs, Line: 45, Symbol: get_post, Definition: async fn get_post(id: i32) -> Result<Post>만 반환.

결과적으로, LLM은 필요한 메타데이터만 전달받으므로 **“이 함수의 내부 구현을 보여줘”**라고 재요청하거나, 메타데이터만으로도 충분한 추론을 수행할 수 있습니다. 불필요한 코드를 읽지 않기 때문에 토큰 사용량이 획기적으로 줄어듭니다.

결론: 에이전트 생태계를 위한 최적화

Semble에서 영감을 받은 이 접근 방식은 단순히 검색 속도를 높이는 것을 넘어, LLM 에이전트와 코드베이스 간의 통신 비용과 효율성을 최적화합니다. 특히 blog-api-server의 로깅 개선이나 모니터링 시스템처럼 대규모 코드베이스를 다루는 환경에서는 필수적입니다.

다음 단계로, 단순 텍스트 매칭을 넘어 **Vector Embedding(벡터 임베딩)**을 결합하여 의미론적 검색(Semantic Search)이 가능하도록 ZeroClaw의 통신 프로토콜을 확장할 예정입니다. 이를 통해 에이전트가 “사용자 인증 관련 로직"을 검색했을 때, auth라는 키워드가 없어도 login, verify, session 등의 함수를 유연하게 찾아낼 수 있게 될 것입니다.

고성능 에이전트 런타임을 구축하신다면, 단순히 파일을 읽는 것에서 벗어나 코드를 ‘이해’하는 인덱서 구축을 고려해 보세요. 토큰 비용 절감과 응답 속도 개선이라는 두 마리 토끼를 잡을 수 있습니다.

참고 자료

Show HN: Semble – Code search for agents that uses 98% fewer tokens than grep
ZeroClaw Architecture Documentation
Rust Tree-sitter Binding Guide

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에 공개되어 있다.

4개의 AI에게 같은 코딩 태스크를 동시에 보내봤다

Fri, 08 May 2026 21:55:39 +0900

같은 버그 수정 태스크를 Claude, ZAI(GLM), OpenAI Codex, Google Gemini에게 동시에 던지면 어떤 일이 벌어질까?

이 질문에서 AgentForge 프로젝트가 시작됐다. 여러 LLM CLI를 NATS JetStream 메시지 큐로 묶어서 같은 태스크를 병렬로 처리하는 시스템을 만들었고, 그 과정에서 예상치 못한 발견들이 있었다. 이번 글은 “설정하면서 뭘 발견했나"에 집중한 비교 실험 기록이다.

시스템의 설계·구현 이야기는 2편에서 다룬다.

테스트한 AI 목록

최종적으로 운영 중인 워커 18개의 구성은 다음과 같다.

계열	모델	비고
Claude Code	claude-sonnet-4-6	메인 개발 워커
Claude Code	claude-sonnet-4-5	이전 세대 비교용
Claude Code	claude-haiku-4-5	경량·고속
Claude Code	claude-opus-4-6	최고 사양
Claude Code	claude-opus-4-5	이전 세대 비교용
ZAI (GLM)	glm-5.1	고사양 티어
ZAI (GLM)	glm-4.7	중간 티어
ZAI (GLM)	glm-4.5-air	경량 티어
OpenAI Codex	gpt-5.5
Codex	gpt-5.4	1M 컨텍스트
Codex	gpt-5.4-mini	400K 컨텍스트
Codex	gpt-5.3-codex	272K 컨텍스트
Google Gemini	gemini-2.5-flash
Gemini	gemini-2.5-pro	고사양
Gemini	gemini-2.5-flash-lite	경량

처음 시작할 때 목록은 훨씬 짧았다. 어떤 모델을 쓸 수 있는지 직접 실험해보면서 늘어났다.

발견 1: Claude 3.x 시리즈는 이미 접근 불가

Claude Code를 오래 써온 사람이라면 Claude 3.7 Sonnet, 3.5 Sonnet, 3.5 Haiku를 떠올릴 수 있다. 그래서 이 모델들도 워커로 추가하려 했다.

claude --model claude-3-7-sonnet-20250219 --print "hello"
# → "may not exist or no access"

세 모델 모두 동일한 오류. Claude 3 시리즈는 2026년 초에 EOL을 맞이했고, Claude Code CLI를 통한 접근이 차단됐다. 현재 Claude Code 구독으로 쓸 수 있는 것은 4.x 계열뿐이다.

결론: Claude 워커는 4.5/4.6 계열로만 구성했다.

발견 2: ChatGPT 계정 Codex는 모델 선택이 제한적이다

OpenAI Codex CLI는 ChatGPT Plus/Pro 계정이나 별도 API 키로 인증한다. ChatGPT 계정 기반일 경우 접근 가능한 모델이 제한된다.

codex --model gpt-5.5-pro "fix the bug"
# → "Model gpt-5.5-pro is not supported with ChatGPT account"

codex --model gpt-5.5 "fix the bug"
# → 정상 작동

ChatGPT 계정으로 사용할 수 있는 모델:

모델	컨텍스트	추론 수준
gpt-5.5	1M / 1M	High
gpt-5.4	1M / 1M	Medium
gpt-5.4-mini	400K / 400K	Medium
gpt-5.3-codex	272K / 400K	Medium

gpt-5.5-pro를 포함한 다른 모델은 모두 “not supported with ChatGPT account” 오류를 반환한다. API 키 방식이라면 더 많은 모델을 쓸 수 있지만, 그건 다른 접근 방식이다.

발견 3: Gemini CLI는 2.5 시리즈만 된다

Gemini CLI(gemini 바이너리)로 여러 모델을 테스트했다.

gemini -p "hello" -m gemini-2.0-flash
# → ModelNotFoundError: models/gemini-2.0-flash is not found

gemini -p "hello" -m gemini-1.5-pro
# → ModelNotFoundError

gemini -p "hello" -m gemini-2.5-flash
# → 정상 작동

현재 계정으로 접근 가능한 Gemini 모델:

gemini-2.5-flash — 기본 추천 모델
gemini-2.5-pro — 고사양
gemini-2.5-flash-lite — 경량

Gemini 2.0 이하 버전은 ModelNotFoundError를 반환한다. 계정 플랜이나 API 키 종류에 따라 다를 수 있지만, Gemini CLI 기준으로는 2.5 시리즈만 안정적으로 동작했다.

발견 4: ZAI는 Claude SDK로 우회할 수 있다

ZAI는 Anthropic API와 호환되는 엔드포인트를 제공하는 서비스다. 덕분에 Claude Code CLI에서 환경변수 두 개만 바꿔서 GLM 모델을 쓸 수 있다.

ANTHROPIC_BASE_URL=https://<ZAI endpoint> \
ANTHROPIC_AUTH_TOKEN=<ZAI_KEY> \
claude --model glm-5.1 --print "fix the bug"

Claude Code가 내부적으로 Anthropic Python SDK를 쓰기 때문에, ANTHROPIC_BASE_URL만 오버라이드하면 동일한 포맷으로 ZAI의 GLM 모델을 호출한다. 별도의 어댑터 코드 없이 기존 claude 백엔드를 그대로 재사용할 수 있다는 점이 흥미로웠다.

사용한 GLM 모델 3종:

glm-5.1 — 고사양 티어
glm-4.7 — 비용·성능 균형점
glm-4.5-air — 경량·고속

4-way Fan-out 비교 테스트

18개 워커 중 대표 4개(Claude Sonnet, GLM-5.1, Codex gpt-5.5, Gemini 2.5 Flash)에 동일한 Go 버그 수정 태스크를 동시에 발행했다.

태스크: "fix the off-by-one error in the binary search function"

응답 시간 (wall clock):

워커	모델	응답 시간
cc-go-dev-01	claude-sonnet-4-6	~8초
cc-zai-high-dev-01	glm-5.1	~12초
codex-py-dev-01	gpt-5.5	~15초
gemini-py-dev-01	gemini-2.5-flash	~10초

응답 시간보다 흥미로운 건 접근 방식의 차이다. Claude는 함수 전체를 리팩토링하는 경향이 있었고, Gemini는 최소한의 수정을 선호했다. Codex는 테스트 코드까지 함께 추가하는 경우가 많았다.

물론 이건 단일 태스크 결과라 통계적 의미는 없다. 벤치마크가 아니라 “실제로 동작하는지 확인"하는 수준의 검증이었다.

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

워커들이 모두 한 서버에 있으면 비교 실험의 의미가 약해진다. 그래서 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커(첫 번째 호스트)에 접근하는 방법은 autossh 터널이다.

[Service]
ExecStart=autossh -N -L 4222:127.0.0.1:4222 broker-host

로컬의 4222 포트를 브로커로 포워딩하면 워커 코드 변경 없이 어느 호스트에서나 nats://127.0.0.1:4222로 접속할 수 있다.

이 방식의 장점: 워커는 브로커가 어디 있는지 알 필요가 없다. 항상 localhost:4222로 연결하면 된다.

운영하면서 가장 당황했던 순간

가장 곤혹스러운 상황은 NATS operator signing key를 분실한 것이었다. NATS JetStream은 NKey 기반 인증을 쓰는데, 신규 워커의 credentials를 발급하려면 operator/account의 signing key(nsc seed)가 필요하다.

nsc add user --account Services --name new-worker
# → "signing key not found"

백업이 없었다. 결국 NATS operator를 통째로 재생성하고, 모든 워커의 credentials를 새 권한 트리로 교체하는 대규모 컷오버를 진행했다. 서비스 다운타임은 약 60초였다.

교훈: NATS operator seed는 생성 즉시 오프라인 백업을 만들어라. 분실하면 재생성 외에 방법이 없다.

정리

이번 실험에서 얻은 실용적인 결론:

Claude 3.x는 EOL - 2026년 기준 Claude Code CLI에서 접근 불가. 4.x만 쓸 것.
Codex ChatGPT 계정은 모델 4종만 - gpt-5.5, 5.4, 5.4-mini, 5.3-codex. Pro 모델은 별도 API 키 필요.
Gemini는 2.5 시리즈만 - CLI 기준 이전 버전 접근 불가.
ZAI는 Claude SDK 환경변수 오버라이드로 통합 가능 - 별도 어댑터 불필요.
NATS NKey는 반드시 백업 - signing key 분실 = 전체 재발급.

다음 편에서는 이 워커들이 어떻게 연결되는지, 시스템 설계와 구현을 다룬다.

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

Wed, 06 May 2026 09:00:48 +0900

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

최근 Hacker News에서 흥미로운 기사를 접했습니다. **[Computer Use is 45x more expensive than structured APIs]**라는 제목의 글입니다. Anthropic의 최신 기능인 ‘Computer Use’는 AI가 컴퓨터 화면을 보고 마우스와 키보드를 조작하여 사용자 대신 작업을 수행할 수 있게 해줍니다. 마치 철권(Tekken) 게임에서 AI가 플레이어를 대신해 콤보를 입력하는 것처럼 매우 매력적입니다.

하지만 이 기능의 구현 비용은 기존의 **Structured Output(JSON 모드 등)**을 사용할 때보다 무려 45배나 높다는 분석이 나왔습니다.

이번 포스트에서는 왜 이런 격차가 발생하는지, 그리고 우리가 개발하는 **Multi-Agent 시스템(예: ZeroClaw)**에서 이 비용 문제를 어떻게 지혜롭게 해결할 수 있을지 현실적인 코드와 함께 분석해 보겠습니다.

1. 비용 격차의 원인 분석

Computer Use (GUI 기반 접근)

‘Computer Use’는 본질적으로 VNC(RDP) 원격 제어와 유사합니다. AI는 매 턴마다 다음을 수행해야 합니다.

화면 캡처: 고해상도 이미지를 다운로드합니다. (토큰 비용 급증)
시각적 처리: 이미지를 이해하기 위해 대규모 Vision 모델을 실행합니다.
좌표 계산: 버튼의 위치를 픽셀 단위로 계산합니다.
액션 실행: 마우스 클릭/키보드 입력을 전송합니다.

이 과정에서 단순한 텍스트 응답 대신 수백만 개의 ‘시각적 토큰’이 소모됩니다.

Structured Output (API 기반 접근)

반면, 우리가 블로그 API 서버나 MCP(Model Context Protocol)를 통해 구성하는 전통적인 방식은 훨씬 효율적입니다.

텍스트 입력: 시스템 상태나 사용자 의도가 텍스트로 전달됩니다.
논리적 추론: LLM이 텍스트를 파싱하여 의사결정을 내립니다.
직접 호출: tool_use 블록을 통해 함수를 직접 실행합니다. (이미지 처리 불필요)

2. 실용적인 해결책: 하이브리드 아키텍처

모든 작업을 Computer Use로 처리하는 것은 낭비입니다. 우리는 ZeroClaw나 MCP 블로그 자동화 프로젝트에서 배운 **‘도구 분리의 원칙’**을 적용해야 합니다.

전략: 도구 사용 우선순위

1순위: Native API (Structured Output)
- 데이터베이스 조회, API 호출, 파일 생성 등 명확한 로직은 항상 함수 호출로 처리.
2순위: Browser Automation (Playwright/Selenium)
- 복잡한 DOM 조작이 필요하나, 백엔드 API가 없는 경우. (이미지보다 HTML 트리를 파싱하는 것이 저렴)
최후의 수단: Computer Use (Vision)
- 캡차가 있거나, 동영상 편집 프로그램처럼 DOM 접근이 불가능한 오래된 레거시 소프트웨어만 대상으로 함.

3. 코드 예제: 비용 최적화된 Agent 구현

Python을 사용하여 LLM이 API 호출(Structured)과 브라우저 제어(Browser)를 선택적으로 사용하도록 만드는 예제를 작성해 보겠습니다. Computer Use는 아직 특정 클라우드 환경에 종속되어 있으므로, 가장 현실적인 대안인 **Playwright(HTML 기반)**와 API 호출을 비교하는 코드를 소개합니다.

시나리오: 블로그 게시글 자동 발행

LLM 에이전트에게 “최신 기술 뉴스를 요약하고 내 블로그에 발행해"라고 요청한다고 가정해 봅시다.

구조적 접근 (Structured Output + API)

import json
from typing import Literal

# 1. 도구 정의 (API 방식)
tools = [
 {
 "type": "function",
 "function": {
 "name": "create_blog_post",
 "description": "블로그에 새 글을 발행합니다. (가장 저렴하고 빠름)",
 "parameters": {
 "type": "object",
 "properties": {
 "title": {"type": "string"},
 "content": {"type": "string"},
 "tags": {"type": "array", "items": {"type": "string"}}
 },
 "required": ["title", "content"]
 }
 }
 },
 {
 "type": "function",
 "function": {
 "name": "search_web_browser",
 "description": "웹 브라우저를 제어하여 정보를 검색합니다. (API가 없을 때 사용)",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string"}
 },
 "required": ["query"]
 }
 }
 }
]

# 2. 에이전트 실행 로직 (시뮬레이션)
def run_agent(user_query: str):
 # 단계 1: LLM에게 도구 사용 요청 (실제로는 OpenAI/Anthropic API 호출)
 # LLM 응답 시뮬레이션: create_blog_post 도구 선택
 llm_response = {
 "tool": "create_blog_post",
 "arguments": {
 "title": "Gemma 4 가속화 기술",
 "content": "구글의 최신 모델 Gemma은 멀티-토큰 예측을 통해...",
 "tags": ["AI", "Google"]
 }
 }

 # 단계 2: 로컬 함수 실행 (Vision 필요 없음)
 if llm_response['tool'] == 'create_blog_post':
 print(f"[API 실행] 블로그 글 발행: {llm_response['arguments']['title']}")
 # 실제로는 여기서 requests.post('https://blog-api.com/posts', ...) 호출
 return {"status": "success", "cost": "0.0001 USD"}

print(run_agent("블로그에 글 써줘"))

이 방식은 텍스트만 주고받으므로 매우 저렴합니다.

비구조적 접근 (Computer Use 시뮬레이션 - 비용 상승)

만약 우리가 블로그 API를 사용하지 않고 Computer Use로 웹 브라우저를 띄워 글을 쓴다고 상상해 보세요.

# Computer Use 방식의 의사코드 (비용 폭발 구간)
def run_computer_use_agent():
 # 1. 화면 캡처 (1024x768 이미지 -> 약 1,100 토큰 소모)
 screenshot = capture_screen()
 print(f"[Vision] 화면 분석 중... (토큰 1,100개 소모)")

 # 2. LLM 추론: "로그인 버튼을 찾아라"
 action = llm_vision_inference(screenshot, prompt="Find the login button")
 # 결과: {"x": 500, "y": 300, "action": "click"}
 print(f"[Action] 마우스 이동 및 클릭: {action}")

 # 3. 다시 화면 캡처 및 입력 필드 분석
 screenshot = capture_screen()
 print(f"[Vision] 입력 필드 분석 중... (토큰 1,100개 소모)")
 
 # ... (반복적인 캡처와 추론)
 return {"status": "success", "cost": "0.05 USD"} 
 # API 방식(0.0001 USD) 대비 약 500배 비용 발생 가능

4. ZeroClaw 및 MCP 아키텍처 적용 가이드

우리가 진행 중인 **ZeroClaw(고성능 Rust 에이전트)**나 Discord MCP 프로젝트에서 이 원칙을 적용하면 다음과 같은 설계가 나옵니다.

MCP (Model Context Protocol) 표준 준수:
- 가능한 모든 자원(파일 시스템, 데이터베이스, 클라우드 리소스)을 MCP Server로 노출시켜 LLM이 Structured JSON으로 제어하게 하십시오.
- 예: Discord 메시지를 보낼 때, 브라우저를 띄우는 것이 아니라 discord_mcp.send_message() 함수를 호출하도록 유도합니다.
Prompt Engineering:
- 시스템 프롬프트에 명확히 선언하십시오.
- “당신은 화면을 보는 것이 아니라 도구를 호출해야 합니다. 사용자의 요청을 처리하기 위해 먼저 available_tools 리스트를 확인하고, 함수 호출이 가능한지 우선 확인하십시오.”
Fallback 메커니즘:
- MCP Server나 API가 죽었을 때만, 혹은 반드시 시각적 확인이 필요할 때만 ‘Computer Use’ 또는 ‘Browser Automation’ 에이전트를 깨우는 2단계 구조를 만드십시오.

5. 결론

AI 에이전트를 개발할 때 ‘Computer Use’는 마치 ‘스위스 군용 칼’과 같습니다. 모든 것을 할 수 있지만, 나사를 하나 조일 때마다 거대한 칼을 꺼내면(화면을 캡처면) 비용이 막대합니다.

우리는 **‘적재적소’**의 도구를 사용해야 합니다. 대부분의 작업은 **Structured Output(API)**으로 해결하고, 정말 어쩔 수 없는 상황에만 Vision/GUI 기능을 사용하는 전략을 취한다면, 45배의 비용 차이를 우리의 이익으로 돌릴 수 있을 것입니다.

앞으로 진행될 ZeroClaw 프로젝트의 통신 프로토콜 설계에서도 이 비용 효율성을 최우선 가이드라인으로 삼겠습니다.

[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가 생성한 콘텐츠를 사람이 검토하고, 시스템이 이상 징후를 감지하면 운영자에게 알리는 구조가 안정적인 운영의 핵심입니다.

멀티모델 AI 에이전트 팀 설계: 조합형 아키텍처와 5팀 계층 구조

Mon, 30 Mar 2026 00:31:36 +0900

개요

블로그 시스템 구축을 위해 14명의 AI 전문가, 5개 팀, 4개 LLM 모델로 구성된 멀티모델 에이전트 팀을 설계했습니다. 핵심은 두 가지입니다.

조합형 에이전트(Composed Agent): 역할 정의와 실행 프로필을 분리해 재사용성 극대화
계층형 브릿지 리더십: 상위팀-하위팀 간 기술 리드의 이중 소속으로 소통 병목 해결

이 글에서는 최종 구조, 모델 배분 전략, 조합형 아키텍처 설계 과정을 공유합니다.

배경: 왜 멀티모델인가

하나의 LLM으로 모든 작업을 처리하면 두 가지 문제가 발생합니다.

비용: Claude Opus 수준의 모델로 14명 전문가를 실행하면 비용이 통제 불가능
적합성: 설계에는 빠른 추론이, 보안 분석에는 깊은 논리가, 구현에는 안정적인 코딩이 필요

그래서 작업 성격에 맞춰 모델을 분배했습니다.

최종 팀 구조

5개 팀, 14명 전문가, 4개 모델로 구성됩니다.

graph TD
 subgraph UPPER["상위팀 — 조정 팀 (steering-team) · consensus"]
 ORC["오케스트레이터
relay:steering-orchestrator"]
 DES["설계자
gemini:gemini-2.5-flash"]
 SEC["보안 검토자
codex:gpt-4o"]
 STL["백엔드 기술 리드
relay:developer-zai"]
 FTL["프론트엔드 기술 리드
relay:developer-zai"]
 DTL["데스크탑 기술 리드
relay:developer-zai"]
 INF["인프라 네트워크
gemini:gemini-2.5-flash"]
 SAD["서버 관리자
relay:developer-zai"]
 end

 subgraph LOWER_BE["백엔드 팀 · leader_decides"]
 BTL["백엔드 기술 리드"]
 BDEV["백엔드 개발자"]
 end

 subgraph LOWER_FE["프론트엔드 팀 · leader_decides"]
 FTL2["프론트엔드 기술 리드"]
 FDEV["프론트엔드 개발자"]
 FUX["UX 디자이너"]
 end

 subgraph LOWER_DT["데스크탑 팀 · leader_decides"]
 DTL2["데스크탑 기술 리드"]
 DDEV["데스크탑 개발자"]
 DUX["UX 디자이너"]
 end

 subgraph LOWER_INFRA["인프라 팀 · leader_decides"]
 SAD2["서버 관리자 (리더)"]
 INET["클라우드 네트워크"]
 DBA["DB 아키텍트"]
 end

 UPPER -.->|bridge| LOWER_BE
 UPPER -.->|bridge| LOWER_FE
 UPPER -.->|bridge| LOWER_DT
 UPPER -.->|bridge| LOWER_INFRA

 BTL --> BDEV
 FTL2 --> FDEV
 FTL2 --> FUX
 DTL2 --> DDEV
 DTL2 --> DUX
 SAD2 --> INET
 SAD2 --> DBA

팀별 상세

팀	유형	의사결정	리더	팀원 수
조정 팀	upper	consensus	오케스트레이터	8명 (브릿지 포함)
백엔드 팀	lower	leader_decides	백엔드 기술 리드	2명
프론트엔드 팀	lower	leader_decides	프론트엔드 기술 리드	3명
데스크탑 팀	lower	leader_decides	데스크탑 기술 리드	3명
인프라 팀	lower	leader_decides	서버 관리자	3명

인프라 팀 분리 결정

초기 설계에서는 DB 아키텍트와 서버 관리자가 백엔드 팀에 포함되어 있었습니다. 하지만 작업 공간(Workspace) 기준으로 분리했습니다.

graph LR
 subgraph 백엔드팀
 B["API 코드 작성
FastAPI, Python
workspace: VS Code / SSH"]
 end

 subgraph 인프라팀
 S["서버 관리
Docker, Ubuntu, Nginx
workspace: SSH 터미널"]
 N["클라우드 네트워크
Cloudflare Dashboard
workspace: 웹 콘솔"]
 D["DB 관리
PostgreSQL, 마이그레이션
workspace: psql / SSH"]
 end

 B -.->|API 배포| S
 B -.->|쿼리 최적화| D

분리 이유: 작업 공간이 다르면 같은 팀에 두는 것보다 분리하는 것이 자연스럽습니다.

모델 배분 전략

pie title 모델별 전문가 수
 "relay:developer-zai (GLM)" : 10
 "gemini:gemini-2.5-flash" : 2
 "codex:gpt-4o" : 1
 "zai:glm-4" : 1

모델	전문가 수	용도	선택 이유
relay:developer-zai	10명	구현, 운영, 리드	비용 효율적, 안정적 코딩
gemini:gemini-2.5-flash	2명	설계, 인프라 네트워크	빠른 응답, 외부 API 호출 용이
codex:gpt-4o	1명	보안 검토	높은 추론 능력, OWASP 지식
zai:glm-4	1명	컨텍스트 압축	무료 티어, 텍스트 요약 특화

10명의 구현 전문가를 GLM(저비용 모델)에 배정하여 전체 비용의 60-70%를 절감했습니다.

조합형 에이전트 아키텍처 (Composed Agent Pattern)

이번 설계의 핵심 혁신은 역할 정의(Expert)와 실행 프로필(Definition)의 분리입니다.

기존 방식의 문제

기존에는 역할과 실행 로직이 결합되어 변경 시 전체 재작성이 필요하고 재사용이 불가능했습니다.

조합형 방식

graph TD
 DEF["Definition
백엔드 개발자"]
 DEF --> BASE["Base: backend-core"]
 DEF --> CAP["Capabilities:
rest-api, crud, auth-jwt"]
 DEF --> PLAT["Platform: fastapi"]
 DEF --> POL["Policy: blog-default"]

 BASE --> |"조합"| RUN["런타임 에이전트"]
 CAP --> |"조합"| RUN
 PLAT --> |"조합"| RUN
 POL --> |"조합"| RUN

모듈 구조

agent-library/
├── definitions/ ← 14개 에이전트 정의
├── modules/
│ ├── base/ ← 6개 기본 모듈
│ ├── capabilities/ ← 15개 역량 모듈
│ ├── platforms/ ← 5개 플랫폼 모듈
│ └── policies/ ← 1개 정책
└── runs/ ← 실행 이력

장점

재사용성: rest-api 역량 모듈은 백엔드 개발자와 기술 리드가 공유
플랫폼 교체: platform: fastapi를 platform: django로 변경하면 즉시 전환
역량 확장: 새 역량 모듈을 추가하고 Definition에 연결만 하면 됨
정책 통일: 모든 에이전트가 동일한 blog-default 정책을 따름

전문가-Definition 매핑

전문가	Definition	Base	Capabilities	Platform
백엔드 개발자	backend-developer	backend-core	rest-api, crud, auth-jwt	fastapi
백엔드 기술 리드	backend-tech-lead	backend-core	rest-api, crud, code-review	fastapi
프론트엔드 개발자	frontend-developer	frontend-core	markdown-renderer, list-filter-sort	nextjs
서버 관리자	server-administrator	server-core	docker-management, nginx-config, postgres-admin	ubuntu
인프라 네트워크	infra-network-admin	infra-core	dns-management, ssl-certificates, rate-limiting	cloudflare
보안 검토자	security-auditor	specialist-core	security-audit	fastapi
컨텍스트 압축	context-compressor	specialist-core	context-compression	markdown

TLS 인증서 전략: Cloudflare Origin CA

프로덕션 환경의 TLS 인증서로 Let’s Encrypt 대신 Cloudflare Origin CA를 선택했습니다.

sequenceDiagram
 participant Client as 방문자
 participant CF as Cloudflare (Proxy)
 participant Nginx as Nginx (Origin)
 participant API as FastAPI

 Client->>CF: HTTPS 요청
 CF->>CF: Cloudflare 관리 인증서로 종료
 CF->>Nginx: Origin CA 인증서로 암호화
 Nginx->>API: HTTP (로컬)
 API-->>Nginx: 응답
 Nginx-->>CF: Origin CA로 암호화
 CF-->>Client: 응답

항목	Let’s Encrypt	Cloudflare Origin CA
유효 기간	90일 (갱신 필요)	15년 (갱신 불필요)
발급 방식	ACME 자동화 필요	Dashboard에서 수동 발급
복잡도	certbot 설정	인증서 파일 복사만

프로덕션 아키텍처:

Oracle Cloud ARM (4 OCPU, 24GB)
├── PostgreSQL (호스트 직접 설치)
├── Docker Compose
│ ├── blog-api (FastAPI)
│ ├── blog-frontend (Next.js standalone)
│ ├── MinIO (S3 호환 스토리지)
│ └── Nginx (Cloudflare Origin CA)
└── Cloudflare Proxy (Full Strict SSL)

Relay 플러그인: 에이전트 호출 메커니즘

팀 구조는 Relay 플러그인을 통해 Claude Code에서 실행됩니다.

sequenceDiagram
 participant User as 사용자
 participant Claude as Claude Code
 participant Plugin as Relay Plugin
 participant MCP as MCP 서버
 participant LLM as 외부 LLM

 User->>Claude: /relay:invoke-agent
 Claude->>Plugin: 전문가 slug로 정의 로드
 Plugin->>Plugin: Definition 조합 (base + capabilities + platform + policy)
 Plugin->>Plugin: backed_by 확인

 alt relay:developer-zai
 Plugin->>Claude: 내부 에이전트 실행
 else gemini:*
 Plugin->>MCP: gemini_mcp 서버 호출
 MCP->>LLM: Gemini API
 LLM-->>MCP: 응답
 MCP-->>Plugin: 결과
 else codex:*
 Plugin->>MCP: codex_mcp 서버 호출
 MCP->>LLM: OpenAI API
 LLM-->>MCP: 응답
 MCP-->>Plugin: 결과
 end

 Plugin-->>Claude: 최종 결과
 Claude-->>User: 응답

backed_by 네임스페이스

네임스페이스	MCP 서버	용도
`relay:developer-zai`	내부 에이전트	구현, 운영 (저비용)
`relay:steering-orchestrator`	내부 에이전트	조율, 최종 결정
`gemini:gemini-2.5-flash`	gemini_mcp	설계, 외부 API
`codex:gpt-4o`	codex_mcp	보안 분석
`zai:glm-4`	zai_mcp	컨텍스트 압축

설계 결정 이력

결정	대안	선택 이유
인프라 팀 분리	백엔드 팀에 포함	작업 공간이 다름 (SSH vs IDE)
Cloudflare Origin CA	Let’s Encrypt	15년 유효, 갱신 불필요
PostgreSQL 호스트 설치	Docker 컨테이너	단일 서버에서 메모리 효율 우선
조합형 에이전트	단일 정의 에이전트	모듈 재사용성, 플랫폼 교체 용이
GLM 다수 배정	Claude 다수 배정	60-70% 비용 절감

회고: 설계하며 배운 것

1. “완벽한 구조"보다 “실행 가능한 구조”

팀 구조, 모델 배정, 인프라 설정을 완벽하게 설계하려다 보면 시작조차 못 합니다.

2. 작업 공간이 곧 팀 경계

코드를 작성하는 사람과 서버를 관리하는 사람은 물리적 작업 환경이 다르고, 그것이 자연스러운 팀 경계가 됩니다.

3. 조합형 아키텍처의 가치

14명의 전문가, 5개 팀, 4개 모델이 얽히는 환경에서는 모듈 분리가 필수적입니다.

4. 비용은 설계 단계에서 결정된다

“이 작업에 꼭 고비용 모델이 필요한가?“를 매번 물어보면 자연스럽게 비용이 최적화됩니다.

다음 단계

Phase 1 구현 착수: DB, Auth, Post/Category CRUD, Docker
팀 운영 경험 공유: 실제 실행 중 겪은 문제와 해결 과정
성능 모니터링: 모델별 응답 시간, 비용 대비 품질 분석

이 글은 Claude Code + Relay 플러그인을 활용한 AI 에이전트 팀 구성 경험을 정리한 것입니다.

[blog-api-server] LLM 설정 개선 및 배포

Tue, 03 Mar 2026 13:01:48 +0900

개요

blog-api-server 프로젝트의 LLM 설정을 개선하고 서버에 배포했다.

LLM 설정 개선

기존 문제

여러 개의 API Key 환경 변수 (ZAI_API_KEY, ANTHROPIC_API_KEY)
Provider 분기 로직이 복잡함
모델 설정이 분산되어 있음

변경 사항

환경 변수 단순화

# 기존
ZAI_API_KEY=xxx
ANTHROPIC_API_KEY=xxx
ZAI_MODEL=gpt-4o-mini
LLM=ZAI

# 변경 후
LLM=ZAI # Provider (ZAI, OPENAI, ANTHROPIC)
LLM_API_KEY=xxx # 단일 API Key
LLM_MODEL=glm-4.7 # 기본 모델
LLM_TIMEOUT=120 # 타임아웃 (초)

BASE_URL 자동 설정

LLM_BASE_URLS = {
 "ZAI": "https://api.z.ai/api/coding/paas/v4",
 "OPENAI": "https://api.openai.com/v1",
 "ANTHROPIC": "https://api.anthropic.com/v1"
}

코드 구조 개선

class Translator:
 """LLM 기반 번역기"""
 
 def __init__(self):
 self.api_key = LLM_API_KEY
 self.base_url = LLM_BASE_URL # 자동 선택
 self.model = LLM_MODEL
 self.timeout = LLM_TIMEOUT

모델 설정

기본 모델

glm-4.7 (기본값)
max_tokens: 8192

지원 모델

모델	max_tokens
glm-4	8192
glm-4.7	8192
gpt-4o-mini	4096
gpt-4o	8192
claude-3-5-haiku	8192

팀 구성

blog-api-server 개발 팀을 구성했다.

역할	이름	담당
팀 리드	team-lead	전체 관리
개발자	developer	코드 작성, 기능 구현
배포 관리자	deployer	서버 배포, 인프라
모니터링	monitor	로그 분석, 성능 모니터링

서버 배포

배포 대상

서버: blog.fcoinfup.com (130.162.133.47)
경로: /var/www/blog-api

배포 내용

translator.py 업데이트
systemd 서비스 재시작

배포 결과

● blog-api.service - Blog API Server
 Active: active (running)

다음 단계

번역 API 테스트
모니터링 대시보드 구축
로그 파일 롤오버 정책 적용

영어 버전: English Version

[ZeroClaw] 소개 - 고성능 Rust 에이전트 런타임

Fri, 27 Feb 2026 19:30:00 +0900

ZeroClaw 소개: 고성능 Rust 에이전트 런타임

ZeroClaw는 Rust로 구축된 고성능 자율 에이전트 런타임으로, AI 기반 애플리케이션에서 속도, 효율성, 안정성이 필요한 개발자를 위해 설계되었습니다.

핵심 기능

성능 우선

Rust 네이티브: 가능한 한 할당 없음
Tokio 기반 Async/await: 효율적인 동시 작업
스트리밍 지원: 실시간 응답 스트리밍

확장성

Trait + Factory 아키텍처: Trait 구현으로 확장
25개 이상의 내장 도구: Shell, 파일 작업, 메모리, 브라우저, HTTP
플러그인 친화적: 코어 수정 없이 Provider, Channel, Tool 추가 가능

기본 보안

샌드박스 지원: Firejail, Bubblewrap, Landlock, Docker
페어링 프로토콜: 6자리 CSPRNG 코드
비밀 저장소: ChaCha20-Poly1305 AEAD 암호화

멀티 플랫폼

20개 이상의 메시징 채널: Telegram, Discord, Slack, WhatsApp, Signal, Matrix
13개 이상의 LLM Provider: OpenAI, Anthropic, Gemini, Ollama, Bedrock, OpenRouter

빠른 시작

cargo install zeroclaw
zeroclaw config init
zeroclaw run --channel telegram

아키텍처

ZeroClaw Agent
├── Providers (OpenAI, Anthropic, Gemini, Ollama)
├── Channels (Telegram, Discord, Slack, WhatsApp)
├── Tools (Shell, File, Memory, Browser, HTTP)
├── Memory (SQLite, PostgreSQL, Markdown)
└── Security (Policy, Sandbox, Secret Store)

로드맵

1단계: 향상된 멀티 에이전트 (진행 중)
2단계: 더 많은 통합
3단계: 엔터프라이즈 기능

영어 버전: English Version

[LLM] 프롬프트 잘 작성하는 방법

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

들어가며

LLM(Large Language Model)을 효과적으로 활용하기 위해서는 좋은 프롬프트를 작성하는 것이 필수적입니다. 이 글에서는 프롬프트 엔지니어링의 핵심 원칙과 실전 패턴을 정리합니다.

좋은 프롬프트의 핵심 원칙

1. 명확성 (Clarity)

모호한 표현을 피하고 구체적으로 작성하세요.

나쁜 예:

좋은 코드를 작성해줘

좋은 예:

Python으로 이진 탐색 트리를 구현해줘.
insert, search, delete 메서드를 포함하고,
시간 복잡도는 O(log n)이어야 해.

2. 컨텍스트 제공 (Context)

LLM이 작업을 이해하는 데 필요한 배경 정보를 제공하세요.

나는 React 초보자야.
useState와 useEffect의 차이점을 예제 코드와 함께 설명해줘.

3. 역할 부여 (Role Playing)

특정 전문가의 관점에서 응답하도록 설정하세요.

당신은 10년 경력의 시니어 백엔드 개발자입니다.
마이크로서비스 아키텍처의 장단점을 설명해주세요.

4. 출력 형식 지정 (Output Format)

원하는 응답 형태를 명시하세요.

다음 내용을 마크다운 표로 정리해줘:
- 언어별 특징
- 장단점
- 사용 사례

프롬프트 패턴

Chain of Thought (사고 과정)

복잡한 문제는 단계별로 생각하도록 유도하세요.

이 문제를 단계별로 생각해보자:
1. 먼저 문제를 분석하고
2. 해결 방법을 고민한 후
3. 최종 답변을 작성해

Few-Shot Learning

예시를 제공하여 원하는 형태를 학습시키세요.

다음 형식으로 요약해줘:

입력: "오늘 날씨가 좋다"
출력: 긍정, 날씨

입력: "회의가 너무 길었다"
출력: 부정, 업무

입력: "새로운 프로젝트를 시작했다"
출력: ?

구조화된 프롬프트

복잡한 작업은 섹션으로 나누어 작성하세요.

## 목표
사용자 인증 API를 설계한다

## 요구사항
- JWT 토큰 사용
- Refresh token 로테이션
- Rate limiting 적용

## 출력
1. API 엔드포인트 명세
2. 시퀀스 다이어그램
3. 보안 고려사항

자주 하는 실수

실수	문제점	해결책
너무 긴 프롬프트	핵심이 흐려짐	핵심만 간결하게
모호한 지시	예상과 다른 결과	구체적인 예시 제공
컨텍스트 누락	부정확한 답변	배경 정보 추가
형식 미지정	가독성 저하	출력 형식 명시

실전 체크리스트

프롬프트 작성 전 확인하세요:

목표가 명확한가?
필요한 컨텍스트를 포함했는가?
출력 형식을 지정했는가?
제약사항을 명시했는가?
예시가 도움이 될 것인가?

마무리

좋은 프롬프트는 명확하고, 구체적이며, 필요한 컨텍스트를 제공합니다. 연습을 통해 프롬프트 작성 실력을 향상시키세요.

참고 자료

영어 버전: English Version