1. Visão Geral do Projeto¶

O que é o iFriend Agents?¶

O iFriend Agents é um bot de atendimento inteligente para o setor de turismo. Ele permite que viajantes, agências e operadoras de turismo conversem por linguagem natural para:

Buscar experiências turísticas, guias e passeios
Solicitar orçamentos com preços, disponibilidade e câmbio
Realizar reservas completas (dados do viajante, emissão)
Efetuar pagamentos (tokenização de cartão, processamento)
Enviar e-mails de confirmação

Tudo isso funciona em múltiplas plataformas: Slack, WhatsApp (Evolution API e Official API), Telegram, WebChat e SSE (Server-Sent Events).

Stack Tecnológica¶

block-beta
    columns 1

    block:lang["Linguagem"]
        Python["Python 3.11"]
    end

    block:ai["Framework de IA"]
        ADK["Google ADK (Agent Dev Kit)<br/>Modelo: Gemini 2.5 Flash"]
    end

    block:web["Framework Web"]
        FastAPI["FastAPI + Uvicorn (ASGI)"]
    end

    block:infra["Infraestrutura"]
        GCP["GCP: Cloud Run · Cloud SQL (MySQL) · Redis<br/>BigQuery · Secret Manager · Vertex AI"]
    end

    block:container["Containerização"]
        Docker["Docker · Cloud Build"]
    end

    lang --> ai
    ai --> web
    web --> infra
    infra --> container

Estrutura de Pastas¶

ifriend-agents/
│
├── unified_bot.py            ← Entry point FastAPI (todas as routes)
├── AGENTS.md                 ← Documentação técnica da arquitetura multi-agent
├── VERSION                   ← v3.7.0
│
├── ifriend_agent/            ← Core do agente de IA
│   ├── agent.py              ← Ponto de entrada (chama AgentBuilder.build())
│   ├── agent_builder.py      ← Composição dinâmica do root_agent com feature flags
│   ├── agents/               ← Sub-agentes especializados:
│   │   ├── discovery_agent   ←   Busca de produtos (8 tools)
│   │   ├── itinerary_agent   ←   Roteiros multi-destino (3 tools, condicional)
│   │   ├── quote_agent       ←   Cotação, orçamento e propostas em PDF (11 tools)
│   │   ├── booking_agent     ←   Reservas (8 tools, condicional)
│   │   ├── booking_info_agent←   Consulta de reservas (1 tool, always-on)
│   │   ├── payment_agent     ←   Pagamentos (3 tools, condicional)
│   │   ├── utils_agent       ←   Email e CSV (2 tools)
│   │   ├── support_agent     ←   Atendimento humano (4 tools)
│   │   ├── custom_tour_agent ←   Orçamento de viagem personalizado (9 tools, condicional)
│   │   ├── custom_affiliate_booking_agent ← Reserva URL afiliado (3 tools, condicional)
│   │   ├── proposal_agent    ←   Propostas comerciais B2B em PDF (4 tools, condicional, affiliate/admin)
│   │   ├── research_agent    ←   Pesquisa web — AgentTool (1 tool)
│   │   └── faq_agent         ←   FAQ da plataforma — AgentTool (0 tools)
│   ├── prompts/              ← Prompt dinâmico do orquestrador
│   │   ├── orchestrator_prompt.py ← build_orchestrator_instruction()
│   │   └── ...               ← Prompts de sub-agentes
│   ├── tools/                ← 25+ tools do ADK (uma por arquivo)
│   │   ├── sanitize.py       ← Filtro de PII (strip_sensitive, safe_*_summary)
│   │   ├── client/           ← HTTP client centralizado (retry, circuit breaker)
│   │   ├── context/          ← Enriquecimento de contexto (headers, preços, whitelabel)
│   │   ├── blocks/           ← Generative UI blocks (experience_cards, guide_cards)
│   │   └── providers/        ← Integrações externas (Tiqets)
│   ├── callbacks/            ← Hooks before/after do agente (JWT, memória)
│   ├── config/               ← Configurações:
│   │   ├── app_config.py     ←   Cache de contexto + compactação de eventos
│   │   ├── feature_flags.py  ←   Feature flags (ENABLE_BOOKING, ENABLE_PAYMENT, etc.)
│   │   └── llm_config.py     ←   Parâmetros LLM + retry automático
│   ├── memory/               ← Memory services (CloudSQL com FULLTEXT search)
│   ├── tests/                ← Testes unitários (200+ testes)
│   └── __init__.py / requirements.txt
│
├── runtime/                  ← Plataforma e infraestrutura
│   ├── messaging/            ← Framework de mensageria multi-plataforma
│   │   ├── base.py           ←   Interface abstrata (MessagingAdapter)
│   │   ├── factory.py        ←   AdapterFactory (registro e resolução)
│   │   ├── processor.py      ←   ConversationProcessor (orquestra o fluxo)
│   │   ├── loop_guard.py     ←   Anti-loop bot-to-bot (4 camadas)
│   │   ├── audio/            ←   Transcrição de áudio via Gemini
│   │   ├── adapters/         ←   Slack, WhatsApp, Telegram, WebChat, SSE
│   │   └── sse/              ←   Stream Manager para Server-Sent Events
│   ├── sessions/             ← Session services (CloudSQL, JWT)
│   ├── a2a/                  ← Protocolo A2A (Agent-to-Agent)
│   ├── analytics/            ← Tracking de billing e analytics
│   ├── evaluations/          ← Avaliações de qualidade do agente
│   ├── workers/              ← Workers assíncronos
│   ├── scripts/              ← Scripts de deploy e manutenção
│   ├── tests/                ← Testes de runtime
│   ├── infra/                ← Schema SQL, migrations
│   └── observability/        ← Observabilidade e monitoramento
│
├── docs/                     ← Documentação do projeto (MkDocs)
├── examples/                 ← Exemplos (A2A client, CLI de teste)
├── scripts/                  ← Scripts utilitários
│
├── Dockerfile                ← Build da imagem Docker
├── Dockerfile.docs           ← Build da imagem de documentação
├── docker-compose.yml        ← Serviços locais (Redis, etc.)
├── cloudbuild.yaml           ← Pipeline CI/CD para Cloud Run
├── cloudbuild.stage.yaml     ← Pipeline CI/CD para Stage
├── cloudbuild-docs.yaml      ← Pipeline CI/CD para documentação
└── requirements*.txt         ← Dependências do projeto

Conceitos-chave que você precisa saber¶

Conceito	O que é	Onde fica
ADK	Google Agent Development Kit — framework para criar agentes de IA com tools, prompts e callbacks	`ifriend_agent/agent.py` + `agent_builder.py`
Tool	Função Python decorada que o agente pode chamar (ex: buscar produto, emitir reserva)	`ifriend_agent/tools/`
Callback	Hook que roda antes/depois do agente processar (ex: injetar JWT, salvar memória)	`ifriend_agent/callbacks/`
Adapter	Classe que traduz mensagens de uma plataforma (Slack, WhatsApp...) para formato interno	`runtime/messaging/adapters/`
Processor	Orquestrador que conecta adapter → session → agente ADK → resposta	`runtime/messaging/processor.py`
Session	Estado da conversa de um usuário (histórico, contexto JWT, metadata)	`runtime/sessions/`
Memory	Memória de longo prazo do usuário (persiste entre sessões)	`ifriend_agent/memory/`

Versão atual¶

A versão atual do projeto está no arquivo VERSION na raiz: v3.7.0

Próximo: Arquitetura e Fluxo de Dados →