가루더스트에서 이벤트가 발생했습니다.

Source: Dev.to

Garudust의 에이전트 코어는 단일 기본 원시 함수인 agent.run(task)를 노출합니다. 모든 진입점—채팅 메시지, 크론 작업, 웹훅 호출—은 결국 이 동일한 호출로 해결됩니다. 이는 HTTP POST를 보낼 수 있는 외부 시스템이라면 모두 이벤트 트리거 역할을 할 수 있음을 의미합니다.
이 문서는 현재 동작 방식, 프로덕션에서 검증된 패턴, 그리고 구체적인 사용 사례를 다룹니다.

Garudust를 웹훅 플랫폼과 함께 설정하면 Axum HTTP 서버가 시작되고, 사용자가 지정한 경로에 POST 엔드포인트가 등록됩니다. 들어오는 요청은 다음과 같습니다:

{
  "text": "A new billing invoice has arrived from Acme Corp for $4,200.",
  "callback_url": "https://your-system.example.com/garudust/reply",
  "user_id": "billing-watcher",
  "session_key": "billing-acme-corp"
}

Garudust는 이를 InboundMessage로 감싸 GatewayHandler를 통해 전달하고, agent.run()을 실행합니다. 에이전트가 작업을 마치면 callback_url에 응답을 POST합니다:

{
  "text": "Invoice from Acme Corp for $4,200 — categorised as SaaS/Infrastructure. Flagged for approval above $3,000 threshold. Draft approval request sent to #finance."
}

POST에 대한 HTTP 응답은 즉시 202 Accepted이며, 에이전트는 비동기적으로 실행됩니다.

Garudust는 모든 인바운드 요청에 대해 HMAC‑SHA256 서명을 검증합니다. 설정 파일에 공유 비밀을 지정하고, 모든 아웃바운드 POST에 다음 헤더를 포함해 서명합니다:

X-Hub-Signature-256: sha256=<signature>

유효하지 않은 서명의 요청은 401로 거부됩니다. 사설 IP(192.168.x.x, 10.x.x.x, localhost) 콜백 URL도 네트워크 가드에 의해 차단되며, 에이전트가 내부 인프라로 호출되는 것을 방지합니다.

관심사의 분리는 명확합니다:

External system               Garudust
─────────────────             ──────────────────────────
Event source (email,          →     Webhook adapter
  calendar, DB, queue)            (필터/매치 로직)
Filter / match logic        →     Your code (pre-POST)
Task description            →     agent.run(task)
Result handling             →     Your callback_url handler

당신의 시스템은 필터링을 담당하고, Garudust는 에이전트 실행을 담당합니다. 서로의 내부 구조를 알 필요가 없습니다.

예시 1 – 이메일 기반 청구서 처리

이메일 처리 서비스가 알려진 청구 발신자들의 메일함을 감시합니다. 일치하는 메일을 발견하면 제목, 발신자, 금액을 추출하고 Garudust에 트리거합니다:

{
  "text": "New invoice received: Stripe — $1,840 for May 2026. Attach to this month's expense report and notify the finance channel if it exceeds the $1,500 alert threshold.",
  "callback_url": "https://your-ops.example.com/hooks/garudust",
  "session_key": "finance-inbox"
}

에이전트는 도구를 이용해 비용 보고서 파일을 읽고, 라인 아이템을 추가한 뒤 Slack에 게시합니다. 이메일 서비스는 발신자 매칭과 트리거만 하면 되며, 비용 보고서나 Slack에 대한 지식은 필요하지 않습니다.

예시 2 – GitHub PR 리뷰 자동화

GitHub Actions 워크플로가 main 브랜치에 PR이 열리면 Garudust를 호출합니다. 워크플로는 GitHub 컨텍스트에서 페이로드를 구성합니다:

{
  "text": "PR #214 opened by @alice: 'feat: add OAuth2 PKCE flow'. Changed files: src/auth/oauth.rs, src/auth/pkce.rs, tests/auth_integration.rs. Diff summary attached. Review for security issues in the auth flow and post a summary comment.",
  "callback_url": "https://your-ci.example.com/garudust/pr-review",
  "session_key": "pr-214"
}

