1. Introdução
Neste codelab, você vai criar seu primeiro agente de IA usando o Kit de Desenvolvimento de Agente (ADK) do Google e o Gemini. Você vai criar um agente básico de escrita de blogs que planeja e escreve conteúdo, mostrando os conceitos principais de raciocínio e ação.
Atividades deste laboratório
- Configure o ambiente de desenvolvimento do ADK.
- Crie um sistema multiagente com um planejador e um escritor.
- Execute o agente localmente e interaja com ele pela interface da web do ADK.
O que é necessário
- Um navegador da Web, como o Chrome.
- Python 3.10 ou mais recente instalado na sua máquina.
- Uma chave de API do Google AI Studio.
Este codelab é destinado a desenvolvedores de todos os níveis, inclusive iniciantes.
Duração estimada: 30 minutos.
2. Guia visual: o que são agentes de IA?
Antes de começar a criar, vamos entender rapidamente o que são agentes de IA e os padrões comuns que eles seguem.
O que é um agente de IA?
No nível mais simples, um agente é um software que não apenas responde, mas também pode decidir e agir. Em vez de gerar uma única resposta como um chatbot tradicional, ele analisa sua solicitação, descobre quais etapas seguir, talvez chame uma API, execute um código, analise o resultado e decida o que fazer em seguida.
Uma das explicações mais claras vem do artigo de pesquisa ReAct: Synergizing Reasoning and Acting in Language Models. A ideia desse artigo era simples, mas poderosa: os modelos de linguagem não devem apenas gerar texto de uma só vez. Eles podem raciocinar etapa por etapa, realizar uma ação como chamar uma ferramenta ou API, observar o resultado e decidir o que fazer em seguida.
Esse ciclo de raciocínio, ação, observação e ajuste é a base de como os agentes de IA modernos funcionam. E isso se alinha à definição do Google Cloud: sistemas com raciocínio, planejamento e memória, com autonomia suficiente para se adaptar e tomar decisões em nome do usuário.
Três padrões de comportamento do agente
Nem todos os agentes se comportam da mesma maneira. Uma forma útil de pensar neles é em três padrões gerais:
- Agentes sequenciais: eles são executados etapa por etapa, como uma linha de montagem: etapa 1, etapa 2, etapa 3. Eles são previsíveis, mas rígidos.
- Agentes reativos: tomam decisões no momento. Eles analisam o estado atual e perguntam: "O que devo fazer agora?" Talvez a Ferramenta A uma vez e a Ferramenta B na próxima. São flexíveis, mas não planejam com antecedência.
- Agentes deliberativos ou de planejamento: eles fazem uma pausa para esboçar um plano e depois o executam. Pense em reservar uma viagem: você não compra um voo aleatoriamente, escolhe datas, hotéis, ordena as etapas e segue em frente.
Qual deles é o "certo"? Depende do problema. Para fluxos simples e previsíveis, o sequencial é adequado. Para tarefas dinâmicas, o reativo funciona melhor. Para metas de várias etapas com dependências, use agentes de planejamento.
Neste laboratório, vamos criar um agente deliberativo/de planejamento que primeiro cria um esboço e depois escreve a postagem do blog.
3. Antes de começar
Criar uma conta e um projeto do Google Cloud
Para implantar o agente no Google Cloud Run mais tarde neste laboratório, você precisa de uma conta do Google Cloud e um projeto com o faturamento ativado.
- Faça login no Console do Google Cloud. Crie um projeto ou reutilize um existente. Se você ainda não tem uma Conta do Google, crie uma.
- Em seguida, ative o faturamento no console do Cloud para usar os recursos do Cloud. A execução deste codelab custa menos de alguns centavos. Novos usuários do Google Cloud também podem se qualificar para o programa de US$300 de avaliação sem custos.
- Anote o ID do projeto, um nome exclusivo em todos os projetos do Google Cloud. Você vai precisar dele para configurar e implantar o agente.
Receber uma chave de API do Google AI Studio
Para usar os modelos do Gemini, você precisa de uma chave de API do Google AI Studio.
- Acesse o Google AI Studio.
- Clique em Receber chave de API.
- Crie uma chave ou use uma já existente. Copie a chave para uso posterior.
4. Criar a estrutura do projeto do agente de redação de blog
Nesta etapa, você vai configurar o diretório e os arquivos para hospedar o código do agente de escrita de blogs na sua máquina local.
1. Criar o espaço de trabalho do agente de escrita de blogs
Abra o terminal e execute os comandos a seguir para criar um diretório dedicado ao seu agente de redação de blog e navegue até ele:
mkdir bloggeragent
cd bloggeragent
2. Inicializar os arquivos do agente
O framework ADK do Google carrega fluxos de trabalho do agente diretamente do diretório do projeto. Crie os arquivos necessários diretamente na raiz de bloggeragent:
touch requirements.txt .env __init__.py agent.py
5. Instalar dependências e configurar o ambiente
Nesta etapa, você vai configurar um ambiente virtual do Python, instalar o framework ADK do Google e configurar variáveis de ambiente para autenticar seu agente de blog com o modelo do Gemini.
1. Configurar os requisitos do agente
Abra o arquivo requirements.txt no diretório bloggeragent e especifique os pacotes necessários para o agente de escrita de blogs adicionando o seguinte:
google-adk==2.2.0
python-dotenv
2. Criar um ambiente virtual para o agente
No diretório bloggeragent, crie e ative um ambiente virtual Python para isolar os pacotes do agente:
python3 -m venv .venv
source .venv/bin/activate
3. Instalar o framework do ADK
Instale as dependências definidas no requirements.txt para equipar seu espaço de trabalho local com o ADK do Google:
pip install -r requirements.txt
4. Configurar credenciais da API do agente
Abra o arquivo .env que você criou na raiz do projeto e adicione sua chave de API Gemini:
GOOGLE_API_KEY=your_api_key
Substitua your_api_key pela chave que você copiou do Google AI Studio.
6. Criar o gravador de blog multiagente
Nesta etapa, você vai implementar o fluxo de trabalho principal do sistema de agente de redação de blogs.
Em vez de um simples chatbot de comando único, você vai criar um sistema multiagente complexo que usa loops de autocorreção e verificação de estrutura para escrever postagens técnicas de alta qualidade. Isso segue o padrão Deliberativo/Planejamento que discutimos anteriormente.
Visão geral da arquitetura
Veja como os agentes especialistas no seu sistema interagem:
Configurar init.py
Abra __init__.py no editor de texto e adicione a seguinte importação para expor o fluxo de trabalho do agente ao executor:
from . import agent
Escrever o fluxo de trabalho do agente de escrita de blog
Abra agent.py no editor de código e adicione o seguinte código, que define o Planner, o Writer, os Validation Checkers e o principal agente do Blogger:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Noções básicas sobre a arquitetura do agente
Vamos analisar os principais componentes do código que você acabou de adicionar em agent.py para entender como ele implementa o fluxo de trabalho de planejamento e escrita multiagente:
1. O subagente do BlogPlanner
O agente blog_planner é responsável pelo planejamento de conteúdo. Ele usa o tema fornecido pelo usuário e produz um esboço estruturado em Markdown (com um título, uma introdução, de quatro a seis seções e uma conclusão). O contorno é salvo no dicionário de estado compartilhado com a chave "blog_outline".
2. O OutlineValidationChecker
O agente OutlineValidationChecker atua como um gate de qualidade. Ele revisa o "blog_outline" gerado no estado. Se o esboço for válido, a resposta será "ok". Caso contrário, ele vai retornar "retry" e uma lista do que está faltando.
3. Loop RobustBlogPlanner
Para evitar que o agente produza planos ruins, envolvemos o planejador e o verificador de validação em um LoopAgent chamado robust_blog_planner. Se a validação falhar e retornar "retry", o loop vai executar o planejador automaticamente de novo, até três vezes, garantindo a autocorreção antes de passar para a próxima etapa.
4. O subagente BlogWriter
Depois que o roteiro é finalizado, o agente blog_writer lê "blog_outline" do estado e gera o artigo técnico completo em Markdown, correspondendo à estrutura do roteiro e adaptando-o para engenheiros de software.
5. O loop BlogPostValidationChecker e RobustBlogWriter
Assim como o esboço, o artigo final é validado pelo BlogPostValidationChecker para garantir que todas as seções principais estejam presentes e claras. O gravador e o verificador estão envolvidos no loop robust_blog_writer, permitindo que ele se autocorrige até três vezes se o verificador encontrar problemas.
6. Expor loops como ferramentas
Encapsulamos o loop do planejador (robust_blog_planner) e o loop do gravador (robust_blog_writer) como ferramentas (planner_tool e writer_tool) usando AgentTool. Isso permite que outros agentes chamem esses fluxos de trabalho complexos como se fossem ferramentas simples.
7. Agente raiz do Blogger
O root_agent (chamado de Blogger) orquestra todo o fluxo de trabalho. Quando recebe um tema, as instruções orientam a IA a:
- Chame
planner_toolpara gerar o esquema validado. - Chame o
writer_toolpara escrever o rascunho com base nesse esboço. - Para concluir, gere três títulos alternativos e dois ganchos para tweets.
Essa arquitetura de loop multiagente garante a confiabilidade ao detectar e corrigir erros de formatação ou estruturais do LLM antes de mostrar a saída ao usuário.
7. Executar e testar o agente
Agora é hora de ver seu agente em ação.
1. Iniciar a interface da web do ADK
Verifique se você está no diretório raiz do projeto bloggeragent no terminal e se o ambiente virtual está ativo (source .venv/bin/activate). Em seguida, inicie a interface da Web:
adk web
2. Interagir com o agente
- Abra o navegador e acesse
http://127.0.0.1:8000(ou a porta especificada). - A interface da web do ADK vai aparecer com o agente
Bloggercarregado e o layout visual dele (mostrando o agente raiz do Blogger apontando para as ferramentas RobustBlogPlanner e RobustBlogWriter):
- Digite um tema técnico na caixa de mensagem e pressione Enter. Confira alguns comandos de teste interessantes que você pode usar para avaliar seu agente:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- Assista o rastreamento de execução na interface. Você vai ver o
BlogPlannercriar o esboço, oOutlineValidationCheckervalidar e oBlogWriterescrever o rascunho final com base no esboço:
8. Implantar no Cloud Run
Agora que você verificou que o agente funciona localmente, vamos implantá-lo no Google Cloud Run para que outras pessoas possam usá-lo.
O Google Cloud Run é uma plataforma de computação gerenciada que permite executar contêineres sem estado que podem ser invocados por meio de solicitações da Web ou eventos do Pub/Sub.
1. Pré-requisitos para implantação
Para implantar o agente de escrita de blogs no Cloud Run, instale e autentique a CLI do Google Cloud (gcloud) na sua máquina local:
- Instale a CLI do Google Cloud: se você ainda não tiver instalado, siga o Guia de Instalação da CLI do Google Cloud para seu sistema operacional (macOS, Windows ou Linux).
- Autentique seu terminal local: depois de instalado, execute o seguinte comando no terminal para fazer login na sua conta do Google Cloud:
gcloud auth login - Verifique a autenticação: confirme se sua conta fez login corretamente e se você pode acessar os recursos do Google Cloud:
gcloud auth list
2. Configurar projeto do Google Cloud
Defina o projeto ativo no terminal:
gcloud config set project <YOUR_PROJECT_ID>
Ative os serviços necessários do Google Cloud para criar e implantar seu agente contêinerizado:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Como o comando de implantação do ADK usa o Google Cloud Build para automatizar o processo de build, é necessário conceder à conta de serviço de computação padrão permissão para usar o Cloud Build.
Para encontrar o número do projeto, execute:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Execute os comandos a seguir para vincular os papéis necessários do IAM. Substitua
- Conceda permissão ao Cloud Build para criar seu contêiner:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Conceda permissão de acesso ao Gemini Enterprise para que o agente implantado possa invocar modelos do Gemini sem precisar de uma chave de API:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Configurar variáveis de ambiente locais
Para simplificar o comando de implantação e evitar erros de digitação, defina o ID do projeto como uma variável de ambiente na sessão do terminal:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. Implantar usando a CLI do ADK
A CLI do ADK oferece um comando simplificado para implantar seu agente no Cloud Run.
Verifique se o ambiente virtual está ativo e se você está no diretório do projeto bloggeragent. Em seguida, execute o comando de implantação:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
Durante o processo de implantação, você vai receber as duas perguntas a seguir no terminal:
- Confirmar a criação do repositório:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Ye pressione Enter. - Permitir acesso não autenticado:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
ye pressione Enter. Isso permite acessar a interface da web do ADK publicamente no navegador.
5. Acessar o agente implantado
Quando a implantação for concluída, o comando vai gerar um URL. Abra esse URL no navegador para acessar a interface da Web do ADK ativa e acessível publicamente.
9. Limpar
Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.
1. Excluir serviço do Cloud Run
Exclua o serviço bloggeragent implantado:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Excluir o repositório do Artifact Registry
Exclua o repositório do Docker criado para armazenar as imagens de contêiner criadas:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Parar o servidor local
Para interromper o servidor ADK local, pressione CTRL+C no terminal em que ele está sendo executado e desative o ambiente virtual:
deactivate
10. Parabéns
Parabéns! Você criou seu primeiro agente de IA usando o ADK do Google e o Gemini.
O que você aprendeu
- Os principais conceitos dos agentes de IA (raciocínio e ação).
- Como usar o ADK do Google para criar um sistema multiagente.
- Como executar e testar seu agente usando a interface da Web.
Próximas etapas
- Tente adicionar ferramentas ao seu agente, como pesquisa na Web ou chamadas de API.
- Aguarde o vídeo 2, em que vamos integrar um servidor MCP.