1. 소개
Google Workspace는 업무가 진행되는 곳입니다. Docs에서 보고서 초안을 작성하고, Sheets에서 데이터를 분석하고, Gmail 및 Meet에서 공동작업하는 등 다양한 작업을 지원합니다.
이제 Docs, Sheets, Gmail이 도구가 아닌 공동작업자라고 생각해 보세요.
Google의 에이전트 개발 키트 (ADK)와 Vertex AI의 에이전트 엔진을 사용하면 더 이상 아이디어에 그치지 않고 이러한 프레임워크를 사용하여 지능형 에이전트를 빌드하고, 에이전트를 대규모로 배포하고, Google Workspace 도구에 원활하게 통합하여 에이전트 생산성의 새로운 시대를 열 수 있습니다.
이 Codelab에서는 다음과 같이 단계별 접근 방식을 사용합니다.
- 에이전트 개발 키트를 사용하여 AI 사실 확인 에이전트를 개발합니다.
- 완전 관리형 환경인 Agent Engine에 에이전트를 배포하여 에이전트를 대규모로 실행합니다.
- 이 에이전트를 Google Docs에 통합하여 문서의 텍스트에 대한 사실 확인을 수행합니다.
최종 솔루션의 작동 방식을 설명하는 개념 다이어그램은 아래와 같습니다.
다음은 Google 문서 내에서 사실 확인 에이전트가 작동하는 최종 출력입니다. 여기에는 일부 문장이 포함된 원본 텍스트가 있으며 문서의 각 문장에 대한 사실 확인을 수행합니다. 빨간색 모서리가 있는 상자에 바인딩된 출력은 에이전트의 출력입니다.
실습할 내용
- Google 문서 내에서 사실 확인을 수행하는 에이전트를 설계, 빌드, 배포합니다.
학습할 내용
- 에이전트 개발 키트 (AK)를 사용하여 에이전트를 개발합니다.
- 에이전트를 로컬에서 테스트하고 에이전트 엔진에 배포합니다.
- Google Workspace 문서 (Google 문서)에 에이전트를 통합합니다.
필요한 항목
- Chrome 웹브라우저
- Gmail 계정
- 결제가 사용 설정된 Cloud 프로젝트
이 Codelab은 초보자를 포함한 모든 수준의 개발자를 위해 설계되었으며 샘플 코드에서 Python과 Apps Script를 사용합니다. 하지만 이러한 프로그래밍 언어를 알지 못해도 되며 기본적인 코드 읽기 기능만으로도 제시된 개념을 이해할 수 있습니다.
2. 시작하기 전에
프로젝트 만들기
- Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
- Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요 .
- bq가 미리 로드되어 제공되는 Google Cloud에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
- Cloud Shell에 연결되면 다음 명령어를 사용하여 인증이 완료되었고 프로젝트가 해당 프로젝트 ID로 설정되었는지 확인합니다.
gcloud auth list
- Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.
gcloud config list project
- 프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
- 아래에 표시된 명령어를 통해 필수 API를 사용 설정합니다. 몇 분 정도 걸릴 수 있으니 잠시만 기다려 주세요.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
명령어가 성공적으로 실행되면 아래와 비슷한 메시지가 표시됩니다.
Operation "operations/..." finished successfully.
API가 누락된 경우 구현 과정에서 언제든지 사용 설정할 수 있습니다.
gcloud 명령어 및 사용법은 문서를 참조하세요.
3. ADK 에이전트 빌드
Google의 사실확인 맞춤 함수 샘플에서 영감을 받은 텍스트의 사실을 확인하는 AI 기반 감사자인 ADK 에이전트 (Document Fact Checker Agent)를 만들어 보겠습니다. 샘플의 단일 단계 접근 방식과 달리, 에이전트는 다단계 추론을 사용하여 주장을 추출하고, google_search로 이를 검증하고, 구조화된 JSON을 출력합니다.
1단계 : 에이전트 개발 키트 설치하기
Cloud Shell에서 새 터미널 탭을 열고 다음과 같이 my-agents이라는 폴더를 만듭니다. my-agents 폴더로도 이동합니다.
mkdir workspace-agents
cd workspace-agents
이제 다음과 같이 venv를 사용하여 가상 Python 환경을 만들어 보겠습니다.
python -m venv .venv
다음과 같이 가상 환경을 활성화합니다.
source .venv/bin/activate
다음과 같이 ADK를 설치합니다.
pip install google-adk
이제 다음과 같이 adk 유틸리티를 호출할 수 있습니다.
adk
명령어 목록이 표시됩니다.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
conformance Conformance testing tools for ADK.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
eval_set Manage Eval Sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
2단계 : ADK를 사용하여 문서 사실 확인 에이전트 개발
이제 adk을 사용하여 아래와 같이 앱 이름 **(docfactcheckeragent)**으로 adk create 명령어를 통해 에이전트의 스캐폴딩을 만듭니다.
adk create docfactcheckeragent
단계를 따르고 다음을 선택합니다.
- 루트 에이전트의 모델을 선택하는 Gemini 모델입니다.
- 백엔드로 Vertex AI를 선택합니다.
- 기본 Google 프로젝트 ID와 리전이 표시됩니다. 기본값을 직접 선택합니다.
Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/workspace-agents/docfactcheckeragent:
- .env
- __init__.py
- agent.py
에이전트의 기본 템플릿과 필수 파일이 생성된 폴더를 확인합니다.
먼저 .env 파일을 살펴보겠습니다. 내용은 아래와 같습니다.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
이 값은 Google Cloud 프로젝트 ID 및 위치의 해당 값과 함께 Vertex AI를 통해 Gemini를 사용함을 나타냅니다.
그런 다음 폴더를 모듈로 표시하고 agent.py 파일에서 에이전트를 가져오는 단일 문이 있는 __init__.py 파일이 있습니다.
from . import agent
마지막으로 agent.py 파일이 있습니다. 이 agent.py 파일의 내용을 아래에 표시된 코드로 바꿔야 합니다.
from google.adk.agents import Agent
from google.adk.tools import google_search
root_agent = Agent(
name='ai_auditor',
model='gemini-2.5-flash',
description="Fact-checks statements from a document and provides citations.",
instruction="""
You are an AI Auditor specialized in factual verification and evidence-based reasoning.
Your goal is to analyze text from a Google Doc, identify verifiable factual claims, and produce a concise, source-backed audit report.
### 🔍 TASK FLOW
1. **Extract Claims**
- Analyze the input text and identify factual claims that can be objectively verified.
- A factual claim is any statement that can be proven true or false with external evidence.
- Skip opinions, vague generalizations, or speculative language.
- List each claim as a string in a JSON array.
2. **Verify Claims**
- For each extracted claim:
- Use the `google_search` tool to find relevant, credible results.
- Evaluate at least the top 3 relevant URLs to determine the claim's accuracy.
- Cross-check multiple sources when possible to ensure confidence.
3. **Classify Findings**
- For each claim, determine one of the following verdicts:
- ✅ **True:** Supported by multiple reputable sources.
- ⚠️ **Misleading / Partially True:** Contains partially correct or context-dependent information.
- ❌ **False:** Contradicted by credible evidence.
- ❓ **Unverifiable:** Insufficient information to confirm or deny.
- Provide a **confidence score (0–100)** reflecting the strength of evidence.
4. **Record Evidence**
- For each claim, include:
- The **verdict**
- **Reasoning summary** (1–2 sentences)
- **List of citation URLs** used for verification
5. **Summarize Results**
- Compile a final report including:
- Total number of claims analyzed
- Distribution of verdicts (True / False / Misleading / Unverifiable)
- Brief overall conclusion (e.g., "Most claims are accurate but some lack supporting evidence.")
### 🧾 OUTPUT FORMAT
Return your final response in structured JSON format as follows:
{
"claims": [
{
"claim": "...",
"verdict": "True | False | Misleading | Unverifiable",
"confidence": 0-100,
"reasoning": "...",
"sources": ["https://...", "https://..."]
}
],
"summary": {
"total_claims": X,
"verdict_breakdown": {
"True": X,
"False": X,
"Misleading": X,
"Unverifiable": X
},
"overall_summary": "..."
}
}
### 🧠 ADDITIONAL INSTRUCTIONS
- Always prefer authoritative domains (.gov, .edu, .org, or major media).
- Avoid low-quality or user-generated content as primary sources.
- Be concise, accurate, and transparent about uncertainty.
""",
tools=[google_search], # Only use the search tool
)
위 소스 코드의 주요 사항은 다음과 같습니다.
- 이름, 모델, 설명, 매우 상세한 명령어 세트를 지정하여 AI 에이전트를 정의합니다.
- 명령어 세트는 에이전트가 정확히 어떻게 생각하고 작동해야 하는지 정의하는 가장 중요한 부분입니다. 이 구조는 전문 팩트체커가 작업하는 방식을 반영하여 AI를 자율 감사 파이프라인으로 전환합니다.
- 이 에이전트 선언이 완료되면
Google Search tool를 통해 에이전트가 실제 정보에 액세스할 수 있도록 합니다. 사전 학습된 데이터에 의존하는 대신 에이전트는 실시간 검색을 실행하고, 결과를 평가하고, 최신 인용을 제공할 수 있습니다.
이 시스템이 에이전트인 이유는 모델이 단순히 답변을 생성하는 것이 아니라 도구를 사용하여 정보를 확인하는 조치를 취하기 때문입니다.
3단계 : 로컬로 에이전트 테스트하기
기존 터미널 창에서 다음 명령어를 입력합니다. docfactcheckeragent 폴더가 포함된 상위 폴더 (workspace-agents)에 있는지 확인합니다.
adk web
실행 샘플은 아래와 같습니다.
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
마지막 링크를 클릭하면 에이전트를 테스트할 수 있는 웹 콘솔이 표시됩니다. 첫 번째 상호작용은 에이전트가 실제로 할 수 있는 일을 파악하는 데 필수적입니다. 이를 통해 에이전트의 description 및 instruction text 요약 능력을 테스트합니다.
에이전트는 설명과 명령어 세트에서 가져온 기능을 간결하게 요약합니다.
그런 다음 두 개의 문 (The sky is blue due to Rayleigh scattering. The Earth is flat.)을 제공하면 콘텐츠를 성공적으로 감사하고 잘 구조화된 JSON 응답을 다시 제공합니다.
자세히 살펴보기:
- google_search 도구는 웹에서 관련 페이지를 가져옵니다.
- Gemini 2.5 Flash 모델은 이러한 스니펫을 파싱하고 사실 여부를 분류합니다.
- ADK는 추론 오케스트레이션을 처리하고 단계별 논리가 따르도록 합니다.
이 로컬 테스트 단계는 Docs 또는 Sheets와 같은 Google Workspace 도구에 연결할 수 있는 Vertex AI Agent Engine에 에이전트를 배포하기 전에 에이전트의 워크플로를 검증하는 데 도움이 됩니다.
요약하자면 Google의 에이전트 개발 키트 (ADK)를 사용하여 강력한 AI 감사 에이전트를 빌드했습니다. 에이전트는 텍스트를 읽고, 사실에 기반한 주장을 식별하고, 신뢰할 수 있는 소스를 검색 (google_search 도구 사용)하고, 명확한 결론을 반환할 수 있습니다.
ADK 웹 인터페이스를 통해 모든 것을 로컬에서 빌드하고 테스트했으며, 에이전트가 다음과 같은 문장을 분석하는 방식을 확인했습니다.
The sky is blue due to Rayleigh scattering. The Earth is flat.
상담사가 한 주장을 true로 확인하고 다른 주장을 false로 표시했습니다. 이는 현지 설정이 완벽하게 작동한다는 작지만 적절한 증거입니다.
이제 로컬에서 클라우드로 이동하는 다음 단계를 밟을 때입니다. 다음 단계로 넘어가겠습니다.
4. Vertex AI Agent Engine에 에이전트 배포
실제 에이전트는 노트북에서 테스트하는 것뿐만 아니라 대규모로 실행하고, 다른 시스템과 통합하고, 앱 전반에 걸쳐 프로덕션에 배포할 수 있는 것입니다.
배포해야 하는 이유
에이전트를 클라우드에 배포해야 하는 몇 가지 이유를 소개합니다.
- 확장성: 로컬 런타임 제한 없이 대량의 요청을 처리합니다.
- 안정성: 2025년 10월 18일 ADK 도구 구성 업데이트와 같은 수정사항이 적용된 내장 모니터링 및 자동 확장
- 통합 준비: 원활한 Workspace 호출을 위한 API 엔드포인트를 노출합니다.
Vertex AI Agent Engine을 사용해야 하는 이유
Vertex AI Agent Engine은 배포된 ADK 에이전트의 홈과 같습니다. 안정성, 확장성, 통합을 위해 빌드된 관리형 환경입니다.
이를 통해 에이전트는 다음을 수행할 수 있습니다.
- 영구 상태 및 메모리
- 통합 도구 실행 (예: Google 검색, Vertex AI 모델)
- 외부 호출을 위한 API 엔드포인트 보안
- Cloud Logging을 통한 로깅 및 관측 가능성
- 멀티 에이전트 오케스트레이션에 대한 기본 지원
간단히 말해 ADK로 한 번 작성한 다음 Agent Engine을 사용하여 확장합니다.
1단계 : 배포 설정
Vertex AI Agent Engine에 에이전트를 배포하기 전에 몇 가지 작업을 수행해야 합니다. 배포 프로세스에는 에이전트 아티팩트용 Google Cloud Storage 버킷이 필요하며, 에이전트 코드 실행에 필요한 모든 종속 항목이 에이전트 엔진 런타임 환경에서 사용할 수 있도록 requirements.txt 파일도 제공해야 합니다.
Cloud Shell 터미널에서 다음 명령어를 실행하여 버킷을 만듭니다. YOUR_BUCKET_NAME, YOUR_PROJECT_ID, YOUR_PROJECT_REGION는 프로젝트에 맞는 실제 값으로 바꾸세요.
gcloud storage buckets create gs://YOUR_BUCKET_NAME \
--project=YOUR_PROJECT_ID \
--location=YOUR_PROJECT_REGION
그런 다음 루트 폴더 (workspace-agents)에 다음 requirements.txt 파일을 만듭니다. 콘텐츠는 아래와 같습니다.
google-cloud-aiplatform
google-adk
requests
2단계 : 에이전트 배포하기
다음 단계는 adk deploy 명령어를 사용하여 에이전트를 Vertex AI Agent Engine에 배포하는 것입니다.
adk deploy agent_engine \
--project=YOUR_PROJECT_ID \
--region=YOUR_PROJECT_REGION \
--display_name "Doc Fact Checker" \
--staging_bucket gs://YOUR_BUCKET_NAME \
--requirements_file requirements.txt \
docfactcheckeragent/
그러면 에이전트를 Agent Engine에 배포하는 프로세스가 시작됩니다. 이 프로세스는 시간이 오래 걸리며 약 5분이 소요될 수 있습니다. 개략적으로 다음과 같은 일이 일어납니다.
- 에이전트 생성이 시작됩니다. ADK CLI가 코드를 패키징하고 Cloud Storage 버킷에 업로드하며 Vertex AI가 새 Agent Engine 인스턴스를 생성하도록 트리거합니다.
- 프로젝트의 Cloud 로그 탐색기를 볼 수 있는 로그 링크가 제공됩니다. 이 버튼을 클릭하면 설정 단계, 종속 항목 설치, 모델 초기화를 비롯한 자세한 진행 상황을 확인할 수 있습니다. 종속 항목 누락이나 권한 문제와 같은 문제가 발생하면 여기에 오류 메시지가 표시됩니다.
- 완료 메시지 - 배포가 완료되면 터미널에 추론 엔진 ID와 함께 확인 메시지가 표시됩니다. 아래는 그 예입니다.
AgentEngine created. Resource name: projects/SOME_ID/locations/REGION/reasoningEngines/SOME_ID
3단계 : Cloud Console에서 에이전트 확인 (에이전트 엔진)
배포가 완료되면 Google Cloud 콘솔의 Vertex AI → Agent Engine 섹션으로 이동합니다. 배포된 에이전트가 아래와 같이 콘솔에 표시됩니다.
🎉 완료되었습니다. 이제 에이전트가 Vertex AI에서 제공되며 Google Workspace에 통합하거나 직접 테스트할 수 있습니다.
4단계 : 배포 에이전트 테스트
축하합니다. 이제 Vertex AI Agent Engine에서 에이전트를 사용할 수 있습니다. 다음 단계는 올바르게 배포되었으며 요청에 응답하는지 테스트하는 것입니다.
작업 방식에 따라 다음과 같은 여러 가지 방법이 있습니다.
- Google Cloud 콘솔: 배포된 에이전트를 직접 보고, 관리하고, 테스트할 수 있는 시각적 인터페이스입니다.
- REST API (cURL) 사용: 요청을 수동으로 전송하고 응답을 검사하려는 개발자에게 적합합니다.
- Python용 Vertex AI SDK: 개발 워크플로에 테스트를 통합하는 더 프로그래매틱한 옵션입니다.
각 접근 방식을 사용하면 배포된 후 에이전트가 어떻게 작동하는지(예: 쿼리 처리, 세션 처리, 응답 반환) 파악할 수 있습니다. 각 방법의 자세한 단계, 예시, 고급 구성을 살펴보려면 공식 문서(여기)를 참고하세요.
이제 AI 감사자는 클라우드 기반 에이전트이며, Vertex AI Agent Engine에 배포되어 google_search를 사용하여 대규모로 사실을 확인할 수 있습니다. 신뢰할 수 있는 API 기반 디지털 팀원으로 변신하여 다음과 같은 JSON을 생성합니다.
{ "claims": [{"claim": "The sky is blue...", "verdict": "True", "confidence": 95}] }
다음 섹션에서 직접 테스트해 보겠습니다. Google 문서 내에 에이전트를 통합하고 문서에 명시된 사실을 검증할 것입니다.
5. 사실 확인 에이전트를 Google Docs에 통합
이 섹션에서는 모든 것을 연결하여 배포된 에이전트를 Google Docs 내에 가져옵니다. 몇 줄의 Apps Script를 사용하면 배포된 에이전트를 사용하여 콘텐츠를 자동으로 분석하고 사실을 확인할 수 있는 AI 지원 편집기로 표준 Google 문서를 변환할 수 있습니다.
1단계: Google Docs 환경 설정하기
새 Google 문서 (docs.new)를 열거나 기존 Google 문서를 엽니다.
이 튜토리얼에서 사용하는 Google 문서에는 다음 콘텐츠가 포함되어 있습니다. 이 콘텐츠를 사용하거나 사실확인을 계획하는 자체 콘텐츠를 사용할 수 있습니다.
Climate change is mainly caused by solar activity cycles, not human activities. The Earth's temperature has not increased significantly in the last 100 years. Wind energy now produces more electricity than coal in every country in Europe. In 2015, nearly all world nations signed the Paris Agreement to limit global warming.
2단계: Apps Script 프로젝트 및 파일 설정
이 설정을 위해서는 Apps Script 프로젝트에 다음 두 파일이 필요합니다.
AIVertex.gs- Vertex AI 및 ADK 에이전트와의 모든 통신을 처리합니다.Code.gs- Google Docs 인터페이스, 메뉴, 문서 작업을 제어합니다.
메뉴에서 Extensions -> Apps Script로 이동하여 편집기를 엽니다. 이 공간은 배포된 ADK 에이전트에 연결하는 데 사용됩니다. Code.gs 파일이 이미 생성되어 있으며 다음 섹션에 제공된 Code.gs 코드로 콘텐츠를 바꿔야 합니다.
각 항목을 살펴보겠습니다.
AIVertex.gs
왼쪽의 파일 섹션 옆에 있는 + 기호를 통해 새 파일을 만들고 Script로 선택한 후 다음 콘텐츠를 복사합니다.
const LOCATION = PropertiesService.getScriptProperties().getProperty('LOCATION');
const GEMINI_MODEL_ID = PropertiesService.getScriptProperties().getProperty('GEMINI_MODEL_ID');
const REASONING_ENGINE_ID = PropertiesService.getScriptProperties().getProperty('REASONING_ENGINE_ID');
const SERVICE_ACCOUNT_KEY = PropertiesService.getScriptProperties().getProperty('SERVICE_ACCOUNT_KEY');
const credentials = credentialsForVertexAI();
/**
* @param {string} statement The statement to fact-check.
*/
function requestLlmAuditorAdkAiAgent(statement) {
return UrlFetchApp.fetch(
`https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/reasoningEngines/${REASONING_ENGINE_ID}:streamQuery?alt=sse`,
{
method: 'post',
headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
contentType: 'application/json',
muteHttpExceptions: true,
payload: JSON.stringify({
"class_method": "async_stream_query",
"input": {
"user_id": "google_sheets_custom_function_fact_check",
"message": statement,
}
})
}
).getContentText();
}
/**
* @param {string} prompt The Gemini prompt to use.
*/
function requestOutputFormatting(prompt) {
const response = UrlFetchApp.fetch(
`https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/publishers/google/models/${GEMINI_MODEL_ID}:generateContent`,
{
method: 'post',
headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
contentType: 'application/json',
muteHttpExceptions: true,
payload: JSON.stringify({
"contents": [{
"role": "user",
"parts": [{ "text": prompt }]
}],
"generationConfig": { "temperature": 0.1, "maxOutputTokens": 2048 },
"safetySettings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"threshold": "BLOCK_NONE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"threshold": "BLOCK_NONE"
},
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"threshold": "BLOCK_NONE"
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"threshold": "BLOCK_NONE"
}
]
})
}
);
return JSON.parse(response).candidates[0].content.parts[0].text
}
/**
* Gets credentials required to call Vertex API using a Service Account.
* Requires use of Service Account Key stored with project.
*
* @return {!Object} Containing the Google Cloud project ID and the access token.
*/
function credentialsForVertexAI() {
const credentials = SERVICE_ACCOUNT_KEY;
if (!credentials) {
throw new Error("service_account_key script property must be set.");
}
const parsedCredentials = JSON.parse(credentials);
const service = OAuth2.createService("Vertex")
.setTokenUrl('https://oauth2.googleapis.com/token')
.setPrivateKey(parsedCredentials['private_key'])
.setIssuer(parsedCredentials['client_email'])
.setPropertyStore(PropertiesService.getScriptProperties())
.setScope("https://www.googleapis.com/auth/cloud-platform");
return {
projectId: parsedCredentials['project_id'],
accessToken: service.getAccessToken(),
}
}
파일을 저장해야 합니다.
이 파일은 다음을 수행합니다.
- 서비스 계정 키를 사용하여 Vertex AI에 안전하게 인증합니다. 배포된 ADK 에이전트를 호출하여 문서 텍스트를 분석하거나 사실 확인합니다.
- Gemini를 사용하여 스마트 응답 형식을 지정하여 결과를 사람이 읽을 수 있도록 합니다.
Code.gs
/**
* Adds a custom menu in Google Docs to run the AI Audit directly.
*/
function onOpen() {
DocumentApp.getUi()
.createMenu('AI Audit Tools')
.addItem('Run AI Audit', 'runAuditAndInsert')
.addToUi();
}
/**
* Returns the entire text content of the document.
*/
function getDocumentText() {
const doc = DocumentApp.getActiveDocument();
const body = doc.getBody();
let text = body.getText();
return text.trim();
}
/**
* Runs the AI Audit and inserts the result as text at the end of the document.
*/
function runAuditAndInsert() {
const docText = getDocumentText();
const result = runAudit(docText);
if (result) {
const doc = DocumentApp.getActiveDocument();
const body = doc.getBody();
// Append the audit result as a new paragraph at the end of the document
body.appendParagraph('AI Audit Result: ' + result);
}
}
/**
* Runs the AI Audit using ADK Agent and Gemini formatting.
*/
function runAudit(docText) {
console.log('[INFO] Starting AI audit process...');
if (!docText) {
console.log('[WARN] No text in document.');
return '⚠️ The document is empty. Please add some text to audit.';
}
// Check for excessive document length to avoid token limits
if (docText.length > 10000) {
console.log('[WARN] Document too long.');
return '⚠️ Document exceeds 10,000 characters. Please shorten the text.';
}
console.log('[STEP] Sending text to ADK Agent...');
const rawAudit = requestLlmAuditorAdkAiAgent(docText);
// Check if rawAudit is an error message
if (rawAudit.startsWith('ERROR:')) {
console.error('[ERROR] ADK Agent returned error:', rawAudit);
return rawAudit;
}
console.log('[STEP] Formatting AI response...');
let formatted;
try {
formatted = requestOutputFormatting(
`Here is a fact-checking result: ${rawAudit}.
Summarize it. Keep the main verdict and reasoning. Remove markdown and make it concise.`
);
} catch (error) {
console.error('[ERROR] Formatting failed:', error.toString());
return `ERROR: Failed to format audit result - ${error.toString()}`;
}
console.log('[SUCCESS] Audit completed successfully.');
console.log('[RESULT] Final Output:', formatted);
return formatted;
}
이 파일은 Docs UI를 위의 ADK 논리와 연결합니다. 맞춤 Docs 메뉴에서 직접 감사를 트리거할 수 있습니다. 개략적으로 다음을 수행합니다.
- Google Docs에 AI 감사 도구라는 맞춤 메뉴를 추가합니다.
- 문서 텍스트를 가져와 분석을 위해 ADK 에이전트로 전송합니다.
- AI 생성 감사 결과를 문서에 다시 표시합니다.
3단계 : 서비스 계정 만들기
에이전트 호출 기능을 Google 문서에 통합할 때 에이전트 엔진에 배포된 에이전트를 호출할 수 있는 올바른 역할을 갖도록 Google 문서에 ID를 제공해야 합니다. 이를 위해 올바른 역할(roles/aiplatform.user)이 있는 서비스 계정을 사용합니다.
Cloud Shell에서 다음 스크립트를 단계별로 실행합니다.
export PROJECT_ID="YOUR_PROJECT_ID"
export SA_NAME="docfactcheckeragentsa"
gcloud iam service-accounts create $SA_NAME \
--project=$PROJECT_ID \
--display-name="Doc Fact Checker Agent Service Account"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/iam.serviceAccountTokenCreator"
이렇게 하면 올바른 권한이 있는 서비스 계정이 생성됩니다.
서비스 계정의 JSON 키가 생성됩니다. Apps Script 프로젝트에서 인증에 사용할 항목입니다. 키를 가져오는 단계는 다음과 같습니다.
- Google Cloud 콘솔에서 IAM 및 관리자 > 서비스 계정으로 이동합니다.
- 방금 만든 특정 서비스 계정을 클릭합니다.
- '키' 탭으로 이동합니다.
- 키 추가 → 새 키 만들기를 클릭합니다.
- JSON을 선택한 다음 '만들기'를 클릭합니다.
- JSON 파일이 자동으로 다운로드되므로 안전하게 보관해야 합니다. 다음 섹션에서 이 콘텐츠를 스크립트 속성에 붙여넣습니다.
4단계 : 스크립트 속성 추가
Google 문서의 Apps Script 편집기로 돌아갑니다.
스크립트를 배포된 리소스에 연결하려면 Project Settings → Script Properties → Add Script Property로 이동하세요.
스크립트 속성에 다음을 추가합니다.
LOCATION: Vertex AI 배포의 리전입니다. 예:us-central1GEMINI_MODEL_ID: 사용할 Gemini 모델입니다.gemini-2.5-flash값을 사용합니다.REASONING_ENGINE_ID: 배포된 ADK 에이전트 ID입니다. 이는 배포한 특정 에이전트의 콘솔에 있는 Agent Engine 옵션에서 확인할 수 있습니다. 배포된 에이전트의 리소스 이름이 표시됩니다. 상담사 ID는 리소스 이름의 마지막 숫자 값 (즉,RESOURCE_ID)입니다. 예를 들어projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID입니다.SERVICE_ACCOUNT_KEY: 이전 단계에서 만든 서비스 계정에 대해 다운로드한 JSON 키의 전체 콘텐츠를 복사합니다.
스크립트 속성 저장을 클릭합니다.
5단계 : OAuth2 라이브러리 추가
API 호출을 인증하려면 Apps Script 프로젝트에 OAuth2 라이브러리가 필요합니다.
추가하려면 다음 단계를 따르세요.
Services → Libraries(으)로 이동Add a Library를 클릭합니다.- 스크립트 ID(
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF)를 입력합니다.
6단계 : Google Docs에서 Fact Checker Doc Agent 테스트하기
이제 Google Docs 내에서 에이전트를 테스트하는 마지막 단계입니다. 이렇게 하려면 다음 단계를 따르세요.
- Apps Script 편집기에서
onOpen()함수를 한 번 실행합니다. 이렇게 하면 Google Docs에 새로운 AI 감사 도구 메뉴가 추가됩니다. - 문서로 돌아갑니다. 기본 메뉴에
AI Audit Tools이라는 추가 메뉴 항목이 표시됩니다. 이 버튼을 클릭한 다음Run AI Audit을 클릭합니다.
다음은 샘플 실행입니다.
6. 삭제
Google Cloud 계정에 지속적으로 요금이 청구되지 않도록 하려면 이 워크숍에서 만든 리소스를 삭제해야 합니다.
더 이상 에이전트 엔진에 에이전트를 배포할 필요가 없는 경우 아래 단계에 따라 삭제할 수 있습니다.
- Google Cloud 콘솔에서 Vertex AI Agent Engine 페이지로 이동합니다.
- 배포된 에이전트 목록에서 삭제할 에이전트를 찾습니다.
- 에이전트 이름 옆에 있는 점 3개로 된 메뉴 (추가 작업)를 클릭합니다.
- 드롭다운 메뉴에서 삭제를 선택합니다.
- 확인 대화상자에서 에이전트 삭제를 클릭하여 삭제를 확인합니다.
서비스 계정도 삭제하는 것이 좋습니다.
gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
7. 축하합니다
이제 AI 에이전트를 배포하고, Google Docs에 연결하고, 콘텐츠가 있는 곳에서 바로 분석, 추론, 요약하는 모습을 확인했습니다. 여기에서 빌드한 것은 독립형 데모가 아닙니다. Google Workspace 내에서 지능적이고 상담사 중심의 공동작업을 위한 기반이 됩니다.
ADK의 추론 기능과 Gemini의 생성형 모델을 결합하여 Google Docs를 살아있는 사고형 어시스턴트로 효과적으로 전환했습니다. 이제 Google Docs는 맥락을 파악하여 텍스트를 읽고, 감사하고, 다듬을 수 있습니다.
동일한 청사진이 Sheets, Slides, Drive, Gmail로 자연스럽게 확장됩니다. 다음과 같은 에이전트를 상상해 보세요.
- Sheets에서 재무 데이터를 감사하고 불일치 항목을 신고하기
- Slides에서 추천 자료 및 요약 자동 생성
- Drive에서 문서를 지능적으로 라벨 지정하고 정리하기
- Gmail에서 바로 이메일을 작성하고 사실을 확인할 수도 있습니다.
이 데모는 일상적인 Workspace 도구에 원활하게 통합되는 에이전트형 워크플로를 구축하여 정적인 문서를 동적인 AI 협업자로 전환하기 위한 기반을 마련합니다.