Skip to content

Roadmap — Suporte ao Google UCP (Universal Checkout Protocol)

Status: Planejamento (não iniciado)
Produto: ifriend_agent (Google ADK v1.25.1)
Objetivo: Permitir que agentes de IA ajudem usuários a comprar produtos de turismo (experiências, tickets, transfers e guias) com checkout via Google UCP / Buy on Google, capturando o pagamento na iFriend (modelo híbrido) com opção de 100% Google via flag.

Contexto

O Google UCP permite que agentes de IA iniciem sessões de checkout no Google para produtos cadastrados no Google Merchant Center. Para o iFriend, isso viabiliza "reservar e pagar passeios/tickets/guias diretamente pelo agente de IA" com checkout nativo do Google.

Decisões de produto já tomadas: - Escopo: experiências, tickets, transfers e guias. - Pagamento: iFriend captura o pagamento (modelo híbrido). - Flag opcional UCP_FULL_GOOGLE_PAYMENT para delegar 100% do pagamento ao Google (pós-MVP). - Conta Merchant Center: operada pela iFriend (conta centralizada). Ainda não existe. - Endpoints de booking existem; precisam de adaptação para pedidos originados do Google UCP.

Escopo do MVP

Incluído Não incluído (pós-MVP)
Agente ucp_agent no root_agent Flag UCP_FULL_GOOGLE_PAYMENT (100% Google)
Tools: iniciar_checkout_ucp, consultar_status_pedido_ucp, validar_elegibilidade_ucp Webhook de notificação de pagamento do Google (recebimento assíncrono)
Feature flag ENABLE_UCP (default False) Sincronização automática contínua de feed (job periódico)
Routing dinâmico no orchestrator Controle de acesso por role (affiliate/admin)
Feed inicial de produtos para Merchant Center (manual/one-shot) Suporte a múltiplas contas Merchant Center (por affiliate)
Testes unitários das tools e do agente Integração com pagamento 100% Google

Fases e Cronograma (estimativa)

Fase 1 — Pesquisa e Viabilidade (1–2 semanas)

Objetivo: Entender a spec do UCP, validar endpoints de backend e definir modelo de dados.

Atividades: - Ler documentação oficial do Google UCP (Merchant Center, checkout sessions, order API). - Definir campos de produto: ucp_enabled, merchant_center_offer_id, google_checkout_url. - Definir endpoints da API iFriend a adaptar/criar (receber pedido pago do Google, criar booking a partir de ordem UCP). - Decidir se o webhook de pagamento entra no MVP ou fica para depois. - Definir escopo de guias no feed do Merchant Center.

Entregáveis: - Documento de decisão de arquitetura (modelo de dados, endpoints necessários). - Lista de endpoints da API iFriend a criar/adaptar.

Perguntas em aberto para o time: - Qual endpoint da API iFriend receberá a notificação de pagamento do Google? - O booking criado a partir de ordem UCP segue o mesmo payload de emitir_reserva_experience/emitir_reserva_guia?

Fase 2 — Conta Merchant Center e Feed de Produtos (2–3 semanas)

Objetivo: Criar conta Merchant Center da iFriend, obter aprovação UCP e publicar produtos elegíveis.

Atividades: - Criar e verificar conta Merchant Center da iFriend. - Solicitar aprovação para UCP / Buy on Google. - Criar job de sincronização de feed (novo worker ou adicionar ao cloudbuild-product-search-sync). - Mapear campos do feed: id, title, description, link (theifriend.com), image_link, price, availability, condition, identificador de oferta UCP. - Incluir guias no feed (produtos do tipo guia). - Sincronização incremental (preço, disponibilidade) e remoção de produtos indisponíveis.

Entregáveis: - Conta Merchant Center ativa e aprovada para UCP. - Código do job de sync de feed. - Produtos elegíveis publicados no Merchant Center.

Dependência externa: Aprovação da conta Merchant Center pelo Google (pode demorar dias/semanas).

Fase 3 — Ferramentas UCP (2–3 semanas)

Objetivo: Criar as tools que interagem com o Google UCP e com o backend iFriend.

Novos arquivos: - ifriend_agent/tools/ucp/__init__.py - ifriend_agent/tools/ucp/iniciar_checkout_ucp_tool.py — inicia sessão de checkout do Google (retorna checkout_url/session_id). - ifriend_agent/tools/ucp/consultar_status_pedido_ucp_tool.py — consulta status do pedido (pago, pendente, cancelado). - ifriend_agent/tools/ucp/validar_elegibilidade_ucp_tool.py — verifica se produto é elegível UCP. - ifriend_agent/tools/ucp/sincronizar_produtos_merchant_center_tool.py — sync manual do feed (admin, opcional).

Padrões a seguir: - Funções async com tool_context: ToolContext. - Usar IFriendAPIClient para chamadas ao backend iFriend. - Sanitização de retorno via sanitize.py. - Retorno dict {"success": bool, ...}.

Entregáveis: - Tools UCP implementadas e testadas com mocks. - Sanitização de dados sensíveis (tokens internos, dados de pagamento).

Fase 4 — Agente UCP (1–2 semanas)

Objetivo: Criar o ucp_agent e integrá-lo ao root_agent.

Novo arquivo: - ifriend_agent/agents/ucp_agent.py

Padrão: Seguir quote_agent / custom_tour_agent (LlmAgent, disallow_transfer_to_peers=True, static_instruction opcional).

