O Google ADK é um framework de código aberto para construir, avaliar e implantar agentes de IA, e ele potencializa agentes reais dentro de produtos Google como o Agentspace. Se você já olhou para outras pilhas de agentes, como o OpenAI Agents SDK, o ADK cobre o mesmo terreno enquanto se mantém próximo ao Gemini e ao Vertex AI. Este guia explica o que é o ADK, como suas partes principais se encaixam e onde uma ferramenta como o Apidog ajuda você a testar as APIs que seu agente acaba chamando.
O que é o Google ADK
ADK significa Agent Development Kit (Kit de Desenvolvimento de Agentes). O Google o introduziu no Google Cloud Next em abril de 2025 como um kit de ferramentas de código aberto para o ciclo de vida completo do agente: definir um agente, dar-lhe ferramentas, compor múltiplos agentes, avaliar o comportamento e implantar em produção.
Ele começou Python-first, e o Google desde então adicionou Java, com suporte a Go e TypeScript a seguir. O framework é o mesmo que o Google usa internamente para agentes no Agentspace e em seu Customer Engagement Suite, então não é um SDK de brinquedo. Ele é construído para cargas de trabalho de produção.
O ADK é agnóstico em relação ao modelo, mas otimizado para o Google. Ele funciona melhor com Gemini e qualquer modelo disponível através do Vertex AI Model Garden, e ele se conecta ao LiteLLM para que você possa apontar um agente para Anthropic, Meta, Mistral e outros provedores. Você obtém a integração apertada com o Gemini sem se prender a um único modelo.
Onde o ADK se encaixa no ecossistema Gemini e Vertex AI
Ajuda separar em três camadas:
- O modelo. Gemini (ou outro provedor via Vertex AI Model Garden ou LiteLLM) faz o raciocínio.
- O framework. ADK é a camada de código onde você define agentes, conecta ferramentas e orquestra fluxos multi-agente.
- O runtime. O Vertex AI Agent Engine é o host gerenciado e escalável onde seu agente roda em produção. Você também pode implantar no Cloud Run ou em qualquer runtime de contêiner.
Então o ADK é a camada voltada para o desenvolvedor. Gemini fornece inteligência por baixo, e Vertex AI Agent Engine fornece um lar gerenciado por cima. Você pode usar todos os três juntos, ou rodar o ADK localmente e implantar em outro lugar. Nada o força a um único caminho.
Conceitos Essenciais
Alguns blocos de construção cobrem a maior parte do que você escreverá.
Agentes
A unidade básica é um agente suportado por LLM. Em Python, você o importa de google.adk.agents. A classe é LlmAgent, e Agent é um alias conveniente para ela. Você dá a ele um modelo, um nome, uma instrução que molda seu comportamento e uma lista de ferramentas.
from google.adk.agents import Agent
def get_exchange_rate(base: str, target: str) -> dict:
"""Return the exchange rate between two currencies."""
# call your real FX API here
return {"base": base, "target": target, "rate": 1.08}
currency_agent = Agent(
name="currency_exchange_agent",
model="gemini-2.0-flash",
instruction="You help users convert between currencies. Stick to the facts.",
tools=[get_exchange_rate],
)
Esse é um agente único funcional. A instrução diz a ele o que fazer, e a lista de ferramentas diz o que ele pode chamar.
Ferramentas
Ferramentas são como um agente faz algo além de gerar texto. No ADK, uma função Python simples é uma ferramenta. O nome da função, as dicas de tipo e a docstring dizem ao modelo quando e como chamá-la, então uma docstring clara importa mais do que você esperaria.
Além de suas próprias funções, o ADK inclui ferramentas embutidas como google_search e execução de código, e suporta o Model Context Protocol (MCP) para conectar servidores de ferramentas externos. Você também pode encapsular bibliotecas de terceiros como LangChain ou LlamaIndex, ou usar outro agente como ferramenta. A maioria dos agentes acaba chamando APIs REST externas através dessas ferramentas, que é exatamente onde o teste e a simulação entram em jogo mais tarde.
Sistemas Multiagentes
Um único agente o leva longe, mas o ADK é construído para hierarquias. Você compõe agentes especializados em um sistema maior e deixa um coordenador rotear o trabalho entre eles.
O framework fornece agentes de fluxo de trabalho para controle determinístico: um SequentialAgent executa sub-agentes em ordem, um ParallelAgent os executa ao mesmo tempo e um LoopAgent se repete até que uma condição seja atendida. Misture estes com roteamento impulsionado por LLM e você pode construir um agente de pesquisa que se ramifica para vários sub-agentes e mescla seus resultados.
Executores (Runners)
Você não chama um agente diretamente em produção. Um Runner é o motor de execução do ADK. Ele gerencia a sessão, impulsiona o fluxo de eventos, atualiza o estado, invoca o modelo e coordena as chamadas de ferramentas. Durante o desenvolvimento, você pode pular a burocracia com o CLI: adk run inicia uma sessão interativa de terminal, e adk web abre uma interface de usuário local no navegador para conversar com seu agente e inspecionar cada etapa.
Avaliação e Implantação
O ADK inclui uma estrutura de avaliação para que você possa pontuar um agente contra trajetórias e respostas esperadas, não apenas observar a saída. Isso é importante porque o comportamento do agente muda à medida que você altera prompts, ferramentas ou modelos.
Para implantação, você tem um caminho gerenciado e um caminho portátil. O Vertex AI Agent Engine oferece um tempo de execução totalmente gerenciado e escalável com a infraestrutura cuidada para você. Se preferir manter a portabilidade, empacote o agente em um contêiner e envie-o para o Cloud Run ou qualquer plataforma de contêiner.
Um exemplo de alto nível
Aqui está a forma de uma pequena configuração multiagente. Um coordenador delega a dois especialistas.
from google.adk.agents import Agent
flights = Agent(
name="flight_agent",
model="gemini-2.0-flash",
instruction="Find flight options for the user's route and dates.",
tools=[search_flights], # your function wrapping a flights API
)
hotels = Agent(
name="hotel_agent",
model="gemini-2.0-flash",
instruction="Find hotel options near the destination.",
tools=[search_hotels], # your function wrapping a hotels API
)
trip_planner = Agent(
name="trip_planner",
model="gemini-2.0-flash",
instruction="Plan a trip. Delegate flight and hotel lookups to your sub-agents.",
sub_agents=[flights, hotels],
)
O coordenador raciocina sobre a solicitação e a entrega ao sub-agente correto. Cada sub-agente chama uma API real através de sua função de ferramenta. Você executa tudo através de um Runner, ou o testa interativamente com adk web.
ADK vs. o OpenAI Agents SDK
Ambos são frameworks de agente "code-first" com ferramentas, transferências e rastreamento. A diferença está na gravidade do ecossistema.
| Google ADK | OpenAI Agents SDK | |
|---|---|---|
| Modelo Padrão | Gemini (Vertex AI) | Modelos OpenAI |
| Outros modelos | Vertex AI Model Garden, LiteLLM | LiteLLM e outros |
| Idiomas | Python, Java, Go, TypeScript | Python, JavaScript/TypeScript |
| Multi-agente | Sub-agentes mais agentes de fluxo de trabalho Sequential, Parallel, Loop | Agentes-como-ferramentas e transferências |
| Runtime gerenciado | Vertex AI Agent Engine | Traga o seu próprio |
| Protocolo de Ferramentas | MCP, ferramentas embutidas, ferramentas de função | MCP, ferramentas de função |
Se sua pilha já está no Google Cloud, o ADK mais o Vertex AI é a escolha natural. Se você é OpenAI-first, o OpenAI Agents SDK o mantém nessa linha. Ambos falam MCP, então os servidores de ferramentas podem ser compartilhados.
Quando usar o ADK
Opte pelo ADK quando:
- Você está construindo no Google Cloud e quer Gemini mais um runtime gerenciado no Vertex AI Agent Engine.
- Você precisa de orquestração multiagente com controle sequencial, paralelo ou em loop explícito.
- Você quer a avaliação incorporada ao framework, em vez de adicioná-la posteriormente.
- Você espera trocar de modelos e quer o LiteLLM e o Vertex AI Model Garden como alternativas.
Você pode ignorá-lo se estiver firmemente em outro ecossistema de modelos, ou se um único prompt com uma ou duas chamadas de função cobrir todo o seu caso de uso. Um framework de agente adiciona estrutura, e a estrutura tem um custo quando o trabalho é pequeno.
Onde o Apidog se encaixa: testando e simulando as APIs que seu agente chama
O ADK orquestra seu agente. Ele não testa as APIs externas das quais o agente depende, e essa é a lacuna que vale a pena fechar cedo.
Toda ferramenta significativa em seu agente chama algo: um endpoint LLM, uma API de pagamentos, um microsserviço interno, uma fonte de dados de terceiros. Quando um deles retorna um formato inesperado, seu agente raciocina com dados ruins e a falha é difícil de rastrear. O Apidog é onde você define esse contrato antes que ele o prejudique. Para deixar claro: o Apidog não é um framework de agente e não substitui o ADK. Ele está uma camada abaixo, nas APIs que suas ferramentas acessam.
Alguns usos concretos durante o desenvolvimento do ADK:
- Simule os endpoints que suas ferramentas chamam. Crie uma API simulada para um LLM ou um endpoint REST de ferramenta para que você possa desenvolver e executar seu agente sem gastar tokens ou atingir limites de taxa. Você controla as respostas, incluindo os casos de erro que seu agente precisa tratar.
- Afirme o formato da resposta da ferramenta. Use asserções de API para confirmar que um endpoint de ferramenta retorna exatamente os campos que seu agente espera. Se o contrato mudar, você o detecta em um teste, não em uma transcrição de agente confusa.
- Gerencie chaves por ambiente. Mantenha chaves de desenvolvimento, staging e produção em ambientes Apidog para que as mesmas chamadas de ferramenta funcionem de forma limpa em diferentes estágios.
Se você quiser um passo a passo mais aprofundado focado especificamente em agentes, veja como testar as chamadas de ferramentas de um agente de IA antes que elas falhem em produção. Você pode baixar o Apidog e simular um único endpoint em poucos minutos.
Perguntas Frequentes
O Google ADK é gratuito e de código aberto?
Sim. O ADK é de código aberto sob um repositório no GitHub com licença Apache, e você pode executá-lo localmente sem custo. Você paga pelos modelos que chama e por qualquer runtime gerenciado para o qual você implanta, como o Vertex AI Agent Engine. O framework em si é gratuito.
O ADK funciona apenas com o Gemini?
Não. O ADK é otimizado para Gemini e Vertex AI, mas é agnóstico em relação ao modelo. Através do Vertex AI Model Garden e do LiteLLM, você pode executar agentes com Anthropic, Meta, Mistral e outros provedores. Gemini é o padrão, não uma exigência.
Quais linguagens o ADK suporta?
Python foi o primeiro e continua sendo o mais completo. O Google adicionou Java desde então, com suporte a Go e TypeScript a seguir. Se você deseja a cobertura de recursos mais ampla hoje, Python é a escolha mais segura.
Como testo as APIs das quais meu agente ADK depende?
Teste-os separadamente do agente. Simule o LLM ou os endpoints da ferramenta para que seu agente seja executado sem chamadas ao vivo, e certifique-se de que cada resposta corresponda ao que seu agente espera. O Apidog cobre ambos, e o guia sobre como testar a API do ChatGPT mostra o mesmo padrão para um endpoint LLM que suas ferramentas podem chamar.
Concluindo
O Google ADK oferece uma maneira limpa e orientada para a produção de construir agentes e sistemas multiagentes, com Gemini e Vertex AI à mão, mas outros modelos a apenas uma mudança de configuração. Comece com um agente e algumas ferramentas, utilize o adk web para observar seu raciocínio e, em seguida, expanda para sub-agentes e um runtime gerenciado conforme a demanda do trabalho. À medida que seu agente depender mais de APIs externas, trate essas APIs como algo a ser simulado e asserido. Essa é a camada que o Apidog gerencia, e é onde o comportamento instável do agente geralmente começa.