단 하나의 SQL 인터페이스로 GitHub, 캘린더, 수면 데이터를 조회하는 AI 에이전트 구축 방법

Coral에 대한 실무 가이드 — 에이전트에게 모든 API에 대한 단일 쿼리 레이어를 제공하는 로컬 우선 (local-first) SQL 런타임

저는 "최근에 왜 생산성이 떨어질까?"와 같은 질문에 답할 수 있는 에이전트를 만드는 데 일주일의 대부분을 보냈습니다. 아이디어는 간단했습니다. GitHub, Google Calendar, 그리고 수면 추적 데이터에서 정보를 가져와 모든 것을 교차 참조하고 AI의 답변을 얻는 것이었습니다.

어려운 점은 데이터 배관 (data plumbing) 작업이었습니다. 모든 소스는 각기 다른 인증 (auth), 페이지네이션 (pagination), 그리고 고유한 특성을 가지고 있습니다. GitHub와 Calendar가 동일한 스크립트와 통신하도록 만들었을 때, 저는 실제 에이전트 로직보다 더 많은 글루 코드 (glue code)를 작성한 상태였습니다.

그러다 Coral을 발견했습니다.

이 포스트에서는 Coral이 무엇인지, 왜 에이전트 개발에 중요한지, 그리고 이를 사용하여 처음부터 작동하는 AI 에이전트를 어떻게 구축하는지 살펴봅니다.

현재 에이전트의 데이터 접근 방식이 가진 문제점

대부분의 에이전트 워크플로우 (workflow)는 다음과 같습니다:

에이전트 (Agent) → 도구 A (Tool A) → API A
에이전트 (Agent) → 도구 B (Tool B) → API B
에이전트 (Agent) → 도구 C (Tool C) → API C

각 도구 호출은 격리되어 있습니다. 에이전트는 세 개의 서로 다른 스키마 (schema)를 추론해야 하고, 세 가지의 서로 다른 인증 (auth) 흐름을 처리해야 하며, 그 다음 결과들을 머릿속으로 조인 (join)하려고 시도해야 합니다. 이는 다음과 같은 문제를 야기합니다:

• 너무 많은 LLM 라운드 트립 (round-trips) — 각 도구 호출은 그 자체로 별도의 컨텍스트 윈도우 (context window) 교환입니다.
• 반복되는 글루 코드 (glue code) — 페이지네이션 (pagination), 재시도 로직 (retry logic), 속도 제한 (rate limiting) 등을 소스마다 개별적으로 구현해야 합니다.
• 부족한 소스 간 추론 (cross-source reasoning) — LLM은 결과를 통합된 데이터셋이 아니라 한 번에 하나씩 보게 됩니다.
• 높은 토큰 비용 (token costs) — 가공되지 않은 API 응답은 정제된 결과 집합이 아닌 장황한 JSON 형태입니다.

Coral 팀의 벤치마크 (benchmark)는 이를 실제로 수치화했습니다. 82개의 실제 작업 전반에 걸쳐, Claude는 직접적인 제공업체 MCP를 사용할 때보다 Coral을 사용할 때 20% 더 정확하고 2배 더 비용 효율적이었습니다. 복잡한 멀티 홉 (multi-hop) 쿼리(코딩 에이전트가 실제로 수행하는 작업)의 경우, 정확도는 31% 상승했고 비용은 3.4배 감소했습니다.

그 이유는 아키텍처 (architectural)에 있습니다. Coral은 에이전트에게 모든 것에 대한 **단 하나의 SQL 인터페이스 (SQL interface)**를 제공합니다.

Coral이란 무엇인가?

Coral은 에이전트와 데이터 소스 사이에 위치하는 **로컬 우선 SQL 런타임 (local-first SQL runtime)**입니다. 사용자가 SQL을 작성하면, Coral이 이를 API 호출로 변환하며(인증, 페이지네이션, 재시도 처리 포함), 깔끔한 테이블 형태의 행(row)을 반환합니다.

사용자 에이전트 → SQL → Coral → GitHub API
                         → Google Calendar API  
                         → 로컬 JSONL 파일
...

주요 특징:

로컬 우선 (Local-first). 모든 것이 사용자의 기기에서 실행됩니다. 인증 정보(Credentials)는 로컬에 저장되며 절대 외부로 유출되지 않습니다. Coral은 읽기 계층(read layer)입니다. 사용자를 대신하여 API 호출을 수행하지만, 데이터를 어디로도 전송하지 않습니다.