Fluxo do agente: 1. Recebe produto selecionado (do discovery/quote). 2. validar_elegibilidade_ucp(product_id). 3. Se elegível: iniciar_checkout_ucp(...) → apresenta checkout_url ao usuário. 4. Após pagamento: consultar_status_pedido_ucp(checkout_id) → confirma ou reporta falha. 5. Transfere ao root_agent.

Entregáveis: - ucp_agent implementado. - Registro no agent_builder.py. - Routing hint no orchestrator_prompt.py.

Fase 5 — Feature Flag, Prompt e Roteamento (1 semana)

Atividades: - Adicionar flag ENABLE_UCP (default False) em config/feature_flags.py. - Registrar ucp_agent no agent_builder.py (condicional via flag). - Adicionar routing hint para ucp_agent em ROUTING_HINTS (orchestrator_prompt.py). - Adicionar DISABLED_HINTS["ucp_agent"]. - (Opcional) Criar config/ucp_access.py para controle de acesso por role/JWT, seguindo o padrão proposal_access.py.

Entregáveis: - ENABLE_UCP controla ativação do agente. - Prompt do orquestrador inclui/sem rota para ucp_agent conforme flag.

Fase 6 — Testes (1–2 semanas)

Novos arquivos de teste: - ifriend_agent/tests/test_ucp_agent.py — estrutura, tools, disallow_transfer_to_peers, prompt. - ifriend_agent/tests/test_ucp_tools.py — mock das chamadas ao Google/UCP e backend (AsyncMock, patch sobre IFriendAPIClient). - ifriend_agent/tests/test_ucp_access.py (se houver access control). - Extensão de test_agent_builder.py e test_orchestrator.py para verificar ucp_agent conforme flag.

Entregáveis: - Cobertura de testes unitários para tools e agente. - Testes passando no CI.

Fase 7 — Deploy e Rollout (1 semana)

Atividades: - Definir env vars: ENABLE_UCP, GOOGLE_MERCHANT_CENTER_ID, credenciais Google UCP, UCP_CHECKOUT_BASE_URL. - Atualizar cloudbuild.yaml / Cloud Run para worker de sync de feed. - Habilitar ENABLE_UCP=true em stage para affiliate piloto. - Monitorar: taxa de conversão checkout, erros de API Google, webhooks de pedido não recebidos.

Entregáveis: - UCP disponível em stage para contas piloto. - Monitoramento e alertas configurados.

Arquivos a criar/modificar

Criar

Caminho Descrição
docs/UCP_IMPLEMENTATION_ROADMAP.md Este documento
ifriend_agent/tools/ucp/__init__.py Pacote de tools UCP
ifriend_agent/tools/ucp/iniciar_checkout_ucp_tool.py Tool de início de checkout
ifriend_agent/tools/ucp/consultar_status_pedido_ucp_tool.py Tool de consulta de status
ifriend_agent/tools/ucp/validar_elegibilidade_ucp_tool.py Tool de validação de elegibilidade
ifriend_agent/tools/ucp/sincronizar_produtos_merchant_center_tool.py Tool de sync de feed (opcional)
ifriend_agent/agents/ucp_agent.py Agente UCP
ifriend_agent/config/ucp_access.py Controle de acesso por role (opcional)
ifriend_agent/scripts/sync_merchant_center.py Job de feed do Merchant Center
ifriend_agent/tests/test_ucp_agent.py Testes do agente
ifriend_agent/tests/test_ucp_tools.py Testes das tools

Modificar

Caminho Alteração
ifriend_agent/config/feature_flags.py Adicionar flag ENABLE_UCP
ifriend_agent/agent_builder.py Registrar ucp_agent
ifriend_agent/prompts/orchestrator_prompt.py Routing hint + disabled hint para ucp_agent
ifriend_agent/tools/sanitize.py Sanitização de resposta UCP
ifriend_agent/requirements.txt Dependências Google (se faltar)
AGENTS.md Documentar novo agente (pós-implementação)

Riscos e Dependências

Item Detalhe Mitigação
Conta Merchant Center Não existe; precisa criar e verificar; aprovação UCP pode demorar Iniciar criação o mais cedo possível (Fase 2)
Backend iFriend Endpoints de booking existem; precisam adaptação para pedidos Google UCP Definir contrato na Fase 1 com o time de API
Flag 100% Google iFriend captura pagamento por padrão; flag UCP_FULL_GOOGLE_PAYMENT para delegar 100% ao Google Deixar para pós-MVP
Guias no feed Produtos de guia precisam ser mapeados corretamente no Merchant Center Incluir guias no mapeamento do feed desde o início
Concorrentes Regra existente proíbe links de GetYourGuide/Viator etc. Checkout do Google é próprio, não concorrente direto; confirmar com produto/legal

Métricas de Sucesso (MVP)

  • Percentual de pedidos iniciados via UCP que são concluídos (checkout_url gerado → pagamento confirmado).
  • Taxa de erro da API Google UCP.
  • Tempo médio entre início do checkout e confirmação de pagamento.
  • Número de produtos elegíveis publicados no Merchant Center.

Próximos Passos Imediatos

  1. Criar branch feature/ucp-support.
  2. Iniciar Fase 1: pesquisa da spec UCP + definição de endpoints de backend (com o time de API).
  3. Criar conta Merchant Center da iFriend e solicitar aprovação UCP (pode rodar em paralelo).