# 🤖 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:** 1. Cliente envia uma mensagem descrevendo uma ação desejada 2. O sistema envia a mensagem e lista de ferramentas disponíveis ao modelo de IA 3. A IA analisa a solicitação e decide qual ferramenta chamar (se necessário) 4. O sistema extrai parâmetros da mensagem e executa a ferramenta 5. 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 (Tools)** | PostgreSQL | Banco relacional para metadados de ferramentas | | **Banco Fictício (Mock)** | MySQL | Dados de negócio simulados usados pelos handlers | | **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 │ │ └── handlers.py # Handlers consultando MySQL fictício │ │ │ ├── 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 MySQL fictício │ └──────┬───────────────────────────┘ │ ▼ ┌──────────────────────────────────┐ │ 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 `.env` e 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](GUIA_COMPLETO_CONFIGURE_E_DEPLOY.md) - Setup completo do Google Cloud - [CLOUD_SQL_PROXY.md](CLOUD_SQL_PROXY.md) - Configuração de Cloud SQL Proxy - [TEST_CASES.md](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.