Assistente de IA para dados imobiliários brasileiros
Construído com Google ADK-Go • Arquitetura Hexagonal • Production-Ready
Instalação • Exemplos • Arquitetura • API • Deploy
| Feature | Descrição |
|---|---|
| 🔍 Busca por Endereço | Pesquisa imóveis por rua, número e bairro |
| 📍 Busca Geoespacial | Encontra imóveis próximos a coordenadas ou pontos de referência |
| 📊 Análise de Mercado | Estatísticas e classificação por bairro |
| ⚖️ Comparador | Compara múltiplos imóveis ou regiões lado a lado |
| 🛡️ Segurança | Proteção contra prompt injection |
- Go 1.23+
- Google API Key (Gemini)
# 1. Clone o ADK-Go (dependência - ainda não publicado no pkg.go.dev)
git clone https://github.com/google/adk-go.git ~/adk-go
# 2. Clone este repositório
git clone https://github.com/raphaeltorquat0/iptu-agent.git ~/iptu-agent
cd ~/iptu-agent
# 3. Configure e execute
export GOOGLE_API_KEY="sua-chave-aqui"
export IPTU_USE_MOCK=true
go run ./cmd/agent --consolego run ./cmd/agent --console # Terminal interativo
go run ./cmd/agent --web # Interface web
go run ./cmd/agent --api # API REST (porta 8080)🔍 Buscar imóveis por endereço
> Quero saber o valor de imóveis na Avenida Paulista
Encontrei 3 imóveis na Avenida Paulista:
| Endereço | Área | Valor Venal | R$/m² | Tipo |
|-----------------------|-----------|-----------------|------------|-----------|
| Av. Paulista, 1500 | 1.200 m² | R$ 15.000.000 | R$ 12.500 | Comercial |
| Av. Paulista, 1000 | 450 m² | R$ 4.500.000 | R$ 10.000 | Comercial |
| Av. Paulista, 2000 | 800 m² | R$ 8.800.000 | R$ 11.000 | Comercial |
📊 Análise de mercado por bairro
> Como está o mercado imobiliário nos Jardins?
O bairro Jardins é classificado como região de alto padrão:
• Total de imóveis: 1.247
• Valor médio/m²: R$ 18.500,00
• Variação: R$ 8.000 a R$ 45.000/m²
• Composição: 72% residencial, 28% comercial
É uma das regiões mais valorizadas de São Paulo, com alta demanda
e valorização constante nos últimos anos.
📍 Busca geoespacial
> Encontre imóveis próximos ao Parque Ibirapuera
Encontrei 5 imóveis em um raio de 500m do Parque Ibirapuera:
• Rua Abílio Soares, 750 - R$ 2.800.000 (280 m²)
• Av. República do Líbano, 1200 - R$ 5.200.000 (420 m²)
• Rua Tutóia, 380 - R$ 1.900.000 (180 m²)
⚖️ Comparar regiões
> Compare os imóveis da Rua Oscar Freire com os da Alameda Lorena
Comparativo entre as duas ruas no bairro Jardins:
| Métrica | Oscar Freire | Alameda Lorena |
|------------------|------------------|------------------|
| Valor médio/m² | R$ 22.000 | R$ 19.500 |
| Predominância | Comercial (85%) | Misto (60/40) |
| Faixa de valores | R$ 3M - R$ 25M | R$ 1.5M - R$ 12M |
A Oscar Freire apresenta valores 12% superiores, refletindo
sua posição como principal corredor de luxo da região.
iptu-agent/
├── cmd/agent/ # Entry point
│ ├── main.go # Bootstrap, DI, graceful shutdown
│ ├── wire.go # Factory functions
│ └── instruction.go # System prompt + security rules
│
├── internal/
│ ├── config/ # Configuração centralizada (env vars)
│ │
│ ├── domain/ # 🎯 Core do negócio
│ │ ├── entity/ # Property, Money, Address, MarketAnalysis
│ │ ├── port/ # Interfaces (PropertyRepository)
│ │ └── service/ # Lógica de negócio (PropertyService)
│ │
│ ├── infrastructure/ # 🔌 Adapters externos
│ │ └── api/ # HTTP client, Mock client, Traced client
│ │
│ └── interfaces/ # 🎮 Adapters de entrada
│ └── tool/ # ADK Tools (5 ferramentas)
│
├── pkg/errors/ # Erros tipados com códigos
└── test/ # Testes de integração
| Princípio | Implementação |
|---|---|
| Hexagonal Architecture | Domain isolado de infraestrutura |
| Dependency Injection | Interfaces + factory functions |
| Fail-Fast Config | Validação no startup |
| Structured Logging | slog com JSON/text |
| Clean Code | SOLID, DRY, KISS |
Variáveis de Ambiente
| Variável | Descrição | Default |
|---|---|---|
GOOGLE_API_KEY |
API key do Gemini (obrigatória) | - |
APP_ENV |
development / staging / production | development |
IPTU_API_URL |
URL da API de IPTU | https://api.iptuapi.com.br |
IPTU_API_KEY |
API key do IPTU (produção) | - |
IPTU_USE_MOCK |
Usar dados mock | false |
LOG_LEVEL |
debug / info / warn / error | info |
LOG_FORMAT |
json / text | json |
HTTP_PORT |
Porta do servidor | 8080 |
Veja .env.example para lista completa.
# Iniciar servidor
go run ./cmd/agent --api --port=8080# Chat com o agente
curl -X POST http://localhost:8080/v1/chat \
-H "Content-Type: application/json" \
-d '{"message": "Busque imóveis na Rua Augusta"}'
# Health check
curl http://localhost:8080/health# Build
docker build -t iptu-agent .
# Run
docker run -p 8080:8080 \
-e GOOGLE_API_KEY=xxx \
-e IPTU_USE_MOCK=true \
iptu-agent# Build e push
gcloud builds submit --tag gcr.io/PROJECT_ID/iptu-agent
# Deploy
gcloud run deploy iptu-agent \
--image gcr.io/PROJECT_ID/iptu-agent \
--platform managed \
--region southamerica-east1 \
--set-env-vars="GOOGLE_API_KEY=xxx" \
--allow-unauthenticatedDocker Compose
version: '3.8'
services:
iptu-agent:
build: .
ports:
- "8080:8080"
environment:
- GOOGLE_API_KEY=${GOOGLE_API_KEY}
- IPTU_USE_MOCK=true
restart: unless-stopped# Testes
go test ./... -v -cover
# Lint
golangci-lint run
# Build
go build -o iptu-agent ./cmd/agent| Package | Coverage |
|---|---|
internal/domain/entity |
100% |
internal/config |
97.6% |
pkg/errors |
91.3% |
internal/domain/service |
85.9% |
- Fork o repositório
- Crie uma branch (
git checkout -b feature/amazing-feature) - Commit suas mudanças (
git commit -m 'feat: add amazing feature') - Push para a branch (
git push origin feature/amazing-feature) - Abra um Pull Request
- Conventional Commits
- Cobertura mínima de 80%
- Lint sem erros
Apache 2.0 - Veja LICENSE para detalhes.