GitHub 웹훅이 워크플로를 실행하고, 워크플로가 작업 텍스트를 만든 뒤 Garudust가 리뷰를 수행합니다. session_key가 PR 번호와 연결돼 있어, 이후 커밋이나 재리뷰 요청도 같은 대화 스레드에서 이어집니다.

예시 3 – 모니터링 기반 이상 탐지

모니터링 잡이 일정에 따라 데이터베이스를 조회하고 집계 지표를 확인합니다. 지표가 임계값을 초과하면 정적 알림 대신 Garudust를 호출합니다:

{
  "text": "Anomaly detected: orders table insert rate dropped 94% in the last 10 minutes (baseline 340/min, current 19/min). Last successful insert: 09:42 UTC. Investigate root cause and summarise for on-call.",
  "callback_url": "https://ops.example.com/garudust/incidents",
  "session_key": "incident-2026-05-23-orders"
}

에이전트는 터미널이나 데이터베이스 도구를 사용해 추가 쿼리를 실행하고, 최근 배포 상황을 확인한 뒤 구조화된 사고 요약을 생성합니다. 모니터링 잡은 단순히 임계값 초과만 감지하면 됩니다.

예시 4 – 캘린더 초대 기반 회의 준비

통합 레이어가 Google Calendar를 폴링하거나 푸시 알림을 받아, 조직 도메인과 일치하지 않는 참석자가 포함된 이벤트가 생성되면 Garudust를 트리거합니다:

{
  "text": "New calendar event: 'Q3 partnership discussion' on 2026-06-04 14:00 UTC. External attendees: jane@partner.com, bob@partner.com. Prepare a one-page briefing on Partner Corp using the CRM notes and recent email thread.",
  "callback_url": "https://your-system.example.com/garudust/calendar",
  "session_key": "meeting-prep-2026-06-04"
}

캘린더 통합은 “외부 참석자” 필터 로직을 담당하고, Garudust는 브리핑 작성을 담당합니다.

예시 5 – 작업 큐 기반 고객 지원

백그라운드 워커가 작업 큐(SQS, Redis, RabbitMQ)를 소모하고 각 아이템을 Garudust에 전달합니다. 이는 양이 가변적이고 에이전트가 각 아이템을 자체 속도로 처리하도록 하고 싶을 때 유용합니다:

{
  "text": "Customer support ticket #8821 (priority: high): User reports that export to CSV silently truncates rows above 10,000. Reproduce the scenario, identify the code path responsible, and draft a fix description for the engineering team.",
  "callback_url": "https://support.example.com/garudust/tickets",
  "session_key": "ticket-8821"
}

큐 워커는 아이템을 꺼내어 작업 텍스트를 포맷하고 웹훅을 호출합니다. 여러 티켓이 동시에 에이전트 세션으로 실행됩니다.

session_key의 역할

session_key는 일회성 작업을 넘어서는 이벤트 트리거를 가능하게 합니다. 키를 고정하면 해당 키를 가진 모든 웹훅 호출이 동일한 대화 기록을 공유합니다. 예를 들어:

• 커밋 1에 대한 PR 리뷰 트리거와 커밋 2에 대한 재리뷰 트리거가 동일한 대화가 됩니다. 에이전트는 이전에 했던 말을 기억합니다.
• 사고 트리거와 현장 엔지니어가 “현재 상황은?”이라고 물어보는 후속 호출이 컨텍스트를 공유합니다.
• 청구 세션이 여러 트리거에 걸쳐 한 달 전체 청구서를 누적한 뒤 월간 요약을 생성합니다.

완전한 격리를 원한다면 session_key를 생략하세요. Garudust는 callback_url을 기준으로 세션을 키 지정해, 각 고유 콜백 대상마다 새로운 컨텍스트를 제공합니다.

푸시 vs 풀

웹훅 어댑터는 푸시 대상입니다—외부 시스템이 호출을 시작해야 합니다. Garudust가 자체적으로 소스(메일함 확인, API 폴링, 파일 감시)에서 풀하도록 하려면, 폴링 크론 잡을 만들거나 아직 존재하지 않는 “watch/filter” 원시 기능이 필요합니다.

실제로 푸시 기반(예: GitHub 웹훅, 큐 워커, 캘린더 푸시 알림, 이메일 라우팅 서비스)인 경우 현재 아키텍처가 충분하고, 관심사의 분리도 깔끔합니다.