```html

실전 튜토리얼

Google apal(Gemini)로 AI 에이전트 만들기 — n8n 워크플로우 구현 가이드

작성자: 지식인 질문답변 생성기 • 카테고리: AI 자동화 • 퍼머링크: /google-apal-agent-workflow

1. 들어가며 — 무엇을 만들 것인가?

이 글은 Google의 Generative AI(Gemini/PaLM, 이하 'apal') API를 사용해 n8n 기반 AI 에이전트를 만드는 실전 워크플로우 가이드입니다. 목표는 인증 설정 → n8n 트리거 → apal 호출 → 응답 후처리 → 도구 연동 → 배포까지 초보자도 따라 할 수 있도록 단계별로 설명하는 것입니다.

핵심 사용 사례 예: 매일 아침 날씨 + 긍정 뉴스 요약 발송, 이메일 자동 분류 및 티켓 생성, 캘린더 자동 일정 등록 등.

2. 전체 워크플로우 개요

에이전트의 구성은 다음 4가지 핵심 요소로 정리됩니다.

구성요소	역할	n8n에서의 구현
Brain	추론·생성 (apal / Gemini)	HTTP Request 또는 n8n의 Gemini 통합 노드
Sensors	입력 수집 (Webhook, Gmail, RSS)	Webhook / Gmail / HTTP Request
Memory	대화·이력 저장	Google Sheets / PostgreSQL / Airtable
Tools	행동 실행 (메일 전송, 캘린더)	Gmail / Google Calendar / Slack 노드

3. 단계별 구현 가이드

Step 1. Google API 키(또는 서비스 계정) 발급

1. Google Cloud Console 또는 AI Studio 접속 → 프로젝트 생성
2. API 사용 설정: Generative Language API (또는 Gemini 관련 API) 활성화
3. 인증 방식 선택:
   • 개발/테스트: API Key (간단하지만 권한 제어 제한)
   • 프로덕션: 서비스 계정(권장) — JSON 키 파일을 발급받아 사용

환경변수 예시: export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Step 2. n8n 기본 워크플로우 만들기 (구성 요소)

1. Webhook Trigger: 외부 요청(또는 테스트 호출)으로 워크플로우 시작
2. HTTP Request (apal 호출): Gemini/PaLM REST 엔드포인트에 POST
3. Function / Set 노드: LLM 응답에서 필요한 텍스트 추출·정리
4. 도구 노드: Gmail(발송), Google Sheets(로그/메모리), Calendar(일정 생성)
5. Cron 노드 (선택): 스케줄러를 이용한 자율 실행 설정

apal(Gemini) 호출 — HTTP Request 노드 예시

{
  "method": "POST",
  "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-latest:generateContent?key=AIzaSyD-FAKEKEYEXAMPLE1234567",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "contents": [
      {
        "parts": [
          {"text": "오늘의 샌프란시스코 날씨 한 줄 요약과 긍정 뉴스 2건을 마크다운 형식으로 작성해줘."}
        ]
      }
    ],
    "generation_config": {
      "max_output_tokens": 400
    }
  }
}

※ 실제 환경에서는 위 URL의 API Key를 환경변수로 관리하세요. 서비스계정 사용 시 OAuth/서비스 계정 토큰 방식으로 인증합니다.

Step 3. 응답 후처리 (Function 노드 예시)

// n8n Function node
return [{
  json: {
    reply: items[0].json.candidates?.[0]?.content?.parts?.[0]?.text || "No reply"
  }
}];

Step 4. 메모리(로그) 저장 — Google Sheets 예시

전송한 기사 URL, 전송일시, 사용자 ID 등을 Google Sheets에 기록해 중복 전송을 방지하고 분석에 활용합니다.

Step 5. 도구 연동 — Gmail 발송 예시

Function 노드에서 생성한 마크다운/HTML을 Gmail 노드의 본문으로 넣어 자동 발송합니다. 발송 성공 여부는 동일 시트에 기록하세요.

Step 6. 스케줄 및 자율성

n8n의 Cron 노드를 활용해 매일 정해진 시간에 워크플로우를 실행하면 사용자 입력 없이 자동으로 동작하는 에이전트가 됩니다.

4. 테스트 & 디버깅 체크리스트

• Webhook을 직접 호출해 전체 플로우 수동 테스트
• HTTP Request의 응답 구조(candidates → content → parts)를 콘솔/로그로 확인
• 중복 필터(시트 조회)가 예상대로 동작하는지 점검
• API Key 및 서비스 계정 권한(범위, IAM)이 올바른지 검증
• 실패 시 재시도 로직과 알림(Slack/Gmail) 설정

5. 실전 활용 시나리오(예시)

사례 A — 매일 아침 뉴스·날씨 요약 발송

Flow: Cron → Weather API → News API → apal로 요약 → 중복 필터 → Gmail 발송 → Sheets 기록

사례 B — 이메일 분류 및 자동응답

Flow: Gmail Trigger → apal로 분류/요약 → 단순 문의 자동응답(Gmail) / 복잡 케이스는 티켓 생성 → Sheets 기록

6. 운영 팁 & 보안 고려사항

• API 키 관리: 절대 코드나 공개 리포지토리에 키를 직접 넣지 마세요. n8n Credentials나 환경변수로 관리.
• 비용 관리: 모델 선택, 토큰 제한, 응답 길이 조절로 비용을 최적화하세요.
• 가드레일: system prompt에 제약을 명확히 넣어 불필요한 행동을 제한합니다.
• 로그·모니터링: 실패율, 응답시간, 중복율을 모니터링해 프롬프트·필터를 조정하세요.

7. 요약 및 다음 단계

요약: Google apal(Gemini)을 n8n에 연결하면 코드 적은(또는 없는) 상태로도 강력한 에이전트를 설계·운영할 수 있습니다. 핵심은 작게 시작 → 로그 저장 → 가드레일 적용 → 점진적 확장입니다.

다음 글에서는 이 워크플로우를 실제로 import 가능한 n8n JSON(예: Webhook → Gemini → Function → Gmail → Sheets)을 제공하고, 서비스계정 기반 인증 예제를 상세히 다뤄드리겠습니다.

```