로컬 AI 인프라 노트 (4/15) — 에이전트 간 메시지 허브 구축

-

fire-and-forget 웹훅과 ACK 기반 메시지를 분리 설계한 에이전트 통신 아키텍처

핵심 요약

  • 에이전트가 여러 개면 통신 구조가 필요하다 — 없으면 사일로(silo)가 된다
  • 인사이트 전달(fire-and-forget)과 작업 요청(ACK 필요)은 설계가 달라야 한다
  • 웹훅 경로와 메시지 경로를 분리하면 단순한 알림과 추적이 필요한 작업을 동시에 처리할 수 있다

배경

에이전트가 하나일 때는 통신이 필요 없다. 에이전트가 작업하고, 결과를 사용자에게 보여주면 끝이다.

문제는 에이전트가 여러 개일 때 시작된다. 주식 분석 에이전트가 발견한 인사이트를 글 작성 에이전트가 써야 할 때. 생활 정리 에이전트의 투자 전략이 주식 에이전트의 포트폴리오 방향에 영향을 줄 때. 이런 연결이 사람을 통해서만 이루어진다면 병목이 된다.

에이전트가 서로 직접 메시지를 주고받을 수 있는 허브가 필요하다. 그런데 모든 메시지가 같은 성격은 아니다. "참고해" 수준의 전달과 "이 작업 해줘, 끝나면 알려줘" 수준의 요청은 다른 메커니즘이 필요하다.

본문

1. 두 가지 통신 경로를 나눈 이유

단일 API로 모든 통신을 처리하는 설계는 빠르게 복잡성 폭발로 이어진다. 단순한 인사이트 전달에도 ACK를 대기하게 되고, 중요한 작업 요청이 인사이트 알림에 묻히게 된다.

해결책은 경로 분리다:

경로 용도 패턴 추적
Webhooks 인사이트/알림 전달 fire-and-forget 없음
Agent Messages 작업 요청/응답 ACK 필수 전체

Webhooks (fire-and-forget): "이런 걸 발견했어"라고 던지고 끝. 받는 쪽이 읽든 안 읽든 보내는 쪽은 신경 쓰지 않는다. 인사이트, 모니터링 데이터, 상태 업데이트 같은 것들이 여기를 탄다.

Agent Messages (ACK 기반): "이 작업 해줘"라고 보내고, 받는 쪽이 확인했다는 응답(ACK)을 돌려줘야 한다. 작업 요청, 데이터 전달 후 처리 확인, 에이전트 간 협업 작업이 여기를 탄다.

2. Webhooks 경로 — 가볍고 빠른 전달

Webhooks의 API 패턴은 단순하다:

POST /api/webhooks
{
  "content": "전달할 내용",
  "tags": ["태그1", "태그2"],
  "source": "보내는-에이전트"
}

응답을 기다리지 않는다. HTTP 200이 오면 전달 완료. 받는 쪽에서 언제 읽을지, 어떻게 처리할지는 보내는 쪽의 관심사가 아니다.

이 경로를 쓰는 상황: - 리서치 에이전트가 발견한 데이터를 허브에 기록 - 모니터링 에이전트가 서비스 상태를 보고 - 한 에이전트가 발견한 패턴을 다른 에이전트들이 참고할 수 있도록 공유

오버헤드가 거의 없어서 에이전트가 자유롭게 인사이트를 공유할 수 있다. "혹시 쓸모 있을까?" 싶은 정보도 부담 없이 보낼 수 있는 구조다.

3. Agent Messages 경로 — 추적과 확인이 필요한 통신

작업을 요청하는 메시지는 다른 수준의 안정성이 필요하다.

POST /api/agent-messages
{
  "fromAgent": "보내는 에이전트",
  "toAgent": "받는 에이전트",
  "messageType": "task_request",
  "intent": "작업 의도 설명",
  "body": {
    "text": "구체적인 요청 내용"
  },
  "dedupeKey": "고유키"
}

이 경로의 핵심 메커니즘:

인박스 패턴: 각 에이전트는 자신의 인박스를 가진다.

GET /api/agent-inbox/{에이전트이름}

에이전트가 활성화되면 자신의 인박스를 확인하고, 대기 중인 메시지를 처리한다.