SQL 스키마로서의 소스 (Sources as SQL schemas). GitHub을 연결하면 github 스키마로 나타납니다. 데이터베이스 테이블처럼 github.commits, github.issues, github.pulls를 쿼리할 수 있습니다. 모든 소스에 대해 동일한 패턴이 적용됩니다.

소스 간 조인 (Joins across sources). 모든 소스가 SQL 테이블처럼 보이기 때문에, 소스 간에 JOIN을 수행할 수 있습니다. Coral은 각 측면의 데이터를 가져온 후 로컬에서 조인을 실행합니다. 이 단일 쿼리는 세 번의 별도 도구 호출(tool calls)과 이를 결합하는 데 필요한 LLM의 추론 과정을 대체합니다.

MCP 서버 내장 (MCP server built-in). Coral에는 MCP 서버가 포함되어 있어, 단 한 번의 명령으로 Claude Code, Cursor 또는 모든 MCP 호환 에이전트에 직접 연결할 수 있습니다.

Coral 설치하기

macOS:

brew install withcoral/tap/coral

Linux:

curl -fsSL https://withcoral.com/install.sh | sh

Windows (10/11 x86_64):
최신 GitHub 릴리스에서 coral-x86_64-pc-windows-msvc.zip을 다운로드하여 압축을 풀고, coral.exe를 PATH에 추가하세요.

설치 확인:

coral --version

첫 번째 소스 연결하기

Coral은 GitHub, Google Calendar, Linear, Sentry, Datadog, Stripe, Slack 등을 위한 번들 소스를 제공합니다. 사용 가능한 모든 항목을 확인하려면 다음을 입력하세요:

coral source discover

GitHub을 연결해 보겠습니다. repo 및 read:user 권한(scope)이 있는 개인 액세스 토큰 (Personal Access Token)이 필요합니다:

coral source add --interactive github
# Coral이 다음과 같이 요청합니다: Enter your GitHub PAT

연결이 완료되면, 정상적으로 작동하는지 확인하세요:

coral sql "SELECT schema_name, table_name FROM coral.tables WHERE schema_name = 'github'"

github.commits, github.issues, github.pulls, github.user 등의 행이 표시되어야 합니다.

실제 쿼리를 실행해 보세요:

coral sql "
  SELECT CAST(commit__author__date AS DATE) AS date, COUNT(*) AS commits
  FROM github.commits
...

Coral은 __를 구분자로 사용하여 중첩된 JSON (Nested JSON)을 평탄화 (Flatten)합니다. 따라서 GitHub API 응답의 commit.author.date는 SQL에서 commit__author__date가 됩니다. 특정 테이블의 정확한 컬럼 이름을 확인하려면 SELECT column_name FROM coral.columns WHERE schema_name = 'github' AND table_name = 'commits'를 실행하세요.

에이전트 구축하기

GitHub 활동에 대한 자연어 질문에 답하는 Node.js 에이전트를 구축해 보겠습니다. 에이전트에게 "이번 주에 내가 무엇을 배포했지?"라고 물으면, 에이전트가 실제 커밋 데이터를 쿼리하여 AI가 생성한 요약을 반환합니다.

프로젝트 설정

mkdir my-coral-agent && cd my-coral-agent
npm init -y
npm install @google/genai dotenv

.env 파일을 생성합니다:

GEMINI_API_KEY=your_key_here
GITHUB_USERNAME=your_github_username

에이전트 — agent.ts

전체 에이전트 코드는 약 80줄 정도입니다. 작동 방식은 다음과 같습니다:

1단계: 실제 데이터를 위해 Coral에 쿼리하기

import { execFileSync } from 'child_process'

function coralQuery<T>(sql: string): T[] {
...

Coral의 CLI를 호출하여 JSON 출력을 요청합니다. execFileSync는 Coral 작업이 완료될 때까지 블로킹 (Blocking)됩니다. Coral은 모든 GitHub API 호출, 페이지네이션 (Pagination), 인증 (Auth)을 내부적으로 처리합니다.

2단계: 데이터 수집하기

function getGithubActivity(username: string, days: number) {
  // 일별 커밋 수
  const commits = coralQuery<{ date: string; repos: string; count: number }>(`
...

3단계: Gemini에게 질문하기

import { GoogleGenAI } from '@google/genai'

async function ask(question: string, data: object): Promise<string> {
...

4단계: 하나로 연결하기 (Wire it together)

import dotenv from 'dotenv'
dotenv.config()

...

실행하기 (Run it)

npx tsx agent.ts "what have I been shipping this week?"
npx tsx agent.ts "which repo am I spending the most time on?"
npx tsx agent.ts "have I been less active than usual?"

이 에이전트는 사용자의 실시간 GitHub 데이터를 조회하여 Gemini에게 전달하고, 실제 커밋 기록 (commit history)에 근거한 자연어 답변을 반환합니다.

더 나아가기: 교차 소스 쿼리 (cross-source queries)

Coral의 진정한 강력함은 소스 간의 조인 (joins)에 있습니다. 두 번째 소스를 추가해 보세요:

coral source add --interactive google_calendar

이제 두 소스에 걸친 질문을 할 수 있습니다:

-- 회의 일정이 많은 날의 커밋 내역
SELECT
  CAST(c.commit__author__date AS DATE) AS date,
...

이는 보통 두 번의 별도 API 호출, 결과 저장, 그리고 에이전트 코드 내에서의 수동 조인이 필요한 쿼리입니다. Coral을 사용하면 단 하나의 SQL 문으로 해결됩니다.

MCP 대신 Coral 사용하기

Claude Code, Cursor, 또는 MCP (Model Context Protocol) 호환 에이전트를 사용 중이라면, 별도의 커스텀 코드 없이 Coral을 MCP 서버로 노출할 수 있습니다:

# Claude Code
claude mcp add --scope user coral -- coral mcp-stdio

이 설정을 마치면, 에이전트는 자연어를 사용하여 연결된 모든 소스를 직접 조회할 수 있습니다. "나에게 할당된 GitHub 오픈 이슈를 보여줘"라고 요청하면, 에이전트가 자동으로 SQL을 작성하고 Coral을 통해 실행합니다.

또한 Coral의 스킬 (skills)을 설치하여 에이전트에게 발견 우선 워크플로 (discovery-first workflow)를 학습시킬 수도 있습니다:

npx skills add withcoral/skills

이를 통해 에이전트는 쿼리를 작성하기 전 스키마 (schema)를 탐색하는 데 필요한 coral.tables, coral.columns 및 메타데이터 테이블에 대한 지식을 갖게 됩니다.

내가 실제로 만든 것

서두에서 설명한 에이전트 — GitHub, 캘린더, 수면 데이터를 교차 참조하여 "왜 나는 생산적이지 못할까?"라는 질문에 답하는 에이전트 — 는 정확히 이 패턴을 사용합니다.

행동 지표 엔진 (behavioral metrics engine)은 다음을 계산합니다:

• 기준치 대비 수면 감소량 (Sleep decline vs baseline)
• 심야 코딩 세션 빈도 (Late-night coding session frequency)
• 본인의 기준치 대비 회의 부하 증가율 (Meeting load increase as a percentage over your own baseline)
• 컨텍스트 스위칭 (Context switching) (일일 리포지토리 수, GitHub 커밋으로부터 실시간 추출)
• 방해 횟수 추세 (Interruption count trends)

이 모든 데이터는 구조화된 프롬프트 (structured prompt) 형태로 Gemini에 입력됩니다. 터미널에서의 결과물은 다음과 같습니다:

  번아웃 위험 (BURNOUT RISK) ─────────────────────────────────

  ▘▀▀▀▀▀▀▀▀▀▀▀▝
...

전체 소스 코드는 GitHub에 공개되어 있습니다. 핵심 파일은 src/coral/sources/github.ts이며, 여기에는 Coral 쿼리를 TypeScript 함수로 래핑(wrap)하고 컬럼 명명 규칙 (column naming conventions)을 처리하는 방법이 정확히 나와 있습니다.

요약 (Summary)

Coral은 특정 범주의 보일러플레이트 (boilerplate)를 완전히 제거해 주는 도구 중 하나입니다. 소스별로 인증 (auth), 페이지네이션 (pagination), 재시도 로직 (retry logic)을 작성하는 대신, SQL을 작성하면 됩니다. 에이전트가 세 개의 별개 도구 출력값에 대해 추론하는 대신, 하나의 결과 집합 (result set)에 대해 추론하게 됩니다.

설정 방법은 다음과 같습니다:

# 1. 설치
brew install withcoral/tap/coral   # 또는 Linux의 경우 curl, Windows의 경우 zip

...

정말 이게 전부입니다. 복잡함은 Coral 내부에 존재하며, 여러분의 에이전트 코드는 깔끔하게 유지됩니다.

만약 Coral로 무언가를 만드신다면 꼭 보고 싶습니다. 참고용 구현체가 필요하시다면 xetroc 소스 코드가 github.com/TejaswaHinduja/xetroc에 있습니다.