Como Adicionar Novo Agente¶

Visão Geral¶

Este guia mostra como adicionar um novo agente ao sistema iFriend.

Passo 1: Criar o arquivo do agente¶

Crie ifriend_agent/agents/meu_novo_agent.py:

import os
from google.adk.agents import LlmAgent
from ifriend_agent.tools.minha_tool_1 import minha_tool_1
from ifriend_agent.tools.minha_tool_2 import minha_tool_2

INSTRUCTION = """
Você é o agente especializado em [domínio].

## Regras
- Execute silenciosamente → Apresente resultados → Pergunta final
- Nunca invente dados
- Quando concluir, transfira de volta ao root_agent

## Fluxo
1. [Passo 1]
2. [Passo 2]
"""

meu_novo_agent = LlmAgent(
    name='meu_novo_agent',
    description='Descrição clara do domínio deste agente',
    model=os.getenv("MODEL", "gemini-2.5-flash"),
    instruction=INSTRUCTION,
    tools=[minha_tool_1, minha_tool_2],
    disallow_transfer_to_peers=True,  # Obrigatório para sub_agents
)

Passo 2: Registrar no agents/init.py¶

from .meu_novo_agent import meu_novo_agent

__all__ = [
    ...
    "meu_novo_agent",
]

Passo 3: Registrar no AgentBuilder¶

Você tem 3 opções de registro, dependendo do padrão de delegação:

Opção A — Sub-agent always-on (multi-turn)¶

Agentes que devem estar sempre disponíveis (ex: discovery_agent, quote_agent, booking_info_agent, utils_agent, support_agent).

Em agent_builder.py, adicione à lista _ALWAYS_ON_SUB_AGENTS:

_ALWAYS_ON_SUB_AGENTS = [
    ...
    meu_novo_agent,
]

Opção B — Sub-agent condicional (multi-turn, com feature flag)¶

Adicionar flag em config/feature_flags.py:

_FLAG_REGISTRY = {
    ...
    "ENABLE_MEU_NOVO": (True, "Habilita meu_novo_agent", []),
}

Se o agente depender de outra flag (ex: ENABLE_PAYMENT requer ENABLE_BOOKING), adicione no array de dependências.

Adicionar mapeamento em agent_builder.py:

_FLAG_TO_AGENT = {
    ...
    "ENABLE_MEU_NOVO": meu_novo_agent,
}

Opção C — AgentTool (call-and-return)¶

Para agentes que devem retornar o resultado ao orquestrador (ex: research_agent), adicione à lista tools no método build():

tools = [
    PreloadMemoryTool(),
    AgentTool(agent=research_agent),
    AgentTool(agent=meu_novo_agent),  # <-- novo
    faq_tool,
]

Passo 4: Adicionar rota no prompt do orquestrador¶

Em ifriend_agent/prompts/orchestrator_prompt.py:

ROUTING_HINTS = {
    ...
    "meu_novo_agent": "→ meu_novo_agent: [quando delegar para este agente]",
}

Se for condicional, adicione também em DISABLED_HINTS:

DISABLED_HINTS = {
    ...
    "meu_novo_agent": "⚠️ [Funcionalidade] NÃO está habilitada neste momento.\n...",
}

As rotas são geradas automaticamente no prompt final pelo build_orchestrator_instruction(). Só agentes ativos aparecem no prompt.

Passo 5: Criar testes¶

Em ifriend_agent/tests/test_sub_agents.py:

class TestMeuNovoAgent:
    def test_is_llm_agent(self):
        assert isinstance(meu_novo_agent, LlmAgent)

    def test_name(self):
        assert meu_novo_agent.name == 'meu_novo_agent'

    def test_tools_count(self):
        assert len(meu_novo_agent.tools) == 2

Estrutura de um Bom Agent Prompt¶

Role — Quem é o agente
Regras — O que ele pode/cannot fazer
Fluxo — Passo a passo da execução
Exemplos — Few-shot examples se necessário
Transferência — Quando transferir de volta ao root

Dicas¶

Use disallow_transfer_to_peers=True para todos os sub-agents — eles só podem transferir de volta ao root_agent
Mantenha o prompt conciso (idealmente < 50 linhas)
Não inclua dados sensíveis nos prompts
Implemente a regra de escape: se o usuário pedir algo fora do domínio, transfira ao root_agent imediatamente
Use static_instruction para payloads JSON grandes (ex: booking_agent) — o ADK cacheia automaticamente
Tools compartilhadas são permitidas entre agents que operam na mesma base de dados (ex: discovery + itinerary compartilham tools de busca)
Sempre registre no __all__ de agents/__init__.py

Comportamento customizado por Affiliate¶

Este guia cobre agentes e feature flags globais. Se o que você precisa é um comportamento que varia por affiliate (ex: FAQ customizado, URL de reserva customizada), o padrão é diferente — não use _FLAG_REGISTRY/_FLAG_TO_AGENT para isso. Veja Estendendo a Configuração do Agente.