1. Propósito e Escopo
Este documento define todos os prompts, configurações de memória, transição entre estados, ferramentas como chamadas a sistemas externos e demais requisitos funcionais para o Fluxo de Agentes "Monitoramento de Portfólio de Investimentos", uma solução de automação projetada para analisar continuamente o desempenho dos investimentos de um cliente e sugerir ajustes com base em mudanças de mercado. Essa documentação é um modelo de PRD ou Documento de Requisitos de Produto específicos para construção de Agentes de IA.
O objetivo principal é implementar um sistema que monitore continuamente os portfólios de investimento dos clientes, identifique mudanças de mercado significativas e sugira ajustes no portfólio para otimizar o desempenho.
2. Contexto e Problema
Cenário Atual
Atualmente, o monitoramento dos portfólios de investimento dos clientes é inadequado e não contínuo, o que resulta em uma falta de reatividade às mudanças de mercado que afetam o desempenho dos investimentos.
- Monitoramento inadequado e não contínuo dos portfólios de investimento dos clientes.
- Falta de reatividade às mudanças de mercado que afetam o desempenho dos investimentos.
Problemas Identificados
- Consumo de tempo: O processo manual de análise e ajustes nos portfólios consome um tempo valioso dos assessores de investimento, que poderia ser usado para prospecção e atendimento ao cliente.
- Atraso na reação: A demora na identificação e resposta a mudanças de mercado pode resultar em perdas financeiras para os clientes.
- Falta de padronização: A análise manual está sujeita a diferentes interpretações, resultando em recomendações inconsistentes.
- Dependência de outros times: Frequentemente, os assessores precisam consultar equipes técnicas para obter dados de mercado atualizados, gerando gargalos e consumindo recursos de outras áreas.
- Risco de erros: Estimativas manuais são propensas a erros, que podem levar a decisões de investimento inadequadas.
3. Impactos Esperados
A implementação deste fluxo de automação visa alcançar os seguintes resultados:
- Reduzir o tempo de análise e ajuste de portfólios em pelo menos 70%.
- Padronizar a qualidade e a consistência das recomendações de investimento.
- Aumentar a precisão na identificação de mudanças de mercado e na resposta a elas.
- Eliminar a dependência de equipes técnicas para a obtenção de dados de mercado.
- Melhorar a satisfação do cliente, permitindo que os clientes tenham um desempenho de investimento otimizado.
4. Visão Geral da Solução
O agente de IA para monitoramento de portfólio de investimentos analisa continuamente o desempenho dos investimentos de um cliente, identifica mudanças de mercado significativas e sugere ajustes no portfólio para otimizar o desempenho. A seguir são detalhadas todas as regras de negócio e especificações funcionais necessárias para que esse agente atue como um assistente útil e autônomo no monitoramento e ajuste de portfólios de investimento.
A solução consiste em um fluxo de automação composto por 6 agentes de IA. O processo inicia com a obtenção de dados de mercado e posições do cliente e termina com a geração de alertas e recomendações de ajuste do portfólio.
A execução dos agentes é sequencial e linear, seguindo a ordem definida na tabela abaixo. O fluxo inclui etapas condicionais que são executadas apenas se critérios específicos forem atendidos, conforme detalhado após a tabela.
| Agentes | Função Principal |
|---|---|
Agente de Execução de Chamada à API - Cotações e Indicadores de Mercado (RF 1)
| Realizar chamada à API de mercado para obter séries de preços, volumes e benchmarks necessários ao monitoramento. |
Agente de Execução de Chamada à API - Posições do Cliente (RF 2)
| Realizar chamada à API do sistema de custódia/corretora para obter as posições e parâmetros do cliente. |
Agente de Normalização e Consolidação de Dados (RF 3)
| Unificar dados de mercado e posições, normalizar moedas e ajustar séries para permitir cálculo de desempenho. |
Agente de Monitoramento de Desempenho e Detecção de Eventos (RF 4)
| Calcular KPIs do portfólio e detectar mudanças significativas de mercado e de risco que exigem atenção. |
Agente de Análise e Recomendações de Ajuste do Portfólio (RF 5)
| Gerar recomendações de ajustes no portfólio para otimizar desempenho dentro dos limites de risco e restrições do cliente. |
Agente de Geração de Alertas e Priorização (RF 6)
| Transformar eventos e recomendações em alertas acionáveis com nível de severidade e contexto para o cliente/assessor. |
5. Protótipos
Para proporcionar uma visão clara e tangível da solução proposta, criamos protótipos interativos que demonstram tanto o fluxo de trabalho dos agentes quanto o resultado final que o cliente receberá. Explore os links abaixo para entender melhor a solução em ação.
6. Requisitos Funcionais
RF 1. Agente de Execução de Chamada à API - Cotações e Indicadores de Mercado
1.1 Tarefa do Agente
Realizar chamada à API de mercado para obter séries de preços, volumes e benchmarks necessários ao monitoramento.
1.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um payload JSON com informações sobre tickers, campos a serem consultados, faixas de tempo e outros parâmetros necessários para a chamada à API de mercado.
# 2. Objetivo
Realizar a chamada à API de mercado para obter os dados solicitados e retornar as informações em formato JSON.
# 3. Regras que você deve seguir para gerar sua resposta
- Execute a chamada à API exatamente conforme os parâmetros recebidos.
- Retorne os dados crus sem transformações, preservando a ordenação temporal crescente e os metadados do provedor.
# 4. Exemplo de Output que você deve produzir
{
"market_data": [
{
"ticker": "AAPL",
"timestamps": ["2025-12-01T14:00:00Z", "2025-12-01T15:00:00Z"],
"close": [150.00, 151.00],
"open": [149.00, 150.50],
"high": [151.50, 152.00],
"low": [148.50, 149.50],
"volume": [10000, 15000]
}
]
} 1.3 Configurações do Agente
1.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente é o ponto de partida do fluxo e deve ser acionado pelo envio de um payload JSON via API. Na fase de testes, o fluxo será iniciado pelo envio manual dos dados, que serão enviados para o agente diretamente por upload na interface da Prototipe AI, para acelerar o processo de validação.
- Tipo do input: O input inicial para o fluxo é um payload JSON contendo informações sobre tickers e parâmetros para a chamada à API de mercado.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 5.000 caracteres.
1.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo os dados de mercado obtidos.
-
Exemplo de Estrutura de Output:
{ "market_data": [ { "ticker": "AAPL", "timestamps": ["2025-12-01T14:00:00Z", "2025-12-01T15:00:00Z"], "close": [150.00, 151.00], "open": [149.00, 150.50], "high": [151.50, 152.00], "low": [148.50, 149.50], "volume": [10000, 15000] } ] } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 2.000 caracteres.
1.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
1.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Não utiliza.
- Busca Online: Não utiliza.
- Sistemas Externos: Conecta-se à API de mercado para obter dados financeiros.
1.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Normalização e Consolidação de Dados (RF 3).
1.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Execução de Chamada à API - Posições do Cliente (RF 2).
RF 2. Agente de Execução de Chamada à API - Posições do Cliente
2.1 Tarefa do Agente
Realizar chamada à API do sistema de custódia/corretora para obter as posições e parâmetros do cliente.
2.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um payload JSON com informações sobre o cliente, incluindo identificador, data de referência e outros parâmetros necessários para a chamada à API do sistema de custódia/corretora.
# 2. Objetivo
Realizar a chamada à API do sistema de custódia/corretora para obter as posições e parâmetros do cliente e retornar as informações em formato JSON.
# 3. Regras que você deve seguir para gerar sua resposta
- Execute a chamada à API exatamente conforme os parâmetros recebidos.
- Retorne os dados crus sem transformações, preservando a estrutura e os metadados recebidos.
# 4. Exemplo de Output que você deve produzir
{
"positions": [
{
"asset_id": "XYZ123",
"ticker": "AAPL",
"quantity": 100,
"avg_cost": 145.00,
"currency": "USD"
}
],
"cash_balance": 5000.00
} 2.3 Configurações do Agente
2.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 1).
- Tipo do input: Este agente deve ser apto a receber como input um payload JSON contendo informações sobre o cliente e parâmetros para a chamada à API do sistema de custódia/corretora.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 5.000 caracteres.
2.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo as posições e parâmetros do cliente obtidos.
-
Exemplo de Estrutura de Output:
{ "positions": [ { "asset_id": "XYZ123", "ticker": "AAPL", "quantity": 100, "avg_cost": 145.00, "currency": "USD" } ], "cash_balance": 5000.00 } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 2.000 caracteres.
2.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
2.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Não utiliza.
- Busca Online: Não utiliza.
- Sistemas Externos: Conecta-se à API do sistema de custódia/corretora para obter dados de posições do cliente.
2.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Normalização e Consolidação de Dados (RF 3).
2.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Normalização e Consolidação de Dados (RF 3).
RF 3. Agente de Normalização e Consolidação de Dados
3.1 Tarefa do Agente
Unificar dados de mercado e posições, normalizar moedas e ajustar séries para permitir cálculo de desempenho.
3.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo dados de mercado e posições do cliente em formato JSON, além de parâmetros para normalização e consolidação dos dados.
# 2. Objetivo
Unificar os dados recebidos, normalizar moedas e ajustar séries para permitir o cálculo de desempenho do portfólio.
# 3. Regras que você deve seguir para gerar sua resposta
- Use o preço de fechamento como referência para cálculos.
- Ajuste quantidades e custos em caso de eventos corporativos, mantendo o valor de mercado inalterado.
- Converta preços para a moeda base usando a taxa de câmbio mais recente disponível.
# 4. Exemplo de Output que você deve produzir
{
"consolidated_portfolio": [
{
"ticker": "AAPL",
"quantity": 100,
"price_in_base": 150.00,
"market_value_base": 15000.00
}
],
"totals": {
"aum_base": 20000.00,
"cash_base": 5000.00
}
} 3.3 Configurações do Agente
3.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 2).
- Tipo do input: Este agente deve ser apto a receber como input dados de mercado e posições do cliente em formato JSON, além de parâmetros para normalização e consolidação.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 10.000 caracteres.
3.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo o portfólio consolidado e normalizado.
-
Exemplo de Estrutura de Output:
{ "consolidated_portfolio": [ { "ticker": "AAPL", "quantity": 100, "price_in_base": 150.00, "market_value_base": 15000.00 } ], "totals": { "aum_base": 20000.00, "cash_base": 5000.00 } } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 3.000 caracteres.
3.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
3.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Utiliza lógica interna para cálculos de consolidação e normalização.
- Busca Online: Não utiliza.
- Sistemas Externos: Não utiliza.
3.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Monitoramento de Desempenho e Detecção de Eventos (RF 4).
3.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Monitoramento de Desempenho e Detecção de Eventos (RF 4).
RF 4. Agente de Monitoramento de Desempenho e Detecção de Eventos
4.1 Tarefa do Agente
Calcular KPIs do portfólio e detectar mudanças significativas de mercado e de risco que exigem atenção.
4.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um portfólio consolidado e normalizado em formato JSON, além de parâmetros para cálculo de KPIs e detecção de eventos.
# 2. Objetivo
Calcular os KPIs do portfólio e detectar mudanças significativas de mercado e de risco que exigem atenção.
# 3. Regras que você deve seguir para gerar sua resposta
- Calcule os retornos e volatilidade do portfólio com base nas séries de preços alinhadas.
- Detecte eventos significativos como variações intraday e concentração excessiva de ativos.
# 4. Exemplo de Output que você deve produzir
{
"performance_snapshot": {
"timestamp_ref": "2025-12-02T13:23:00Z",
"kpis": {
"ret_1d": 0.02,
"volatilidade_21d": 0.15
},
"eventos_detectados": [
{
"tipo": "var_intraday",
"alvo": "AAPL",
"valor_observado": 0.05,
"limiar": 0.03,
"severidade": "alta"
}
]
}
} 4.3 Configurações do Agente
4.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 3).
- Tipo do input: Este agente deve ser apto a receber como input um portfólio consolidado e normalizado em formato JSON, além de parâmetros para cálculo de KPIs e detecção de eventos.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 8.000 caracteres.
4.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo o snapshot de desempenho do portfólio e eventos detectados.
-
Exemplo de Estrutura de Output:
{ "performance_snapshot": { "timestamp_ref": "2025-12-02T13:23:00Z", "kpis": { "ret_1d": 0.02, "volatilidade_21d": 0.15 }, "eventos_detectados": [ { "tipo": "var_intraday", "alvo": "AAPL", "valor_observado": 0.05, "limiar": 0.03, "severidade": "alta" } ] } } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 2.500 caracteres.
4.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
4.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Utiliza lógica interna para cálculos de KPIs e detecção de eventos.
- Busca Online: Não utiliza.
- Sistemas Externos: Não utiliza.
4.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Análise e Recomendações de Ajuste do Portfólio (RF 5).
4.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Análise e Recomendações de Ajuste do Portfólio (RF 5).
RF 5. Agente de Análise e Recomendações de Ajuste do Portfólio
5.1 Tarefa do Agente
Gerar recomendações de ajustes no portfólio para otimizar desempenho dentro dos limites de risco e restrições do cliente.
5.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um snapshot de desempenho do portfólio e eventos detectados em formato JSON, além de parâmetros e restrições do cliente para gerar recomendações de ajuste do portfólio.
# 2. Objetivo
Gerar recomendações de ajustes no portfólio para otimizar o desempenho dentro dos limites de risco e restrições do cliente.
# 3. Regras que você deve seguir para gerar sua resposta
- Proponha ajustes no portfólio com base nos eventos detectados e nas metas de risco do cliente.
- Considere as restrições de alocação e limites de risco ao gerar as recomendações.
# 4. Exemplo de Output que você deve produzir
{
"recommendations": {
"racional_geral": "Ajustar exposição em AAPL devido a variação intraday significativa.",
"trades": [
{
"ticker": "AAPL",
"acao": "sell",
"quantidade": 10,
"motivo_principal": "var_intraday",
"impacto_peso_pct": 0.05
}
]
}
} 5.3 Configurações do Agente
5.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 4).
- Tipo do input: Este agente deve ser apto a receber como input um snapshot de desempenho do portfólio e eventos detectados em formato JSON, além de parâmetros e restrições do cliente.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 8.000 caracteres.
5.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo as recomendações de ajustes no portfólio.
-
Exemplo de Estrutura de Output:
{ "recommendations": { "racional_geral": "Ajustar exposição em AAPL devido a variação intraday significativa.", "trades": [ { "ticker": "AAPL", "acao": "sell", "quantidade": 10, "motivo_principal": "var_intraday", "impacto_peso_pct": 0.05 } ] } } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 2.500 caracteres.
5.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
5.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Utiliza lógica interna para cálculos de recomendações de ajuste.
- Busca Online: Não utiliza.
- Sistemas Externos: Não utiliza.
5.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Geração de Alertas e Priorização (RF 6).
5.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Geração de Alertas e Priorização (RF 6).
RF 6. Agente de Geração de Alertas e Priorização
6.1 Tarefa do Agente
Transformar eventos e recomendações em alertas acionáveis com nível de severidade e contexto para o cliente/assessor.
6.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo recomendações de ajustes no portfólio e eventos detectados em formato JSON, além de preferências de notificação do cliente.
# 2. Objetivo
Transformar eventos e recomendações em alertas acionáveis com nível de severidade e contexto para o cliente/assessor.
# 3. Regras que você deve seguir para gerar sua resposta
- Mapeie a severidade dos eventos e priorize as recomendações de ajuste com base no impacto potencial.
- Formate os alertas de forma clara e acionável, incluindo passos concretos a serem seguidos.
# 4. Exemplo de Output que você deve produzir
{
"alerta": {
"titulo": "Ajuste Recomendado para AAPL",
"resumo": "Variação intraday significativa detectada.",
"severidade": "alta",
"prioridade": "alta",
"what": "var_intraday",
"why": "Variação de preço excedeu o limiar.",
"so_what": "Potencial impacto no desempenho do portfólio.",
"now_what": "Rebalancear ativo conforme recomendação.",
"canais": ["sistema", "email"]
}
} 6.3 Configurações do Agente
6.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 5).
- Tipo do input: Este agente deve ser apto a receber como input recomendações de ajustes no portfólio e eventos detectados em formato JSON, além de preferências de notificação do cliente.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 8.000 caracteres.
6.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo os alertas gerados a partir dos eventos e recomendações.
-
Exemplo de Estrutura de Output:
{ "alerta": { "titulo": "Ajuste Recomendado para AAPL", "resumo": "Variação intraday significativa detectada.", "severidade": "alta", "prioridade": "alta", "what": "var_intraday", "why": "Variação de preço excedeu o limiar.", "so_what": "Potencial impacto no desempenho do portfólio.", "now_what": "Rebalancear ativo conforme recomendação.", "canais": ["sistema", "email"] } } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 2.500 caracteres.
6.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
6.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Utiliza lógica interna para formatação de alertas.
- Busca Online: Não utiliza.
- Sistemas Externos: Não utiliza.
6.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente é o entregável final e não é passada para outros agentes internos.
6.3.6 Regras de Orquestração e Transição
A execução deste agente finaliza o fluxo. Os alertas gerados são o resultado que deve ser disponibilizado ao usuário.