Com o avanço dos modelos de linguagem de grande porte (LLMs), cresce também a necessidade de utilizá-los de forma segura, controlada e integrada aos ambientes corporativos e governamentais. Nesse cenário, apenas realizar chamadas diretas a um modelo de linguagem já não é suficiente para atender requisitos como governança, rastreabilidade, controle de acesso e reutilização de lógica de negócio.
Este material apresenta, de forma gradual e prática, como criar agentes inteligentes utilizando o Google ADK (Agent Development Kit), consumindo modelos de linguagem disponibilizados por meio do WSO2, plataforma amplamente adotada para gerenciamento e exposição de APIs no Estado de Goiás. A proposta é mostrar como sair de um uso simples de LLMs e evoluir para agentes capazes de tomar decisões, utilizar ferramentas e interagir com sistemas externos de maneira estruturada.
Ao longo do passo a passo, serão abordados conceitos fundamentais, arquitetura da solução e exemplos práticos de código, sempre com foco em um cenário real: modelos de linguagem protegidos por um gateway corporativo, com autenticação, segurança e políticas de uso. O objetivo é fornecer uma base sólida para desenvolvedores que desejam criar agentes mais robustos, previsíveis e alinhados às necessidades de ambientes institucionais.
Antes de avançar para a parte prática, é importante estabelecer alguns conceitos fundamentais que servem de base para todo o restante do material. Termos como LLM, agente, Google ADK e WSO2 aparecem com frequência ao longo do texto e, embora estejam relacionados, representam papéis distintos dentro da arquitetura proposta.
Nesta seção, será apresentada uma visão geral sobre a diferença entre o uso de um modelo de linguagem simples e a construção de um agente, além de uma explicação objetiva sobre o que é o Google ADK e como o WSO2 se encaixa nesse contexto. O objetivo é garantir um entendimento comum antes de partir para a implementação prática dos agentes.
Diferença entre um LLM simples e um agente
Um LLM simples é, basicamente, uma chamada direta a um modelo de linguagem:
- Você envia um prompt
- O modelo gera uma resposta
- A interação termina ali
Esse modelo funciona bem para tarefas isoladas, como responder perguntas, resumir textos ou gerar conteúdo, mas ele não possui consciência de contexto, objetivo ou capacidade de ação estruturada.
Já um agente é uma entidade que utiliza um LLM como parte do seu funcionamento, mas vai além:
- Ele possui instruções claras de comportamento
- Pode decidir quando usar ferramentas externas
- Pode executar múltiplos passos para chegar a uma resposta
- Mantém um fluxo lógico mais controlado
Em outras palavras:
- LLM → responde
- Agente → analisa, decide, age e responde
O Google ADK permite justamente essa evolução: sair de chamadas simples a modelos e criar agentes que operam de forma mais próxima a um assistente inteligente real, especialmente quando integrados a APIs corporativas, sistemas internos e modelos protegidos por plataformas como o WSO2.
O que é o Google ADK (Agent Development Kit)
O Google ADK (Agent Development Kit) é um framework criado para facilitar o desenvolvimento de agentes inteligentes, ou seja, aplicações baseadas em modelos de linguagem que não apenas respondem perguntas, mas tomam decisões, utilizam ferramentas, executam ações e seguem regras de comportamento.
Diferente de uma simples chamada a um modelo de linguagem, o ADK fornece uma estrutura para:
- Definir instruções e objetivos do agente
- Controlar quando e como ferramentas externas são utilizadas
- Organizar o fluxo de execução do agente
- Evitar que toda a lógica fique concentrada apenas em prompts
Na prática, o ADK funciona como uma “camada de orquestração” sobre um modelo de linguagem. Ele não substitui o LLM, mas define como o LLM deve se comportar dentro de um contexto mais amplo, permitindo a criação de agentes mais previsíveis, reutilizáveis e controláveis.
O que é o WSO2
O WSO2 é uma plataforma de gerenciamento de APIs e integração, muito utilizada em ambientes corporativos e governamentais por oferecer controle, segurança e governança no consumo de serviços.
No contexto de modelos de linguagem, o WSO2 atua como um gateway entre as aplicações consumidoras (como agentes criados com o Google ADK) e os modelos LLM propriamente ditos. Isso significa que:
- O acesso aos modelos é feito via APIs padronizadas
- Existe controle de autenticação e autorização, geralmente via OAuth2
- É possível aplicar políticas de segurança, limites de uso e auditoria
- Os modelos não ficam expostos diretamente à internet
Em ambientes como o do Estado de Goiás, essa abordagem é fundamental para garantir que o uso de modelos de IA siga requisitos de segurança, conformidade e rastreabilidade.
Hora de por a mão na massa.
Pré-requisitos
Lista clara para evitar frustração:
- Python 3.10+
- pip
- Acesso ao endpoint do modelo no WSO2
- Client ID / Client Secret (OAuth2)
- Ambiente virtual (opcional, mas recomendado)
python -m venv .venv<br>
source .venv/bin/activate # linux/mac
.venv\Scripts\activate # windowsInstalação do Google ADK
Explicar de forma direta:
pip install google-adk litellmCom o ambiente configurado e o Google ADK instalado, é importante compreender como os diferentes componentes dessa solução se conectam. Antes de partir para a implementação do agente, vale visualizar a arquitetura geral envolvida na comunicação entre o usuário, o agente, a plataforma de gerenciamento de APIs e o modelo de linguagem.
O diagrama a seguir ilustra, de forma simplificada, o fluxo de interação desde a solicitação do usuário até a chamada ao modelo LLM, evidenciando o papel de cada camada — do agente criado com o Google ADK até o acesso ao modelo por meio do WSO2.
Para iniciar, são importadas as bibliotecas necessárias para o funcionamento do agente e para a comunicação com o WSO2, além da definição de algumas variáveis essenciais para o processo de autenticação. Esse conjunto inclui tanto componentes do Google ADK quanto bibliotecas auxiliares para requisições HTTP e manipulação de dados.
É importante destacar que, neste exemplo, a definição das credenciais e variáveis de configuração é feita de forma simplificada, com o objetivo exclusivo de facilitar o entendimento do fluxo apresentado. Boas práticas e protocolos de segurança não foram aplicados neste trecho, devendo ser obrigatoriamente adotados em cenários reais, conforme as diretrizes e políticas de cada órgão ou instituição.
from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from google.adk.models.llm_request import LlmRequest
from google.adk.models.llm_response import LlmResponse
import requests
import base64
from datetime import datetime, timedelta
from typing import AsyncGenerator
import httpx
import litellm
from typing import AsyncGenerator
consumer_key=''
consumer_secret=''
url_token='https://endereço_do_wso2/token'
wso2_endpoint = "https://endpoint_da_api/v1"Geração de token de acesso (OAuth2)
No contexto de consumo de modelos de linguagem expostos por meio do WSO2, é necessário realizar a autenticação via OAuth2 para obter um token de acesso válido. Esse token será utilizado nas requisições subsequentes ao endpoint do modelo.
O trecho de código abaixo apresenta uma implementação básica e simplificada de geração de token utilizando o fluxo client credentials. O objetivo é apenas exemplificar o processo, facilitando o entendimento do fluxo de autenticação, e não deve ser encarado como uma implementação definitiva para ambientes produtivos.
def gera_token(Consumer_Key=consumer_key,
Consumer_Secret=consumer_secret,
url=url_token):
basic = f'{Consumer_Key}:{Consumer_Secret}'
basic_bytes = basic.encode('ascii')
base64_bytes = base64.b64encode(basic_bytes)
base64_basic = base64_bytes.decode('ascii')
data = {'grant_type':'client_credentials'}
headers = {"Authorization": "Basic {}".format(base64_basic)}
token = requests.post(url=url, data=data, headers=headers).json()
return token['access_token']
Nesta função, as credenciais (consumer_key e consumer_secret) são combinadas e codificadas em Base64 para compor o header de autenticação do tipo Basic Authentication. Em seguida, é realizada uma requisição HTTP ao endpoint de token do WSO2, que retorna um access token utilizado para autorizar chamadas às APIs protegidas.
É importante destacar que:
- Esta função não implementa cache de token, renovação automática ou tratamento de erros.
- As credenciais estão representadas de forma direta apenas para fins didáticos.
- Cada órgão ou instituição pode (e normalmente deve) adotar políticas próprias de segurança, como:
- Uso de cofres de segredo (Secret Manager, Vault, etc.)
- Rotação de credenciais
- Controle de escopo (scopes)
- Logs e auditoria de acesso
- Tratamento adequado de exceções e falhas de autenticação
Portanto, antes de utilizar qualquer lógica semelhante em produção, é fundamental alinhar a implementação aos protocolos de segurança, governança e conformidade definidos pela organização.
Criando as Ferramentas do agente
Para demonstrar o funcionamento de agentes no Google ADK, foram criadas algumas ferramentas de exemplo que simulam a obtenção de informações sobre cidades. Essas ferramentas têm como objetivo ilustrar como um agente pode decidir quando utilizar uma função externa para complementar sua resposta, sem a necessidade de integração com serviços reais neste momento.
As funções apresentadas retornam dados simulados, como horário local, área territorial e coordenadas geográficas, permitindo focar no comportamento do agente, na estrutura das ferramentas e na forma como o ADK orquestra as chamadas, sem adicionar complexidade externa ao exemplo.
Cada ferramenta segue um padrão simples:
- Recebe um parâmetro de entrada (
city) - Executa uma lógica interna simulada
- Retorna um dicionário contendo uma resposta textual, que poderá ser utilizada diretamente pelo agente
Esse tipo de abordagem é especialmente útil em fases iniciais de desenvolvimento, testes ou aprendizado, antes de substituir as funções simuladas por integrações reais com APIs corporativas, bases de dados ou serviços internos, respeitando sempre os protocolos e políticas de segurança de cada instituição.
def get_horas(city: str) -> dict:
"""
Ferramenta: Obter horário atual em uma cidade.
Descrição:
Retorna o horário atual aproximado em uma cidade específica, com base em fusos horários simulados.
Parâmetros:
- city (str): Nome da cidade desejada.
Retorna:
- Um dicionário contendo:
- o nome da cidade,
- o horário atual no formato HH:MM,
- uma descrição textual.
"""
# Simulação de fusos horários relativos a UTC
fuso_simulado = {
"São Paulo": -3,
"Rio de Janeiro": -3,
"Brasília": -3,
"Lisboa": 0,
"Nova York": -4,
"Tóquio": 9,
"Londres": 1
}
utc_now = datetime.utcnow()
offset = fuso_simulado.get(city, 0)
local_time = utc_now + timedelta(hours=offset)
formatted_time = local_time.strftime("%H:%M")
return {"text": f"O horário atual em {city} é aproximadamente {formatted_time}."}
def get_tamanho_cidade(city: str) -> dict:
"""
Ferramenta: Obter área territorial de uma cidade.
Descrição:
Retorna a área aproximada de uma cidade, em quilômetros quadrados.
Parâmetros:
- city (str): Nome da cidade desejada.
Retorna:
- Um dicionário contendo o nome da cidade, sua área em km² e uma descrição textual.
"""
# Dados simulados para algumas cidades
tamanhos_simulados = {
"São Paulo": 1521.11,
"Rio de Janeiro": 1182.3,
"Brasília": 5802.0,
"Salvador": 693.8,
}
area = tamanhos_simulados.get(city, 1000.0)
return {"text": f"A cidade de {city} possui uma área aproximada de {area:.2f} km²."}
def get_latitude_longitude(city: str) -> dict:
"""
Ferramenta: Obter coordenadas geográficas.
Descrição: Retorna a latitude e longitude aproximadas da cidade informada.
Parâmetros:
- city (str): Nome da cidade desejada.
Retorna:
- Um dicionário contendo a cidade, latitude e longitude.
"""
# Dados simulados para exemplo
coordenadas_simuladas = {
"São Paulo": ( -23.55052, -46.63331),
"Rio de Janeiro": (-22.90685, -43.1729),
"Brasília": (-15.79389, -47.88278),
"Salvador": (-12.97139, -38.50139),
}
coords = coordenadas_simuladas.get(city, (14.123114, 16.12312))
return {"text": "As coordenadas da cidade "+city+" é latitude "+str(coords[0])+" e longitude "+str(coords[1])}
No Google ADK, a forma como as ferramentas são declaradas influencia diretamente o comportamento do agente. Funções bem definidas, com parâmetros claros e descrições objetivas, ajudam o modelo a entender quando uma ferramenta deve ser utilizada e qual resultado esperar de sua execução. Uma definição inadequada pode levar a usos incorretos, respostas inconsistentes ou execuções desnecessárias. Por isso, declarar corretamente as funções que atuarão como ferramentas é um passo essencial para garantir agentes mais previsíveis e eficientes.
Atualização automática de token OAuth2 do WSO2
Durante o uso do Google ADK consumindo modelos LLM por meio do WSO2, um ponto importante é o gerenciamento do token OAuth2. Como esses tokens possuem tempo de expiração, a aplicação pode falhar com erros de autenticação (401 ou AuthenticationError) caso o token expire durante a execução do agente.
Para resolver esse problema, foi adicionada uma camada de refresh automático do token, estendendo a classe LiteLlm utilizada pelo Google ADK.
A ideia é simples:
- Executar a chamada normalmente para o modelo LLM via LiteLLM.
- Caso ocorra um erro de autenticação (
AuthenticationError), assumir que o token expirou. - Solicitar um novo token ao WSO2.
- Atualizar dinamicamente o header
Authorization. - Reexecutar a chamada ao modelo uma única vez, agora com o token atualizado.
Implementação
Abaixo está a classe responsável por encapsular esse comportamento:
async def refresh_wso2_token() -> str:
async with httpx.AsyncClient() as client:
resp = await client.post(
url_token,
data={
"grant_type": "client_credentials",
"client_id": consumer_key,
"client_secret": consumer_secret,
},
headers={"Content-Type": "application/x-www-form-urlencoded"},
timeout=10,
)
resp.raise_for_status()
return resp.json()["access_token"]
class LiteLlmWithWso2Refresh(LiteLlm):
async def generate_content_async(
self, llm_request: LlmRequest, stream: bool = False
) -> AsyncGenerator[LlmResponse, None]:
try:
async for resp in super().generate_content_async(
llm_request, stream=stream
):
yield resp
except litellm.exceptions.AuthenticationError:
# 🔁 Refresh do token OAuth2 no WSO2
new_token = await refresh_wso2_token()
# Atualiza o header Authorization sem efeitos colaterais
headers = self._additional_args.get("extra_headers", {})
headers = dict(headers)
headers["Authorization"] = f"Bearer {new_token}"
self._additional_args["extra_headers"] = headers
# 🔁 Reexecuta a chamada apenas uma vez
async for resp in super().generate_content_async(
llm_request, stream=stream
):
yield respCriação do modelo customizado (vLLM)
Nesta etapa é realizada a criação de um modelo customizado utilizando o LiteLlm, que será responsável por intermediar a comunicação entre o agente do Google ADK e um modelo de linguagem servido via vLLM. Essa configuração permite que o agente utilize um modelo hospedado externamente, acessado por meio do WSO2, sem a necessidade de conexão direta com o servidor do modelo.
O trecho abaixo define o modelo que será consumido pelo agente, especificando o identificador do modelo no vLLM, o endpoint exposto pelo WSO2 e os headers necessários para autenticação e comunicação com a API.
custom_model = LiteLlmWithWso2Refresh(
model="hosted_vllm/llama-31-8b-instruct",
api_key="qualquer_key",
base_url=wso2_endpoint,
extra_headers={
"Authorization": f"Bearer {gera_token()}",
"Content-Type": "application/json",
"Accept": "application/json"
}
)Essa abordagem permite que o Google ADK utilize modelos servidos pelo vLLM de forma transparente, mantendo o controle de acesso, segurança e governança providos pelo WSO2.
Criação do modelo customizado (Ollama)
Além do consumo de modelos servidos via vLLM, o Google ADK também pode ser configurado para utilizar modelos disponibilizados por meio do Ollama, desde que estes estejam expostos por um endpoint compatível e protegidos pelo WSO2. Nesse cenário, o LiteLlm atua novamente como a camada de integração entre o agente e o modelo de linguagem.
O trecho a seguir demonstra a criação de um modelo customizado apontando para um modelo hospedado no Ollama, especificando o identificador do modelo, o endpoint exposto pelo WSO2 e os headers necessários para autenticação.
ollama_custom_model = LiteLlmWithWso2Refresh(
model="ollama/llama3.1:8b",
api_key="qualquer_key",
api_base=wso2_endpoint, # Endpoint do OLLAMA
extra_headers={
"Authorization": f"Bearer {gera_token()}",
"Content-Type": "application/json",
"Accept": "application/json"
}
)Nesse caso, o valor informado em api_key é apenas um placeholder, já que a autenticação efetiva ocorre por meio do token OAuth2 enviado no header Authorization. Essa configuração permite que o agente do Google ADK utilize modelos servidos pelo Ollama de forma segura e padronizada, mantendo a governança e o controle de acesso providos pelo WSO2.
Apesar de ambos os modelos customizados utilizarem o LiteLlm, existem pequenas diferenças na forma como o código é configurado para o vLLM e para o Ollama. No caso do vLLM, o modelo é identificado pelo prefixo hosted_vllm, indicando que a inferência ocorre em um servidor vLLM externo. Já no Ollama, o prefixo ollama é utilizado para sinalizar que o modelo segue o padrão de consumo do Ollama.
Além disso, há variações nos parâmetros de configuração: no vLLM é utilizado o atributo base_url, enquanto no Ollama é empregado api_base, refletindo a forma como cada backend expõe seu endpoint.
Essas diferenças são sutis, mas importantes para que o LiteLlm identifique corretamente o backend utilizado e direcione as requisições de forma adequada.
Existem diferenças importantes no papel de cada um dentro da arquitetura. No caso do vLLM, o foco está em alta performance e escalabilidade, sendo mais indicado para ambientes que exigem maior throughput e controle fino sobre recursos de inferência. Já o Ollama é geralmente utilizado em cenários mais simples ou locais, facilitando a execução e o gerenciamento de modelos com menor complexidade operacional.
Criação do agente
Com o modelo customizado configurado e as ferramentas definidas, o próximo passo é a criação do agente propriamente dito utilizando o Google ADK. É nesse momento que são estabelecidos o comportamento, as regras de uso de ferramentas e a forma como o agente deve interagir com o usuário.
No trecho abaixo, o agente é criado a partir do custom_model, recebe um nome e uma descrição, e é configurado com um conjunto de instruções detalhadas. Essas instruções funcionam como regras de operação, orientando o agente sobre quando utilizar ferramentas, como responder ao usuário e quais comportamentos devem ser evitados.
root_agent = Agent(
model=custom_model,
name='agente_ferramentas',
description='Agente com ferramentas',
instruction="""Você é um agente inteligente que pode usar ferramentas quando necessário.
REGRAS ABSOLUTAS:
1. Use UMA ferramenta por vez, somente se for estritamente necessário.
2. Se a informação já for suficiente para responder, NÃO use ferramentas.
3. Após receber o resultado de uma ferramenta, você DEVE responder ao usuário.
4. Nunca chame ferramentas novamente depois de já ter recebido os dados necessários.
5. A resposta final ao usuário NUNCA deve conter chamadas de ferramentas.
6. Nunca explique seu raciocínio interno, nem diga se usou ou não ferramentas, a menos que o usuário pergunte.
FERRAMENTAS DISPONÍVEIS:
get_latitude_longitude(city)
Retorna a latitude e longitude de uma cidade.
get_tamanho_cidade(city)
Retorna a área aproximada (em km²) de uma cidade.
get_horas(city)
Retorna o horário atual aproximado em uma cidade.
COMPORTAMENTO:
- Se a pergunta puder ser respondida com conhecimento geral → responda naturalmente.
- Se exigir um dado específico ou atual → use a ferramenta correta.
- Quando responder ao usuário, seja direto, claro e natural.
Agora aguarde a pergunta do usuário.
""",
tools=[
get_horas,
get_tamanho_cidade,
get_latitude_longitude
]
)A definição explícita das regras dentro do campo instruction é fundamental para garantir um comportamento previsível do agente, evitando usos desnecessários de ferramentas ou ciclos de execução incorretos. Já o parâmetro tools informa ao Google ADK quais funções estão disponíveis para o agente, permitindo que ele escolha a ferramenta adequada apenas quando a informação não puder ser obtida diretamente pelo modelo.
Essa separação entre modelo, ferramentas e instruções é um dos principais diferenciais do Google ADK, pois torna o agente mais controlável, reutilizável e alinhado a cenários corporativos.
Estrutura final do projeto
Ao final da implementação, o projeto fica organizado de forma simples e modular, separando os agentes de acordo com o modelo utilizado. Essa organização facilita a manutenção, os testes e a evolução do código, além de permitir reutilizar a mesma base para diferentes backends de inferência.
A estrutura final dos arquivos é apresentada a seguir:
.
├── README.md
├── requirements.txt
├── hello
│ ├── __init__.py
│ ├── .env
│ └── agent.py
└── helloollama
├── __init__.py
├── .env
└── agent.py
O arquivo README.md concentra as instruções gerais do projeto, enquanto o requirements.txt define as dependências necessárias para execução. Cada diretório (hello e helloollama) representa um agente independente, com sua própria configuração de ambiente (.env) e arquivo principal (agent.py), permitindo apontar para modelos distintos, como vLLM ou Ollama, sem interferência entre eles.
Em todos os arquivos __init__.py, foi incluída apenas a linha:
from . import agentEssa abordagem garante que o módulo do agente seja carregado automaticamente ao importar o pacote, mantendo a estrutura simples e consistente, sem adicionar lógica desnecessária nesses arquivos.
Essa separação torna o projeto mais organizado e facilita a adaptação do código para novos agentes, modelos ou ambientes, mantendo uma estrutura clara e escalável.
Execução dos agentes com o Google ADK
Após a definição do agente e da estrutura do projeto, o Google ADK oferece diferentes formas de executar e testar os agentes criados. As duas mais comuns são por meio da interface web (adk web) e pela linha de comando (adk run), ambas utilizando a mesma base de código.
Execução via adk run
A forma mais simples de executar um agente é utilizando o comando adk run, apontando para o módulo que contém a definição do agente. Por exemplo, para executar o agente configurado com o modelo vLLM:
adk run helloOu, no caso do agente que utiliza o modelo via Ollama:
adk run helloollamaNesse modo, o agente é iniciado em um ambiente interativo no terminal, permitindo enviar perguntas diretamente e observar o comportamento do agente, incluindo o uso (ou não) das ferramentas definidas.
Execução via adk web
Outra opção é executar o agente utilizando a interface web fornecida pelo ADK, o que pode ser útil para testes manuais e demonstrações. Para isso, basta executar:
adk webAo iniciar esse comando, o ADK sobe uma interface web local onde os agentes disponíveis no projeto podem ser selecionados e testados por meio de um chat. Essa abordagem facilita a validação do comportamento do agente sem a necessidade de interações via terminal.
Ambos os modos utilizam as mesmas configurações, modelos e ferramentas definidos no código, tornando o processo de execução flexível e adequado tanto para desenvolvimento quanto para testes iniciais.
Conclusão
Ao longo deste material, foi apresentado um passo a passo para a criação de agentes inteligentes utilizando o Google ADK, consumindo modelos de linguagem protegidos e expostos por meio do WSO2. A abordagem demonstrou como evoluir de um uso simples de LLMs para a construção de agentes com comportamento controlado, uso consciente de ferramentas e integração com diferentes backends de inferência, como vLLM e Ollama. Esse modelo de desenvolvimento permite maior governança, segurança e previsibilidade, atendendo às necessidades de ambientes corporativos e governamentais, além de servir como base para a expansão futura com novos agentes, ferramentas e integrações.
Mais um excelente artigo Adriano Pericles! Parabéns!