1. Introdução
O Google Workspace é onde o trabalho acontece. Desde a criação de relatórios nos Documentos até a análise de dados nas Planilhas e a colaboração no Gmail e no Meet.
Agora imagine se os apps Documentos, Planilhas e Gmail não fossem apenas ferramentas, mas colaboradores.
Com a ajuda do Kit de Desenvolvimento de Agente (ADK) do Google e do Agent Engine da Vertex AI, isso não é mais apenas uma ideia. Vamos usar essas estruturas para criar um agente inteligente, implantá-lo em grande escala e integrá-lo perfeitamente às nossas ferramentas do Google Workspace, inaugurando uma nova era de produtividade de agentes.
Neste codelab, você vai usar uma abordagem gradual da seguinte forma:
- Desenvolva o agente de verificação de fatos de IA usando o Kit de Desenvolvimento de Agente.
- Implante o agente no Agent Engine, um ambiente totalmente gerenciado para executar agentes em grande escala.
- Integre esse agente ao Documentos Google para fazer a checagem de fatos do texto no documento.
Confira abaixo um diagrama conceitual que explica como a solução final funciona:
Esta é uma saída final de como o agente de verificação de fatos funciona em um documento Google. Havia um texto original com algumas declarações, e ele faz uma verificação de fatos para cada uma delas. A saída vinculada na caixa com o canto vermelho é a saída do agente.
O que você aprenderá
- Projete, crie e implante um agente que faça checagem de fatos em um documento Google.
O que você vai aprender
- Desenvolver um agente usando o Kit de Desenvolvimento de Agente (AK).
- Teste o agente localmente e implante-o no Agent Engine.
- Integrar o agente a um documento do Google Workspace (Documentos Google).
O que é necessário
- Navegador da Web Google Chrome
- Uma conta do Gmail
- Um projeto do Cloud com faturamento ativado
Este codelab, criado para desenvolvedores de todos os níveis (incluindo iniciantes), usa Python e Apps Script no código de exemplo. No entanto, o conhecimento dessas linguagens de programação não é um pré-requisito, e a capacidade básica de leitura de código será suficiente para entender os conceitos apresentados.
2. Antes de começar
Criar um projeto
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .
- Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com bq. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.
- Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com seu ID do projeto usando o seguinte comando:
gcloud auth list
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
- Se o projeto não estiver definido, use este comando:
gcloud config set project <YOUR_PROJECT_ID>
- Ative as APIs necessárias com o comando mostrado abaixo. Isso pode levar alguns minutos.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Após a execução do comando, você vai receber uma mensagem semelhante à mostrada abaixo:
Operation "operations/..." finished successfully.
Se alguma API for esquecida, você sempre poderá ativá-la durante a implementação.
Consulte a documentação para ver o uso e os comandos gcloud.
3. Como criar o agente do ADK
Vamos criar o agente do ADK (Document Fact Checker Agent), um auditor baseado em IA que checa fatos em textos, inspirado na amostra da função personalizada de checagem de fatos do Google. Ao contrário da abordagem de uma única etapa do exemplo, nosso agente usa o raciocínio de várias etapas para extrair declarações, verificá-las com o google_search e gerar JSON estruturado.
Etapa 1 : instalar o Kit de Desenvolvimento de Agente
Abra uma nova guia do terminal no Cloud Shell e crie uma pasta chamada my-agents da seguinte maneira. Navegue até a pasta my-agents também.
mkdir workspace-agents
cd workspace-agents
Agora, vamos criar um ambiente Python virtual usando venv da seguinte maneira:
python -m venv .venv
Ative o ambiente virtual da seguinte maneira:
source .venv/bin/activate
Instale o ADK da seguinte maneira:
pip install google-adk
Agora você pode invocar o utilitário adk da seguinte maneira.
adk
Uma lista de comandos vai aparecer.
$ 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.
Etapa 2 : desenvolver o agente de verificação de fatos de documentos usando o ADK
Agora vamos usar adk para criar uma estrutura para nosso agente usando o comando adk create com o nome do app **(docfactcheckeragent)**, conforme mostrado abaixo.
adk create docfactcheckeragent
Siga as etapas e selecione o seguinte:
- Modelo do Gemini para escolher um modelo para o agente raiz.
- Escolha a Vertex AI para o back-end.
- O ID e a região padrão do projeto do Google vão aparecer. Selecione o padrão.
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
Observe a pasta em que um modelo padrão e os arquivos necessários para o agente foram criados.
Primeiro, o arquivo .env. O conteúdo dele é mostrado abaixo:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Os valores indicam que vamos usar o Gemini pela Vertex AI com os respectivos valores do ID e local do projeto do Google Cloud.
Em seguida, temos o arquivo __init__.py, que marca a pasta como um módulo e tem uma única instrução que importa o agente do arquivo agent.py.
from . import agent
Por fim, há o arquivo agent.py. Substitua o conteúdo do arquivo agent.py pelo código abaixo:
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
)
Os pontos principais do código-fonte acima são:
- Definimos o agente de IA um nome a ele, seguido pelo modelo, descrição e um conjunto de instruções muito detalhado.
- O conjunto de instruções é a parte mais importante que define exatamente como o agente deve pensar e operar. Essa estrutura espelha o trabalho de verificadores de fatos profissionais, transformando a IA em um pipeline de auditoria autônomo.
- Depois de concluir essa declaração, vamos dar ao agente acesso a informações do mundo real usando o
Google Search tool. Em vez de depender de dados pré-treinados, o agente pode fazer pesquisas em tempo real, avaliar resultados e fornecer citações atualizadas.
É isso que torna esse sistema agente: o modelo não apenas gera respostas, mas também realiza ações (usando ferramentas) para verificar informações.
Etapa 3 : testar o agente localmente
Na janela de terminal aberta, execute o seguinte comando. Confirme se você está na pasta mãe (workspace-agents) que contém a pasta docfactcheckeragent.
adk web
Confira um exemplo de execução abaixo:
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)
Clique no último link para abrir um console da Web e testar o agente. Nossa primeira interação é fundamental: entender o que o agente pode fazer. Isso testa a capacidade dele de resumir o description e o instruction text.
O agente oferece um resumo conciso das próprias habilidades, com base na descrição e no conjunto de instruções.
Em seguida, fornecemos duas declarações (The sky is blue due to Rayleigh scattering. The Earth is flat.), e ele audita o conteúdo e retorna uma resposta JSON bem estruturada.
Em segundo plano:
- A ferramenta google_search busca páginas relevantes na Web.
- O modelo Gemini 2.5 Flash analisa esses snippets e classifica a veracidade.
- O ADK processa a orquestração de raciocínio e garante que a lógica seja seguida etapa por etapa.
Essa fase de teste local ajuda a validar o fluxo de trabalho do nosso agente antes de implantá-lo no Vertex AI Agent Engine, onde ele pode ser conectado a ferramentas do Google Workspace, como Documentos ou Planilhas.
Em resumo, criamos um agente de auditoria de IA eficiente usando o Kit de Desenvolvimento de Agente (ADK) do Google. Nosso agente conseguiu ler texto, identificar declarações factuais, pesquisar fontes confiáveis (usando a ferramenta google_search) e retornar um veredito claro.
Criamos e testamos tudo localmente pela interface da Web do ADK e vimos como o agente analisou uma declaração como:
The sky is blue due to Rayleigh scattering. The Earth is flat.
O agente verificou uma declaração como true e sinalizou a outra como false, uma prova pequena, mas adequada, de que nossa configuração local funciona perfeitamente.
Agora é hora de dar o próximo grande passo: migrar do local para a nuvem. Vamos fazer isso em seguida.
4. Implantar o agente no Vertex AI Agent Engine
Um agente real não é apenas algo que você testa no laptop, mas algo que pode ser executado em grande escala, integrado a outros sistemas e implantado para produção em todos os seus apps.
Por que usar o Deploy?
Confira alguns bons motivos para implantar seus agentes na nuvem.
- Escalabilidade: processe solicitações de alto volume sem limites de tempo de execução local.
- Confiabilidade: monitoramento e escalonamento automático integrados, com correções como a atualização da configuração da ferramenta ADK de 18 de outubro de 2025.
- Pronto para integração: exponha um endpoint de API para chamadas do Workspace sem problemas.
Por que usar o Vertex AI Agent Engine?
Pense no Vertex AI Agent Engine como a casa dos seus agentes do ADK implantados, um ambiente gerenciado criado para confiabilidade, escalonabilidade e integração.
Ele oferece ao seu agente:
- Estado e memória persistentes
- Execução de ferramentas integradas (por exemplo, Pesquisa Google, modelos da Vertex AI)
- Proteger endpoints de API para chamadas externas
- Registro e observabilidade com o Cloud Logging
- Suporte nativo para orquestração de vários agentes
Em resumo, você escreve uma vez com o ADK e depois aumenta a escala usando o Agent Engine.
Etapa 1 : configurar para implantação
Precisamos fazer algumas coisas antes de implantar o agente do Vertex AI Agent Engine. O processo de implantação exige a criação de um bucket do Google Cloud Storage para os artefatos do agente. Também precisamos fornecer um arquivo requirements.txt para que todas as dependências necessárias para executar o código do agente estejam disponíveis no ambiente de execução do Agent Engine.
No terminal do Cloud Shell, execute o comando a seguir para criar um bucket. Não se esqueça de substituir YOUR_BUCKET_NAME, YOUR_PROJECT_ID e YOUR_PROJECT_REGION por valores reais específicos do seu projeto:
gcloud storage buckets create gs://YOUR_BUCKET_NAME \
--project=YOUR_PROJECT_ID \
--location=YOUR_PROJECT_REGION
Em seguida, crie o arquivo requirements.txt a seguir na pasta raiz (workspace-agents), cujo conteúdo é mostrado abaixo:
google-cloud-aiplatform
google-adk
requests
Etapa 2 : implante o agente
A próxima etapa é implantar o agente no Vertex AI Agent Engine usando o comando adk deploy.
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/
Isso vai iniciar um processo para implantar nosso agente no Agent Engine. O processo é demorado e pode levar aproximadamente 5 minutos. Em geral, isto é o que acontece:
- A criação do agente começa. A CLI do ADK empacota seu código, faz upload dele para o bucket do Cloud Storage e aciona a Vertex AI para criar uma nova instância do Agent Engine.
- Você recebe um link "Registros", em que pode conferir o Explorador de registros do Cloud para seu projeto. Clique nele para conferir o progresso detalhado, incluindo etapas de configuração, instalação de dependências e inicialização do modelo. Se algo der errado (como uma dependência ausente ou um problema de permissão), a mensagem de erro vai aparecer aqui.
- Mensagem de conclusão: quando a implantação for concluída, uma mensagem de confirmação vai aparecer no terminal com seu ID do Reasoning Engine. Confira um exemplo abaixo:
AgentEngine created. Resource name: projects/SOME_ID/locations/REGION/reasoningEngines/SOME_ID
Etapa 3 : verificar o agente no Console do Cloud (mecanismo de agente)
Depois que a implantação for concluída, acesse a seção Vertex AI → Agent Engine do console do Google Cloud. O agente implantado vai aparecer no console, conforme mostrado abaixo:
🎉 Pronto! Seu agente já está disponível na Vertex AI e pronto para ser integrado ao Google Workspace ou testado diretamente.
Etapa 4 : testar o agente de implantação
Parabéns! Seu agente está ativo no Vertex AI Agent Engine. A próxima etapa é testar se ele foi implantado corretamente e está respondendo às solicitações.
Há algumas maneiras de fazer isso, dependendo da sua preferência:
- Pelo console do Google Cloud: uma interface visual para ver, gerenciar e testar seus agentes implantados diretamente.
- Usando a API REST (cURL): ideal para desenvolvedores que querem enviar solicitações manualmente e inspecionar respostas.
- Com o SDK da Vertex AI para Python: uma opção mais programática para integrar testes ao seu fluxo de trabalho de desenvolvimento.
Cada abordagem oferece insights sobre o comportamento do agente depois da implantação, ou seja, se ele está processando consultas, gerenciando sessões ou retornando respostas. Para conferir etapas detalhadas, exemplos e configurações avançadas de cada método, consulte a documentação oficial aqui.
Seu auditor de IA agora é um agente com tecnologia de nuvem, implantado no Vertex AI Agent Engine e pronto para verificar fatos em grande escala com o google_search. Ele é transformado em um colega de trabalho digital confiável e orientado por API, gerando JSONs como:
{ "claims": [{"claim": "The sky is blue...", "verdict": "True", "confidence": 95}] }
Vamos testar isso diretamente na próxima seção, em que vamos integrar o agente em um documento do Google e validar os fatos declarados nele.
5. Integrar o agente de checagem de fatos aos Documentos Google
Nesta seção, vamos conectar tudo, trazendo o agente implantado para dentro do Google Docs. Com algumas linhas do Apps Script, você transforma um documento padrão do Google em um editor com tecnologia de IA que pode analisar e verificar fatos automaticamente usando seu agente implantado.
Etapa 1: configurar seu ambiente dos Documentos Google
Comece abrindo um documento Google novo ou já existente (docs.new).
O documento Google que estamos usando neste tutorial contém o seguinte conteúdo (você pode usar esse ou seu próprio conteúdo que planeja verificar):
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.
Etapa 2: configurar o projeto e os arquivos do Apps Script
Você vai precisar de dois arquivos no projeto do Apps Script para essa configuração:
AIVertex.gs: processa toda a comunicação com a Vertex AI e o agente do ADK.Code.gs: controla a interface, os menus e as ações do documento nos Documentos Google.
No menu, acesse Extensions -> Apps Script para abrir o editor. Vamos usar esse espaço para nos conectar ao agente do ADK implantado. Você vai encontrar um arquivo Code.gs já criado e precisará substituir o conteúdo dele pelo código Code.gs fornecido na próxima seção.
Vamos analisar cada uma delas.
AIVertex.gs
Crie um novo arquivo usando o sinal de + ao lado da seção "Arquivos" à esquerda, selecione-o como Script e copie o conteúdo a seguir nele.
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(),
}
}
Não se esqueça de salvar o arquivo.
Esse arquivo faz o seguinte:
- Autentica com segurança na Vertex AI usando uma chave de conta de serviço. Ele invoca o agente do ADK implantado para analisar ou verificar os fatos no texto do documento.
- Usa o Gemini para formatar respostas inteligentes , tornando os resultados legíveis para humanos.
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;
}
Esse arquivo conecta a interface do usuário do Google Docs com a lógica do ADK acima. Ele permite acionar a auditoria diretamente em um menu personalizado do Documentos. Em geral, ele faz o seguinte:
- Adiciona um menu personalizado aos Documentos Google chamado "Ferramentas de auditoria de IA".
- Extrai o texto do documento e o envia ao agente do ADK para análise.
- Mostra os resultados da auditoria gerados com IA no documento.
Etapa 3 : criar uma conta de serviço
Ao integrar a funcionalidade de chamada do agente a um Documento Google, precisamos fornecer uma identidade a ele para que tenha a função correta de invocar o agente implantado no Agent Engine. Para isso, vamos usar uma conta de serviço com o papel correto: roles/aiplatform.user.
No Cloud Shell, execute o script a seguir, etapa por etapa:
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"
Isso vai criar a conta de serviço com as permissões corretas.
Vamos gerar uma chave JSON para a conta de serviço. É o que seu projeto do Apps Script vai usar para autenticar. Para conseguir a chave, siga estas etapas:
- No console do Google Cloud, acesse IAM e administrador > Contas de serviço.
- Clique na conta de serviço específica que você acabou de criar.
- Acesse a guia "Chaves".
- Clique em "Adicionar chave" → "Criar nova chave".
- Selecione JSON e clique em "Criar".
- Um arquivo JSON será baixado automaticamente. Mantenha-o em segurança. Você vai colar o conteúdo dele nas propriedades de script na próxima seção.
Etapa 4 : adicionar propriedades do script
Volte ao editor do Apps Script no Documentos Google.
Para conectar o script aos recursos implantados, acesse Project Settings → Script Properties → Add Script Property.
Adicione o seguinte às propriedades do script:
LOCATION: a região da sua implantação da Vertex AI. Por exemplo,us-central1GEMINI_MODEL_ID: modelo do Gemini a ser usado. Use o valor:gemini-2.5-flashREASONING_ENGINE_ID: o ID do agente do ADK implantado. Ele pode ser obtido na opção "Agent Engine" no console do agente específico que você implantou. Você vai encontrar um nome de recurso para o agente implantado. O ID do agente é o último valor numérico no nome do recurso (ou seja,RESOURCE_ID). Por exemplo,projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_IDSERVICE_ACCOUNT_KEY: copie todo o conteúdo da chave JSON que você baixou para a conta de serviço criada na etapa anterior.
Clique em Salvar propriedades do script.
Etapa 5 : adicionar a biblioteca OAuth2
Nosso projeto do Apps Script precisa da biblioteca OAuth2 para autenticar chamadas de API.
Para adicionar:
- Acessar
Services → Libraries - Clique em
Add a Library. - Insira o ID do script:
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
Etapa 6 : testar o agente de documentos do Fact Checker nos Documentos Google
Estamos na etapa final para testar o agente no Documentos Google. Para isso, faça o seguinte:
- No editor do Apps Script, execute a função
onOpen()uma vez. Isso vai adicionar um novo menu de ferramentas de auditoria de IA nos Documentos Google. - Volte ao documento. Você vai encontrar um item de menu adicional no menu principal chamado
AI Audit Tools. Clique nele e emRun AI Audit.
Confira um exemplo de execução:
6. Limpeza
Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este workshop.
Se você não precisar mais que o agente seja implantado no Agent Engine, exclua-o seguindo as etapas abaixo:
- Navegue até a página Vertex AI Agent Engine no console do Google Cloud.
- Localize o agente que você quer excluir na lista de agentes implantados.
- Clique no menu de três pontos (mais ações) ao lado do nome do agente.
- Selecione Excluir no menu suspenso.
- Confirme a exclusão clicando em Excluir agente na caixa de diálogo de confirmação.
Como prática recomendada, exclua também a conta de serviço.
gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
7. Parabéns
Agora você implantou seu agente de IA, conectou ele ao Google Docs e o viu em ação: analisando, raciocinando e resumindo exatamente onde seu conteúdo está. O que criamos aqui não é apenas uma demonstração independente. É a base para uma colaboração inteligente e orientada por agentes no Google Workspace.
Ao combinar os recursos de raciocínio do ADK com os modelos generativos do Gemini, transformamos os Documentos Google em um assistente vivo e inteligente, capaz de ler, auditar e refinar seu texto com contexto.
O mesmo projeto se estende naturalmente aos apps Planilhas, Apresentações, Drive e Gmail. Imagine agentes que:
- Auditar dados financeiros e sinalizar inconsistências nas Planilhas
- Gerar automaticamente apresentações e resumos no app Apresentações
- Marcar e organizar documentos de forma inteligente no Drive
- Ou até mesmo escrever e checar fatos diretamente no Gmail
Esta demonstração estabelece as bases para a criação de fluxos de trabalho baseados em agentes que se integram perfeitamente às suas ferramentas diárias do Workspace, transformando documentos estáticos em colaboradores dinâmicos de IA.