Fluxo: AI Assistant Pipeline¶

Visão Geral¶

O AI Assistant é um assistente de IA integrado ao portal administrativo que auxilia na criação e refinamento de conteúdo dos agentes. Cada seção do agente (prompt, base de conhecimento, etapas) possui um system prompt especializado que contextualiza a assistência.

Arquitetura¶

┌─────────────────────────────────────────────────────────────────────┐
│  POST /api/agents/{agentId}/ai-assistant/chat                       │
│  ► AiAssistantHandler (MediatR)                                     │
│  ► Pipeline<AiAssistantPipelineContext>                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────────┐                                               │
│  │ 1. LoadAgent     │ Carrega prompt do agente (cache Redis)        │
│  │    PromptStep    │ → context.AgentPrompt                         │
│  └────────┬─────────┘                                               │
│           ▼                                                         │
│  ┌──────────────────┐                                               │
│  │ 2. CheckAi       │ Verifica créditos da subscription             │
│  │    CreditsStep   │ → context.HasSubscription                     │
│  └────────┬─────────┘                                               │
│           ▼                                                         │
│  ┌──────────────────┐                                               │
│  │ 3. BuildSystem   │ Monta system blocks com prompt template       │
│  │    BlocksStep    │ especializado pela sectionKey                  │
│  │                  │ → context.SystemBlocks                         │
│  └────────┬─────────┘                                               │
│           ▼                                                         │
│  ┌──────────────────┐                                               │
│  │ 4. GenerateAi    │ Chama Claude API via ILlmClient               │
│  │    ResponseStep  │ → context.LlmResponse                         │
│  └────────┬─────────┘                                               │
│           ▼                                                         │
│  ┌──────────────────┐                                               │
│  │ 5. ConsumeAi     │ Decrementa crédito da subscription            │
│  │    CreditStep    │ + notifica frontend via SignalR                │
│  └────────┬─────────┘                                               │
│           ▼                                                         │
│  ┌──────────────────┐                                               │
│  │ 6. TrackAi       │ Registra uso de tokens (fire-and-forget)      │
│  │    UsageStep     │ via ILlmUsageTracker                          │
│  └────────┬─────────┘                                               │
│           ▼                                                         │
│  ┌──────────────────┐                                               │
│  │ 7. ParseAi       │ Faz parse do JSON retornado pelo LLM          │
│  │    ResponseStep  │ → context.Result (AgentAiAssistantResponse)   │
│  └──────────────────┘                                               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Contexto do Pipeline¶

AiAssistantPipelineContext
├── Input (init)
│   ├── Request: AgentAiAssistantRequest
│   └── TenantId: Guid
├── Loaded
│   ├── AgentPrompt: string?          ← LoadAgentPromptStep
│   └── HasSubscription: bool         ← CheckAiAssistantCreditsStep
├── Built
│   └── SystemBlocks: List<SystemPromptBlock>  ← BuildSystemBlocksStep
├── Generated
│   └── LlmResponse: LlmResponse?    ← GenerateAiAssistantResponseStep
└── Output
    └── Result: Result<AgentAiAssistantResponse>?  ← ParseAiAssistantResponseStep

Seções e Prompt Templates¶

Cada sectionKey carrega um system prompt especializado:

SectionKey	Template	Propósito
`prompt`	`system-prompt-prompt.md`	Assistência na criação do prompt principal do agente
`knowledge`	`system-prompt-knowledge.md`	Assistência na criação de blocos de conhecimento
`step`	`system-prompt-step.md`	Assistência na criação de instruções de etapas
`step_planner`	`system-prompt-step-planner.md`	Planejamento e geração de etapas completas

Templates ficam em: Infrastructure/Prompts/AiAssistant/

Prompt Caching¶

Os templates usam marcadores {{CACHE_BREAK}} para habilitar prompt caching na Claude API. O conteúdo antes do marcador é cacheado (instruções do sistema), e o conteúdo após (contexto do agente) varia por request.

Formato da Resposta do LLM¶

O assistente responde em JSON com a seguinte estrutura:

{
  "suggested_content": "conteúdo sugerido para aplicar na seção",
  "message": "explicação textual para o usuário",
  "quick_replies": ["Sugestão 1", "Sugestão 2"]
}

O ParseAiAssistantResponseStep faz o parse e mapeia para AgentAiAssistantResponse.

Arquivos Relevantes¶

Arquivo	Descrição
`Api/Features/Agents/AiAssistant/AiAssistantHandler.cs`	Handler MediatR que orquestra o pipeline
`Api/Features/Agents/AiAssistant/AiAssistantEndpoints.cs`	Endpoint Minimal API
`Api/Features/Agents/AiAssistant/Pipeline/`	Steps do pipeline (7 steps)
`Shared/Features/Agents/AiAssistant/`	Request, Response, Validator
`Shared/Constants/AiAssistantSections.cs`	Constantes das section keys
`Infrastructure/Prompts/AiAssistant/`	Templates de system prompt
`Infrastructure/Configuration/AiAssistantConfig.cs`	Configuração (modelo, tokens, temperatura)