Agentes de IA

Responsabilidades separadas

O projeto possui três agentes conversacionais: Triagem, Qualificação e Coleta. São papéis de prompt acionados pelo estado da sessão, usando o mesmo contrato de saída e a mesma interface LLMClient. Não são processos autônomos com ferramentas livres: o modelo propõe um código s, e o dispatcher interpreta as ações permitidas.

Agente	Estado	Responsabilidade	Prompt
Triagem	TRIAGE	Receber, identificar segmento/intenção e encaminhar	src/core/agents/triagem/system_prompt.py
Qualificação	QUALIFYING	Identificar serviço canônico e coletar parâmetros	src/core/agents/qualificacao/system_prompt.py
Coleta	DATA_COLLECT, CONFIRM	Coletar cadastro e pedir confirmação	src/core/agents/coleta/system_prompt.py

AgentName também contém orchestrator e summary, usados no log/suporte. Isso não cria um quarto ou quinto agente selecionável pela máquina de estados. O resumo operacional é uma chamada separada com JSON puro, diferente de {JSON}Mensagem.

Invocação

src/core/application/agent_invoker.py define o Protocol AgentInvoker.invoke(...). A implementação real AgentInvokerImpl, em src/core/agents/invoker.py, recebe settings, cliente LLM, KB e repositories opcionais de prompts/configuração. Seu retorno é LLMCallResult(raw_response, model, tokens_input, tokens_output, latency_ms).

flowchart TD
    S[Estado da sessão] --> A[Selecionar agente]
    A --> P[Builder do system prompt]
    DB[Override administrativo ativo] --> P
    P --> G[Adicionar guards fixos]
    H[Histórico somente da sessão] --> M[Montar mensagens system/user/assistant]
    K[Packages solicitados] --> P
    G --> M
    M --> L[LLMClient.chat / Responses API]
    L --> R[Parser estrito e dispatcher]
    R -->|s=99| K
    R -->|próximo agente| A
    R --> O[Persistir ação e retornar resposta]

O invocador consulta todos os IDs disponíveis na KB e injeta o catálogo compacto no prompt. Somente conteúdo de packages já coletados entra integralmente. Histórico INBOUND vira user, OUTBOUND vira assistant, eventos SYSTEM e mensagens com error="superseded" são excluídos. Há dupla proteção de session_id: no repository e no invocador. A mensagem atual não é duplicada quando já consta como última entrada do usuário.

Metadados e configuração

Toda chamada recebe identidade, instância, horário comercial e catálogo/contextos. Qualificação recebe segmento, intenção e dados técnicos parciais; Coleta recebe telefone e cadastro parcial. Triagem recebe nome reconhecido e configuração de empresas estratégicas. O builder da Coleta aceita serviço e qualificação como parâmetros, mas a interpolação atual do prompt usa principalmente cadastro, segmento e histórico; não se deve assumir que cada parâmetro aceito aparece textualmente no prompt final.

OPENAI_MODEL_TRIAGE, OPENAI_MODEL_QUALIFICATION e OPENAI_MODEL_COLLECTION selecionam modelos por papel; OPENAI_MODEL_SUMMARY serve resumo e reparo de formato. Os defaults de load_settings() são gpt-4o-mini; outras fontes de configuração podem sobrescrevê-los. MAX_HISTORY_MESSAGES tem default 50, MAX_CONTEXT_ENRICHMENTS_PER_MESSAGE default 2. Consulte a referência de configuração.

Regras fixas e overrides

Prompts podem ser sobrescritos por VersionedResourceRepository. Após renderizar o override, _with_runtime_guards() acrescenta identidade única baseada em AGENT_NAME, instância/segmento/intenção, proibição de prometer prazo humano e regra de confirmar troca de assunto. Em Qualificação/Coleta, contexto GoYou ou segmento HUMANO acrescenta limites de saúde mesmo sem package injetado.

Isso torna algumas instruções resistentes à remoção pelo editor de prompt. Não é um validador semântico de toda frase do modelo: validação programática cobre formato, códigos, enums e campos específicos; veracidade clínica/comercial continua exigindo prompt, conhecimento confiável e testes.

Falhas e manutenção

Parse inválido recebe uma tentativa de reparo; código inválido não é aceito apenas porque o JSON é válido. Package desconhecido, limite de enriquecimento ou incerteza levam ao humano. O caso de uso controla persistência, CRM e envio; o invocador apenas monta e faz a chamada.

tests/unit/agents/test_invoker.py verifica modelo por agente, histórico, não duplicação, metadados e guards após override. tests/unit/agents/test_system_prompts.py verifica instruções dos builders. tests/unit/application/test_action_mapping.py e test_process_message_use_case.py verificam consequências determinísticas. Fixtures e integrações reais têm finalidade distinta; veja testes.

Ao alterar um agente, mantenha enum, dispatcher e prompt sincronizados, acrescente regressão pequena e revise a máquina de estados. Uma mudança apenas de estilo não deve introduzir um código ou estado novo. Consulte contrato e como modificar.