Desafio Técnico — iFriend Agents¶

Duração estimada: 4-8 horas. O objetivo é avaliar sua capacidade de navegar pela arquitetura multi-agent, seguir padrões existentes e entregar código de qualidade.

Contexto¶

A iFriend é uma plataforma de agentes de IA para turismo. Usamos o Google ADK com arquitetura Coordinator/Dispatcher: um orquestrador central (root_agent) delega para agentes especializados.

Você receberá acesso a um repositório com a estrutura completa do projeto. Leia o AGENTS.md para entender a arquitetura.

Cenário¶

A equipe de produto identificou a necessidade de um novo agente: feedback_agent. Após uma experiência ou reserva, o viajante pode dar um feedback (avaliação + comentário). O agente deve:

Coletar avaliação (nota 1-5) e comentário opcional
Validar os dados
Enviar o feedback para uma API externa
Agradecer e perguntar se o viajante quer falar com suporte

O Que Você Deve Fazer¶

1. Criar o agente `feedback_agent`¶

Siga os padrões documentados em docs/development/new-agent.md e no AGENTS.md.

Crie ifriend_agent/agents/feedback_agent.py com:

Nome: feedback_agent
Descrição: Coleta feedback de viajantes após experiência/reserva
Model: gemini-2.5-flash (via env MODEL)
disallow_transfer_to_peers: True
Prompt: ~30-50 linhas seguindo a estrutura: Role → Regras → Fluxo → Transferência

Fluxo do agente:¶

Solicita avaliação (nota 1-5) e comentário opcional
Valida os dados (nota obrigatória entre 1-5, comentário opcional até 500 caracteres)
Chama a tool enviar_feedback para registrar
Agradece e pergunta se o viajante quer falar com suporte
Se o viajante quiser suporte, transfere ao root_agent

Regra de transferência:¶

Se o usuário pedir algo fora do domínio de feedback, transfere imediatamente ao root_agent

2. Criar a tool `enviar_feedback`¶

Crie ifriend_agent/tools/enviar_feedback_tool.py:

from typing import Optional
from google.adk.tools import BaseTool

def enviar_feedback(
    booking_id: str,
    rating: int,
    comment: Optional[str] = None
) -> dict:
    """
    Registra o feedback de um viajante.

    Args:
        booking_id: ID da reserva
        rating: Nota de 1 a 5
        comment: Comentário opcional (máx 500 caracteres)

    Returns:
        dict com status e mensagem de confirmação
    """
    # Validações
    if not 1 <= rating <= 5:
        return {"status": "error", "message": "Nota deve ser entre 1 e 5"}
    if comment and len(comment) > 500:
        return {"status": "error", "message": "Comentário deve ter no máximo 500 caracteres"}

    # Simula envio para API externa
    feedback_id = f"fbk_{hash(booking_id + str(rating)) % 100000:05d}"

    return {
        "status": "success",
        "feedback_id": feedback_id,
        "message": f"Feedback {feedback_id} registrado com sucesso! Nota: {rating}/5."
    }

3. Registrar o agente¶

Adicione ao __all__ em ifriend_agent/agents/__init__.py
Registre como sub-agent always-on no AgentBuilder (em agent_builder.py)
Adicione a rota no ROUTING_HINTS em ifriend_agent/prompts/orchestrator_prompt.py

4. Criar testes¶

Em ifriend_agent/tests/test_sub_agents.py, adicione:

class TestFeedbackAgent:
    def test_is_llm_agent(self):
        from google.adk.agents import LlmAgent
        from ifriend_agent.agents.feedback_agent import feedback_agent
        assert isinstance(feedback_agent, LlmAgent)

    def test_name(self):
        from ifriend_agent.agents.feedback_agent import feedback_agent
        assert feedback_agent.name == 'feedback_agent'

    def test_tools_count(self):
        from ifriend_agent.agents.feedback_agent import feedback_agent
        assert len(feedback_agent.tools) == 1

E em ifriend_agent/tests/test_feedback_tool.py:

class TestEnviarFeedback:
    def test_success(self):
        from ifriend_agent.tools.enviar_feedback_tool import enviar_feedback
        result = enviar_feedback(booking_id="BK-001", rating=5, comment="Excelente!")
        assert result["status"] == "success"
        assert "feedback_id" in result

    def test_invalid_rating_below_1(self):
        from ifriend_agent.tools.enviar_feedback_tool import enviar_feedback
        result = enviar_feedback(booking_id="BK-001", rating=0)
        assert result["status"] == "error"

    def test_invalid_rating_above_5(self):
        from ifriend_agent.tools.enviar_feedback_tool import enviar_feedback
        result = enviar_feedback(booking_id="BK-001", rating=6)
        assert result["status"] == "error"

    def test_comment_too_long(self):
        from ifriend_agent.tools.enviar_feedback_tool import enviar_feedback
        result = enviar_feedback(booking_id="BK-001", rating=5, comment="x" * 501)
        assert result["status"] == "error"

    def test_comment_without_comment(self):
        from ifriend_agent.tools.enviar_feedback_tool import enviar_feedback
        result = enviar_feedback(booking_id="BK-001", rating=4)
        assert result["status"] == "success"

Entregáveis¶

Código do agente (ifriend_agent/agents/feedback_agent.py)
Código da tool (ifriend_agent/tools/enviar_feedback_tool.py)
Registro no __init__.py e agent_builder.py
Rota no orchestrator_prompt.py
Testes no test_sub_agents.py e test_feedback_tool.py
Breve explicação (máx 1 parágrafo) de como testaria o agente manualmente

Critérios de Avaliação¶

Critério	Peso	O que avaliamos
Adesão aos padrões	30%	Seguiu a estrutura do AGENTS.md? Usou `disallow_transfer_to_peers`? Registrou corretamente?
Qualidade do prompt	25%	Prompt claro, fluxo definido, regra de escape, instruções de transferência
Qualidade do código	20%	Type hints, docstrings, tratamento de erros, estilo consistente
Testes	15%	Testes para a tool (casos de borda) e para o agente
Explicação	10%	Clareza ao explicar como testaria manualmente

Instruções de Entrega¶

Faça um fork do repositório ou crie um repositório privado
Commit cada passo separadamente (agente, tool, registro, testes)
Abra um PR ou compartilhe o link do repositório
Inclua um COMMENTS.md com sua explicação e quaisquer observações

Dicas¶

Leia o AGENTS.md — ele contém tudo que você precisa saber
Veja agentes existentes (ex: discovery_agent.py, quote_agent.py) como referência
Veja tools existentes como referência de estilo
Siga os padrões de tipo, docstring e nomenclatura do projeto
Não se preocupe em acertar de primeira — queremos ver seu raciocínio