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¶

Always-on (sempre ativo):¶

Em agent_builder.py:

_ALWAYS_ON_SUB_AGENTS = [
    ...
    meu_novo_agent,
]

Condicional (com feature flag):¶

Adicionar flag em config/feature_flags.py:

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

Adicionar mapeamento em agent_builder.py:

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

Passo 4: Adicionar rota no prompt do orquestrador¶

Em prompts/orchestrator_prompt.py:

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

Se for condicional:

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

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
Mantenha o prompt conciso (idealmente < 50 linhas)
Não inclua dados sensíveis nos prompts
Use tools compartilhadas quando possível