Google ADK: arquitectura multi-agente, orquestación y routing

Usuario: ¿Está bien comprar NVDA a este precio?
         ↓
financial_advisor (orquestador)
  → Esta pregunta es sobre análisis de una acción específica
  → delega a stock_research_agent
         ↓
stock_research_agent
  → llama analyze_stock_fundamentals(NVDA)
  → llama get_analyst_ratings(NVDA)
  → llama compare_sector_peers(NVDA)
  → formula respuesta con los resultados
         ↓
financial_advisor recibe la respuesta del especialista
  → presenta la respuesta al usuario

// src/agent.ts
import { LlmAgent } from '@google/adk';
import { budgetAgent } from './agents/budgetAgent.js';
import { investmentAgent } from './agents/investmentAgent.js';
import { stockResearchAgent } from './agents/stockResearchAgent.js';
import { personalAdvisorAgent } from './agents/personalAdvisorAgent.js';
// ...otros agentes

export const rootAgent = new LlmAgent({
  name: 'financial_advisor',
  model: 'gemini-3-flash-preview',
  instruction: `Sos FinancialAdvisorAI...

  Tu equipo de especialistas:
  - budget_savings_agent: presupuesto, ahorro, fondo de emergencia
  - stock_research_agent: análisis fundamental de acciones individuales
  - personal_investment_advisor: plan financiero personalizado completo
  ...`,
  subAgents: [
    budgetAgent,
    investmentAgent,
    portfolioAgent,
    goalPlannerAgent,
    riskAssessmentAgent,
    stockResearchAgent,
    personalAdvisorAgent,
  ],
});

// ❌ Demasiado vaga — el orquestador no puede discriminar
description: "Agente de inversiones",

// ✅ Específica sobre cuándo usar ESTE agente vs otros
description:
  "Especialista en análisis profundo de acciones individuales: " +
  "análisis fundamental (P/E, PEG, márgenes, deuda), ratings de analistas " +
  "y precio objetivo, calidad del dividendo, señales técnicas, y comparación " +
  "vs peers del sector. Usá este agente para due diligence antes de comprar " +
  "una acción específica. NO es para screening de ETFs ni análisis de mercado general.",

financial_advisor (raíz — solo routing, sin tools propias)
│
├── budget_savings_agent (4 tools)
│   ├── analyze_budget
│   ├── find_savings_opportunities
│   ├── project_savings_growth
│   └── calculate_emergency_fund
│
├── investment_research_agent (5 tools)
│   ├── get_investment_details
│   ├── screen_investments
│   ├── compare_investments
│   ├── get_market_overview
│   └── get_index_fund_recommendations
│
├── portfolio_manager_agent (3 tools)
│   ├── analyze_portfolio
│   ├── rebalance_portfolio
│   └── analyze_portfolio_performance
│
├── goal_planner_agent (4 tools)
│   ├── plan_retirement
│   ├── plan_home_purchase
│   ├── calculate_financial_independence
│   └── plan_education_fund
│
├── risk_assessment_agent (3 tools)
│   ├── assess_risk_profile
│   ├── stress_test_portfolio
│   └── analyze_debt_vs_invest
│
├── stock_research_agent (5 tools)            ← análisis de acciones específicas
│   ├── analyze_stock_fundamentals
│   ├── get_analyst_ratings
│   ├── analyze_dividend_quality
│   ├── get_technical_signals
│   └── compare_sector_peers
│
└── personal_investment_advisor (5 tools)     ← plan personalizado holístico
    ├── build_financial_profile
    ├── generate_personalized_portfolio
    ├── optimize_tax_strategy
    ├── analyze_net_worth
    └── plan_life_event

// src/agents/completePlanAgent.ts
import { SequentialAgent } from '@google/adk';
import { personalAdvisorAgent } from './personalAdvisorAgent.js';
import { riskAssessmentAgent } from './riskAssessmentAgent.js';
import { goalPlannerAgent } from './goalPlannerAgent.js';

export const completePlanAgent = new SequentialAgent({
  name: 'complete_financial_plan',
  description:
    'Análisis financiero completo en secuencia: ' +
    '(1) construye el perfil financiero y portfolio personalizado, ' +
    '(2) evalúa tolerancia al riesgo y hace stress testing, ' +
    '(3) mapea objetivos concretos (retiro, vivienda, FIRE, educación). ' +
    'Usá cuando el usuario quiere un plan COMPLETO y aportó toda su situación financiera.',
  subAgents: [personalAdvisorAgent, riskAssessmentAgent, goalPlannerAgent],
});

// riskAssessmentAgent.ts — guarda la evaluación de riesgo para que el goalPlannerAgent la lea
export const riskAssessmentAgent = new LlmAgent({
  name: 'risk_assessment_agent',
  model: config.model,
  outputKey: 'user_risk_profile', // ← guardado en session.state["user_risk_profile"]
  // ...
});

// src/agents/parallelAnalysisAgent.ts
import { ParallelAgent } from '@google/adk';
import { stockResearchAgent } from './stockResearchAgent.js';
import { riskAssessmentAgent } from './riskAssessmentAgent.js';

export const parallelAnalysisAgent = new ParallelAgent({
  name: 'stock_and_risk_parallel',
  description:
    'Análisis profundo de una acción Y evaluación de riesgo del usuario en paralelo. ' +
    'Usá cuando el usuario quiere saber tanto si una acción es buena como si encaja ' +
    'con su perfil de riesgo, en la misma consulta.',
  subAgents: [stockResearchAgent, riskAssessmentAgent],
});

¿Necesita el resultado de A para ejecutar B?
  Sí → SequentialAgent
  No → ParallelAgent (si la latencia importa)
        Delegaciones del orquestador (si la decisión es dinámica)

import { LoopAgent, LlmAgent, BaseAgent } from '@google/adk';
import type { InvocationContext } from '@google/adk';

// Agente árbitro — verifica si el research es suficientemente bueno
class ResearchQualityChecker extends BaseAgent {
  async *runAsyncImpl(context: InvocationContext) {
    const feedback = context.session.state.get('research_feedback');
    if (feedback?.status === 'pass') {
      // Research aprobado — señal de salida del loop
      yield { escalate: true };
    }
    // Si no hay señal, el LoopAgent vuelve a iterar desde el principio
  }
}

const researchLoop = new LoopAgent({
  name: 'research_loop',
  maxIterations: 3, // ← guardia de seguridad — evita loops infinitos en producción
  subAgents: [
    researchAgent, // hace el research
    judgeAgent, // evalúa la calidad y guarda feedback en session.state
    new ResearchQualityChecker({ name: 'quality_checker' }), // decide si continuar
  ],
});

// src/agent.ts — callback de inicialización de sesión
import type { CallbackContext } from '@google/adk';

const initializeSession = (context: CallbackContext): undefined => {
  if (!context.state.has('session_start')) {
    context.state.set('session_start', new Date().toISOString());
    context.state.set('conversation_turn', 0);
  }
  const turn = (context.state.get<number>('conversation_turn') ?? 0) + 1;
  context.state.set('conversation_turn', turn);

  // undefined → el agente continúa procesando normalmente
  return undefined;
};

export const rootAgent = new LlmAgent({
  name: 'financial_advisor',
  model: config.model,
  beforeAgentCallback: initializeSession,
  // ...
});

financial_advisor (raíz — routing + inicialización de sesión)
│
├── budget_savings_agent (4 tools)
├── investment_research_agent (5 tools)
├── portfolio_manager_agent (3 tools)
├── goal_planner_agent (4 tools)
├── risk_assessment_agent (3 tools, outputKey: user_risk_profile)
├── stock_research_agent (5 tools)
├── personal_investment_advisor (5 tools, outputKey: financial_profile)
│
├── complete_financial_plan [SequentialAgent]    ← plan holístico en secuencia
│   ├── personal_investment_advisor (paso 1)
│   ├── risk_assessment_agent (paso 2)
│   └── goal_planner_agent (paso 3)
│
└── stock_and_risk_parallel [ParallelAgent]      ← análisis concurrente
    ├── stock_research_agent ─────────────────────┐ ejecutan simultáneamente
    └── risk_assessment_agent ────────────────────┘