11 KiB
🤖 AI Orquestrador
Um sistema inteligente de orquestração de ferramentas que utiliza inteligência artificial para processar pedidos de clientes e executar ações automaticamente. Utilizando o poder do Google Vertex AI e Gemini, o sistema compreende intenções naturais e chama as ferramentas apropriadas para resolver cada solicitação.
📖 Visão Geral
AI Orquestrador é um MVP (Produto Mínimo Viável) que demonstra como integrar um modelo de linguagem avançado com um conjunto de ferramentas específicas do domínio para criar uma experiência conversacional inteligente.
Fluxo de funcionamento:
- Cliente envia uma mensagem descrevendo uma ação desejada
- O sistema envia a mensagem e lista de ferramentas disponíveis ao modelo de IA
- A IA analisa a solicitação e decide qual ferramenta chamar (se necessário)
- O sistema extrai parâmetros da mensagem e executa a ferramenta
- Resultado é formatado e retornado ao cliente de forma natural
Exemplo prático:
Cliente: "Gostaria de comprar um carro de até 50000 reais que seja sedan"
↓
IA decide: chamar ferramenta "consultar_estoque"
↓
Sistema busca no banco de dados
↓
Retorna: "Encontrei 5 veículos sedans disponíveis até R$ 50.000..."
🛠️ Stack Tecnológico
| Componente | Tecnologia | Descrição |
|---|---|---|
| Backend | FastAPI | Framework web moderno e rápido para APIs Python |
| IA/LLM | Google Vertex AI | Plataforma de IA empresarial com Gemini 1.5 Pro |
| Banco de Dados | PostgreSQL | Banco relacional robusto para dados estruturados |
| Dados de Teste | Mockaroo | Geração de dados fictícios para simulação |
| Containerização | Docker | Isolamento e deploy consistente |
| Orquestração | Google Cloud Build | Pipeline automatizado de build e deploy |
| Computação | Google Cloud Run | Plataforma serverless escalável |
| Runtime | Python 3.11+ | Linguagem principal da aplicação |
🏗️ Arquitetura do Projeto
Orquestrador/
├── app/
│ ├── main.py # Ponto de entrada da aplicação FastAPI
│ │
│ ├── api/
│ │ ├── routes.py # Endpoints principais (Chat, Health)
│ │ ├── tool_routes.py # Endpoints de gerenciamento de ferramentas
│ │ └── schemas.py # Modelos Pydantic para validação
│ │
│ ├── core/
│ │ └── settings.py # Configurações e variáveis de ambiente
│ │
│ ├── db/
│ │ ├── database.py # Conexão e declaração SQLAlchemy
│ │ ├── models.py # Modelos ORM do banco de dados
│ │ ├── init_db.py # Inicialização de banco
│ │ └── tool_seed.py # Dados iniciais de ferramentas
│ │
│ ├── services/
│ │ ├── orquestrador_service.py # Lógica principal de orquestração
│ │ ├── llm_service.py # Integração com Vertex AI / Gemini
│ │ ├── tool_registry.py # Registro e descoberta de ferramentas
│ │ ├── handlers.py # Handlers de execução de tools
│ │ └── mockaroo_client.py # Cliente para gerar dados fictícios
│ │
│ ├── repositories/
│ │ └── tool_repository.py # Acesso a dados de ferramentas
│ │
│ └── integrations/ # Integrações externas
│
├── Dockerfile # Imagem Docker da aplicação
├── cloudbuild.yaml # Configuração CI/CD (Cloud Build)
├── docker-compose.yml # Stack local com PostgreSQL
├── deploy.sh # Script de deploy no Cloud Run
├── requirements.txt # Dependências Python
├── .env.example # Exemplo de configuração
└── README.md # Esta documentação
🛠️ Ferramentas Disponíveis
O sistema possui as seguintes ferramentas pré-configuradas:
| Ferramenta | Descrição |
|---|---|
| consultar_estoque | Busca veículos por critérios de preço e categoria |
| validar_cliente_venda | Verifica aprovação de crédito do cliente |
| avaliar_veiculo_troca | Calcula valor estimado de troca de veículo |
| agendar_revisao | Agenda manutenção e revisão de veículo |
| cancelar_pedido | Cancela pedido existente do cliente |
🚀 Tecnologias em Detalhes
FastAPI
Framework web de alto desempenho construído sobre Starlette. Oferece validação automática de dados com Pydantic, documentação interativa (Swagger/OpenAPI) e tipagem forte em Python.
Google Vertex AI + Gemini
Plataforma de IA gerenciada do Google Cloud que permite usar modelos de linguagem avançados como o Gemini 1.5 Pro. Oferece segurança, escalabilidade e integração nativa com o ecossistema Google Cloud.
PostgreSQL
Banco de dados relacional de código aberto com suporte a JSON, transações ACID e extensibilidade. Ideal para estruturar dados de ferramentas e histórico de interações.
Docker
Containerização da aplicação garantindo consistência entre ambientes de desenvolvimento, teste e produção.
Google Cloud Build + Cloud Run
Pipeline CI/CD totalmente gerenciado que faz build da imagem, realiza testes e faz deploy automático no Cloud Run (plataforma serverless que escala automaticamente conforme a demanda).
📊 Fluxograma de Funcionamento
┌─────────────┐
│ Cliente │ "Comprar carro por até 50mil"
└──────┬──────┘
│
▼
┌──────────────────────────┐
│ Endpoint /chat (POST) │
└──────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ OrquestradorService │
│ - Processa mensagem │
│ - Busca ferramentas disponíveis │
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ LLMService (Vertex AI) │
│ - Envia ao Gemini 1.5 Pro │
│ - Recebe decisão de tool │
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Tool Handlers │
│ - Executa: consultar_estoque │
│ - Busca no PostgreSQL │
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Formata Resposta │
│ - Estrutura resultado │
│ - Retorna ao cliente │
└──────┬───────────────────────────┘
│
▼
┌──────────────────┐
│ Cliente │ Resultado formatado
└──────────────────┘
🔐 Segurança
O sistema foi construído com foco em boas práticas de segurança:
- Variáveis sensíveis: Armazenadas em
.enve variáveis de ambiente, nunca commitadas - Autenticação Google Cloud: Utiliza credenciais de serviço (service account) com roles específicas
- Isolamento de banco de dados: Credenciais separadas por ambiente
- Validação de dados: Pydantic garante tipagem e validação em todos os endpoints
- CORS: Configurável para ambientes específicos
- Cloud Run: Ambiente gerenciado com certificados SSL automáticos
📝 Como Usar
Para mais detalhes sobre instalação, configuração e uso, consulte os documentos:
- GUIA_COMPLETO_CONFIGURE_E_DEPLOY.md - Setup completo do Google Cloud
- CLOUD_SQL_PROXY.md - Configuração de Cloud SQL Proxy
- TEST_CASES.md - Casos de teste e exemplos
📚 Estrutura de Dados
Tabela: tools
Armazena metadados das ferramentas disponíveis:
- Nome e descrição
- Parâmetros obrigatórios e opcionais
- Endpoint correspondente
- Estado (ativa/inativa)
Histórico de Interações
Logs de todas as chamadas para fins de auditoria e análise.
🌐 APIs Disponíveis
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /chat |
Enviar mensagem e processar com IA |
| GET | /docs |
Documentação interativa (Swagger) |
| GET | /health |
Status da aplicação |
| GET | /tools |
Listar ferramentas disponíveis |
| POST | /tools |
Registrar nova ferramenta |
📈 Monitoramento na Produção
Quando implantado no Google Cloud Run, o sistema aproveita:
- Cloud Logging: Logs centralizados e estruturados
- Cloud Monitoring: Métricas de CPU, memória, latência e requisições
- Cloud Trace: Rastreamento distribuído para análise de performance
🔄 Próximas Melhorias
O projeto está em evolução contínua com planos para:
- Autenticação e autorização de usuários
- Rate limiting e proteção contra abuso
- Persistência de histórico de conversa
- Analytics de uso de ferramentas
- Testes end-to-end automatizados
- Suporte a múltiplos modelos de IA
- Dashboard de administração
📧 Contato
Para dúvidas, sugestões ou contribuições, entre em contato com o time de desenvolvimento.