ACK(확인응답): 메시지를 받으면 반드시 ACK를 보내야 한다.

POST /api/agent-messages/{messageId}/ack
{
  "status": "acked",
  "response": { ... }
}

ACK가 오지 않으면 메시지가 처리되지 않은 것이다. 재전송 로직이나 타임아웃 처리가 가능해진다.

중복 방지: dedupeKey로 같은 메시지가 중복 처리되는 것을 방지한다. 네트워크 문제로 재전송되더라도 같은 키의 메시지는 한 번만 처리된다.

4. 에이전트 이름 규칙

에이전트 이름에는 규칙이 필요하다. API가 자동으로 정규화(normalize)하기는 하지만, 원칙적으로 공백을 포함한 한글 이름을 사용한다.

  • 올바른 예: "글 작성 디렉터", "주식 정보 관리 디렉터"
  • 피할 예: "글-작성-디렉터", "write_score_agent"

이유는 단순하다. 사용자가 에이전트를 부르는 방식과 시스템 내부의 이름이 일치해야 혼란이 없다. 기술적 편의를 위해 하이픈이나 언더스코어를 쓰면 "어떤 이름이 맞지?" 하는 상황이 반복된다.

5. 실제 사례: 에이전트 간 블로그 소재 전달

이 구조가 작동하는 흐름을 하나 살펴보자.

  1. 생활 정리 에이전트가 사용자의 경험/결정을 정리하면서 "이건 블로그 소재가 될 수 있겠다"고 판단
  2. 웹훅으로 허브에 인사이트 전달: POST /api/webhooks — 태그에 "블로그소재" 포함
  3. 글 작성 에이전트가 세션 시작 시 허브에서 관련 인사이트를 확인
  4. 소재가 유효하다고 판단되면, 메시지 경로로 작업 시작: 리서치 → 소스 파일 작성 → 검증 → 블로그 글 작성
  5. 블로그 글 초안이 완성되면 사용자에게 컨펌 요청

핵심은 1~2단계가 웹훅(fire-and-forget)이고 나머지가 에이전트 자체의 파이프라인이라는 점이다. 인사이트 전달은 가볍게, 실제 작업은 각 에이전트가 자율적으로.

생활 정리 에이전트가 글 작성 에이전트에게 "이 주제로 글을 써줘"라고 직접 요청할 경우에는 메시지 경로(POST /api/agent-messages)를 사용한다. 작업 완료 후 ACK로 결과를 돌려준다.

설계 함정과 대응 패턴

단일 경로 설계의 문제: 모든 통신을 하나의 API로 처리하면 인사이트 알림에도 ACK가 요구되어 에이전트 처리 부담이 늘어난다. 중요한 작업 요청이 알림 사이에 묻히는 우선순위 역전 현상도 발생한다. 경로를 분리하면 각 통신 유형이 필요한 만큼의 오버헤드만 부담한다.

이름 불일치 문제: 에이전트 이름을 시스템 내부와 외부에서 다르게 쓰면 인박스 조회 시 매칭 실패가 발생한다. API 레벨에서 정규화를 적용하되, 사용자 가시 이름과 내부 식별자를 동일하게 유지하는 것이 원칙이다.

dedupeKey 누락의 위험: 네트워크 타임아웃으로 메시지가 재전송될 때 dedupeKey가 없으면 같은 작업이 중복 실행된다. 모든 작업 요청 메시지에 결정론적(deterministic) 고유 키를 포함하는 것이 필수다. 키 생성 전략: {fromAgent}:{toAgent}:{intent}:{timestamp} 패턴으로 중복 가능성을 최소화한다.

마무리

에이전트가 하나일 때는 통신 구조가 필요 없다. 두 개가 되면 "있으면 좋겠다" 수준이다. 세 개 이상이 되면 없으면 안 된다.

핵심 설계 원칙은 단순하다: 가벼운 전달은 웹훅, 추적이 필요한 작업은 메시지. 이 구분 하나로 통신 구조의 복잡성이 관리 가능한 수준으로 내려온다.

에이전트 간 통신에서 어려운 것은 기술 구현이 아니다. "어떤 통신에 어떤 수준의 안정성이 필요한가"를 판단하는 것이 설계의 본질이다. 그 판단을 구조로 굳히는 것이 메시지 허브의 역할이다.

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »