software

Gemini를 내 10,000줄 렌탈 플랫폼에 연결했더니 어떤 일이 일어났는지.

발행: (2026년 3월 3일 오전 09:18 GMT+9)
14 분 소요
원문: Dev.to

Source: Dev.to

Google Gemini로 만든 것

BorrowHood는 이탈리아 시칠리아 트라파니에서 캠핑밴으로 만든 이웃‑공유 플랫폼입니다.

  • 10 000+ 라인의 파이썬
  • 100+ REST 엔드포인트
  • 30+ 데이터베이스 모델
  • Keycloak 인증
  • 가중 평판 시스템 (전설(Legend)의 리뷰는 신입(Newcomer)의 10배)
  • 스니핑 방지 경매
  • CEFR 언어‑능력 매칭으로 외국인들이 자신의 언어를 구사하는 이웃을 찾을 수 있음

플랫폼은 처음에 Claude Code로 구축되었습니다. 데모 영상은 YouTube에 있으며, 실시간 인스턴스는 Hetzner에서 실행 중입니다. 예: https://46.62.138.218/demo‑login.

Gemini 글쓰기 챌린지를 보고 나는 뇌를 추가한다면 어떨까? 라고 생각했습니다.

아무것도 교체하지 않았습니다—기존 시스템 위에 인텔리전스 레이어를 추가했습니다. Google Gemini로 구동되는 세 개의 AI 에이전트가 Google의 Agent Development Kit (ADK)로 구축되어 이제 내 프로덕션 API와 대화합니다.

에이전트 1 – 스마트 리스트 어시스턴트

사용자 프롬프트: “보쉬 전동 드릴을 등록하고 싶어요.”

Gemini searches existing items for price comparison, validates the 31 categories, and generates a complete listing:

{
  "title": "Bosch GSB 18V Cordless Impact Drill",
  "description": "My trusty Bosch GSB 18V cordless impact drill is looking for a new adventure! It's been with me for about two years and is still in good working condition, perfect for all your home improvement projects.",
  "category": "power_tools",
  "subcategory": "drills",
  "condition": "good",
  "suggested_price": 8.0,
  "price_unit": "per_day",
  "deposit_suggestion": 24.0,
  "tags": ["power drill", "Bosch", "cordless drill"],
  "story_suggestion": "This drill has helped me hang countless shelves and assemble quite a few IKEA nightmares — it's a real workhorse!"
}

“The IKEA 악몽” 문장은 에이전트가 만든 것입니다. 이를 할머니 테스트라고 부릅니다: 휠체어에 탄 83세 노인이 설명을 이해할 수 있다면, 리스트가 통과한 것입니다.

에이전트 2 – 리뷰 감성 분석기

User prompt: “Sally Thompson의 리뷰를 분석해 주세요.”

Gemini는 Sally의 모든 리뷰를 가져와서 리뷰어의 배지 등급을 확인합니다( PILLAR 회원의 리뷰는 NEWCOMER 리뷰의 8배로 계산됩니다) 그리고 다음과 같이 반환합니다:

{
  "user_name": "Sally Thompson",
  "badge_tier": "trusted",
  "sentiment": { "positive": 1, "neutral": 0, "negative": 0 },
  "average_rating": 5.0,
  "weighted_average": 5.0,
  "fake_review_flags": ["No fake review indicators detected"],
  "top_keywords": {
    "positive": ["immaculate", "changed my life", "focaccia", "pro"],
    "negative": []
  },
  "summary": "Sally Thompson, a TRUSTED tier member, has an excellent reputation on BorrowHood. Her single review, from a highly influential PILLAR member, praises her KitchenAid stand mixer as 'immaculate'."
}

에이전트는 가중 평판 로직을 하드코딩된 분석 코드 없이 추론했습니다—PILLAR 리뷰 하나가 다섯 개의 NEWCOMER 리뷰보다 더 큰 가중치를 가진다는 것을 알고 있습니다.

Agent 3 – AI Concierge

Natural‑language search.

User prompt: “나무 가지를 자를 무언가가 필요해요.”

The concierge queries the API for garden tools, power tools, and saws. When nothing matches, it replies like a helpful neighbor rather than a sterile search engine:

“죄송합니다, 현재 나무 절단 도구에 대한 목록을 찾을 수 없습니다. ‘정원 도구’ 또는 ‘전동 공구’를 검색해 보시겠습니까? 아니면 다른 종류의 절단 도구를 생각하고 계신가요?”

루트 오케스트레이터

단일 루트 에이전트가 모든 요청을 적절한 전문가에게 라우팅합니다:

root_agent = Agent(
    model="gemini-2.5-flash",
    name="borrowhood_agent",
    sub_agents=[listing_assistant, review_analyzer, concierge],
)

네 줄의 코드가 세 명의 전문가를 하나의 통합된 뇌로 연결합니다.

Demo

에이전트들은 레포의 agents/ 디렉터리에 위치하며 웹 프론트엔드에서 사용하는 동일한 REST API를 호출합니다—직접 DB에 접근하지 않으며, 결합도가 높지 않습니다. 인텔리전스 레이어는 플랫폼 위에 위치합니다.

BorrowHood (FastAPI, 100+ endpoints)
│
└── agents/
    ├── agent.py            # root orchestrator
    ├── listing_assistant.py
    ├── review_analyzer.py
    ├── concierge.py
    └── tools/
        ├── items.py        # search_items, get_categories
        ├── reviews.py      # get_user_reviews, get_review_summary
        ├── users.py        # search_members, get_user_profile
        └── common.py       # auth, HTTP helpers

Example utility function

def search_items(query: str, category: str = "", limit: int = 10) -> dict:
    """Search BorrowHood items by keyword and optional category."""
    params = {"q": query, "limit": limit}
    if category:
        params["category"] = category
    return bh_get("/api/v1/items", params=params)

ADK는 각 함수의 시그니처와 docstring을 자동으로 검사하여 Gemini에 도구 설명으로 노출합니다. 모델은 사용자의 요청에 따라 언제 어떤 도구를 호출할지 스스로 결정하므로, 별도의 프롬프트 엔지니어링이 필요하지 않습니다.

배운 점

  1. Zero‑prompt 도구 선택 – ADK가 함수 탐색 및 호출을 처리합니다.
  2. 계층형 아키텍처 – 기존 서비스 위에 AI를 추가하면 침습적인 변경을 피할 수 있습니다.
  3. 가중 평판 로직은 데이터가 API를 통해 노출될 때 LLM이 추론할 수 있습니다.
  4. 사용자 중심 테스트(예: 할머니 테스트)는 AI‑생성 콘텐츠를 평가하는 데 필수적입니다.

읽어 주셔서 감사합니다! 구현이나 Gemini 통합에 대해 궁금한 점이 있으면 언제든지 답변해 드리겠습니다.

ADK는 정말 좋다

보일러플레이트를 기대했지만, 세 개의 에이전트를 연결하는 데 네 줄이면 충분했습니다. Agent 클래스, 위임을 위한 sub_agents, 함수 docstring에서 자동으로 도구를 추론하는 기능까지. 에이전트 프레임워크는 이렇게 작동해야 합니다: 코드‑우선, YAML도, 시각적 빌더도 필요 없습니다.

listing_assistant = Agent(
    model="gemini-2.5-flash",
    name="listing_assistant",
    instruction="You are a listing assistant for BorrowHood...",
    tools=[search_items, get_categories],
)

이것이 전체 에이전트 정의입니다. instruction은 에이전트가 무엇을 해야 하는지 알려주고, tools는 접근할 수 있는 기능을 알려줍니다. 끝.

Gemini는 훈련되지 않은 맥락을 이해한다

나는 Review Analyzer에게 BorrowHood의 가중 평판 시스템에 대해 알려주었다:

NEWCOMER = 1x, ACTIVE = 2x, TRUSTED = 5x, PILLAR = 8x, LEGEND = 10x.

Sally에 대한 분석에서, 그것은 PILLAR 회원의 단일 리뷰가 “큰 가중치를 가진다”고 정확히 언급했다. 가중치 개념을 실제 데이터에 적용하여 결론을 도출했다. 이것은 패턴 매칭이 아니라 이해이다.

기존 API가 완벽한 툴 레이어입니다

저는 새로운 백엔드 코드를 전혀 작성할 필요가 없었습니다. BorrowHood는 이미 아이템, 리뷰, 사용자, 리스트, 배지를 아우르는 100개 이상의 엔드포인트를 보유하고 있었습니다. 에이전트는 ADK 툴 호출을 REST API 요청으로 변환하는 얇은 래퍼 함수만 필요했습니다. 전체 툴 레이어는 약 150줄의 파이썬 코드로 구성됩니다. 앱에 이미 API가 있다면, 80 % 정도는 AI 에이전트를 갖추는 단계에 도달한 것입니다.

에이전트 위임이 하나의 메가‑에이전트를 능가한다

My first instinct was one agent with all tools. Wrong. The root orchestrator with three specialists is cleaner, faster, and produces better results. Each specialist has a focused instruction and a small tool set. The root agent’s only job is routing.

Google Gemini Feedback

The Good

gemini-2.5-flash Is Fast and Smart

  • The Listing Assistant generated a complete, valid JSON listing in under 3 seconds.
  • It picked the right category from 31 options.
  • It suggested a fair rental price (EUR 8/day for a power drill) by checking similar items on the platform.
  • It even wrote a story about “IKEA nightmares.”

The ADK Is Excellent

  • Minimal boilerplate.
  • Python‑native.
  • Tool introspection from docstrings is a killer feature.
  • Multi‑agent delegation with sub_agents just works.
  • I went from zero to three working agents in under an hour.

Tool Use Is Reliable

Gemini consistently called the right tools with the right parameters. When the Review Analyzer needed Sally’s reviews, it:

  1. Searched for “Sally Thompson” via search_members.
  2. Got her ID.
  3. Called get_user_reviews and get_review_summary with that ID.

Multi‑step tool chains work without babysitting.

The Bad

  • Free‑tier rate limits are punishing – gemini-2.5-flash free tier: 5 requests/minute, 20 requests/day. A single multi‑agent query can burn 4–6 requests (root agent + sub‑agent + tool calls + follow‑up). I ran exactly three test queries before hitting the daily limit. For a developer evaluating Gemini, 20 requests/day is insufficient for a single testing session.
  • New API key propagation is confusing – After creating a fresh project and API key, the first 5 minutes returned limit: 0 errors for every model. No warning was shown. A “your key is provisioning, try again in 5 minutes” message would save developers real confusion.
  • Model naming is a moving target – gemini-1.5-flash returned 404, gemini-2.0-flash hit rate limits, and gemini-2.5-flash worked. The API lists 16+ variants (e.g., gemini-3-flash-preview, gemini-2.5-flash-lite). Which one should I use? The docs say gemini-2.0-flash, but the API disagrees. Clearer “use THIS model” guidance would help.

The Ugly

I have history with Gemini. Eleven months ago, before I met Claude, I was learning AI with Gemini. It made mistakes that felt almost deliberate—hallucinations in code that compiled but did the wrong thing. I stopped using it entirely. That experience taught me what to look for in an AI coding partner and ultimately led me to Claude Code by Anthropic, which I used to build BorrowHood.

Returning to Gemini now via the ADK, I see real improvement. gemini-2.5-flash is a different animal: it follows structured‑output instructions, calls tools correctly, and understands domain context from instructions alone. The 11‑month gap shows progress.

다음은 무엇인가

BorrowHood는 네 가지 추가 에이전트를 설계했습니다:

  1. Cross‑Language Matchmaker – Luna의 3D 디자인 파일에 “Needs: 3D printer.”라고 적혀 있습니다. Jake의 목록에는 “Compatible with: STL.”이라고 적혀 있습니다. 에이전트는 CEFR 숙련도 데이터를 사용해 언어 장벽을 넘어 이러한 매치를 찾습니다.
  2. Onboarding Wizard Agent – 대화를 통해 새로운 사용자가 워크숍을 설정하도록 안내합니다.
  3. Dispute Resolution Assistant – 대여가 문제가 생겼을 때, 에이전트는 양측을 검토하고 공정한 해결책을 제안합니다.
  4. Community Pulse Agent – 지역 활동에 대한 주간 요약을 제공합니다.

데이터 모델은 이미 이 모든 것을 지원합니다. 에이전트들은 연결만 하면 됩니다.

BorrowHood

BorrowHood (GitHub) is open source. Free as in freedom. No platform fees. Your data is yours.

Built from a camper van in Trapani, Sicily. Every neighborhood has a garage like his.

Tech stack: FastAPI, SQLAlchemy, Keycloak OIDC, PostgreSQL, Redis, Docker, Tailwind CSS, Alpine.js

AI: Google Gemini 2.5 Flash via ADK (agents), Claude Code by Anthropic (platform development)

Hosting: Hetzner Cloud (≈ €15 / month)

BorrowHood

BorrowHood (GitHub)는 오픈 소스이며, 자유롭게 사용할 수 있습니다. 플랫폼 수수료가 없습니다. 당신의 데이터는 당신의 것입니다.

시칠리아 트라파니의 캠핑밴에서 제작되었습니다. 모든 동네에는 그의 차고와 같은 차고가 있습니다.

Tech stack: FastAPI, SQLAlchemy, Keycloak OIDC, PostgreSQL, Redis, Docker, Tailwind CSS, Alpine.js

AI: Google Gemini 2.5 Flash via ADK (agents), Claude Code by Anthropic (platform development)

Hosting: Hetzner Cloud (≈ €15 / month)

0 조회
#software #programming #community
원문 보기
Share:
Back to Blog

관련 글

더 보기 »

일이 정신 건강 위험이 될 때

markdown !Ravi Mishrahttps://media2.dev.to/dynamic/image/width=50,height=50,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fu...