# ClientFlow v4928.1.5.6 — Fase 1: integração segura do agente de email

Esta versão integra o agente de respostas testado com conhecimento BLIF no fluxo seguro do ClientFlow.

## Objetivo

Gerar rascunhos editáveis para respostas a emails/mensagens de clientes, usando OpenAI Responses API + `file_search` sobre uma vector store de conhecimento BLIF.

A integração **não envia respostas automaticamente**. O operador continua a rever e enviar pelo painel da tarefa.

## Novos ficheiros / alterações principais

- `app/email_reply_agent_service.py`
  - Novo serviço de agente de email.
  - Chama OpenAI Responses API com `file_search`.
  - Devolve JSON estruturado: intenção, prioridade, resposta sugerida, revisão humana, confiança e informação usada.

- `app/reply_assistant_service.py`
  - Integra o agente como prioridade quando `CLIENTFLOW_EMAIL_REPLY_AGENT_ENABLED=true`.
  - Guarda metadata do agente em `message_drafts.metadata.email_agent`.
  - Mantém fallback para fluxo existente se o agente estiver desligado ou indisponível.

- `app/admin_ui/pages/tasks.py`
  - Mostra estado do agente no painel de resposta da tarefa.
  - Badge atualizado para `v4928.1.5.6`.

- `app/api/internal.py`
  - Novo endpoint interno:
    - `POST /api/internal/tasks/{task_id}/reply-draft`
  - Cria rascunho persistente e devolve JSON.
  - Protegido pelo mesmo `X-ClientFlow-Admin-Token` quando configurado.

- `.env.example`
  - Novas variáveis OpenAI/agent.

## Variáveis de ambiente

```env
CLIENTFLOW_EMAIL_REPLY_AGENT_ENABLED=false
OPENAI_API_KEY=
OPENAI_RESPONSES_URL=https://api.openai.com/v1/responses
OPENAI_VECTOR_STORE_ID=
CLIENTFLOW_EMAIL_REPLY_AGENT_MODEL=gpt-4.1-mini
CLIENTFLOW_EMAIL_REPLY_AGENT_TIMEOUT_SECONDS=30
CLIENTFLOW_EMAIL_REPLY_AGENT_MAX_RESULTS=6
CLIENTFLOW_EMAIL_REPLY_AGENT_PROMPT_VERSION=blif-email-agent-phase1-20260613
```

Para ativar em staging/produção:

```env
CLIENTFLOW_EMAIL_REPLY_AGENT_ENABLED=true
OPENAI_API_KEY=sk-proj-...
OPENAI_VECTOR_STORE_ID=vs_...
```

## Fluxo seguro

```text
Task ClientFlow
  ↓
Gerar rascunho
  ↓
Agente OpenAI/file_search consulta conhecimento BLIF
  ↓
Resposta JSON estruturada
  ↓
ClientFlow valida segurança
  ↓
Guarda em message_drafts
  ↓
Operador revê e envia manualmente
```

## Fallback

Se o agente estiver desligado, mal configurado ou indisponível, o ClientFlow mantém o fluxo anterior:

```text
business_knowledge_service + templates + OpenRouter opcional
```

Isto evita bloqueio da operação.

## API interna

Exemplo:

```bash
curl -X POST "https://clientflow.blif.pt/api/internal/tasks/<TASK_ID>/reply-draft" \
  -H "X-ClientFlow-Admin-Token: <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"selected_document_ids": []}'
```

Resposta resumida:

```json
{
  "draft_id": "...",
  "task_id": "...",
  "template_code": "LLM_BUSINESS_REPLY",
  "message_body": "...",
  "blockers": [],
  "warnings": [],
  "email_agent": {
    "used": true,
    "intencao": "pedido_preco",
    "precisa_revisao_humana": false,
    "nivel_confianca": "alto"
  }
}
```

## Guardrails principais

- Não enviar automaticamente.
- Não substituir bounces, respostas automáticas ou revisão manual por resposta comercial.
- Se o agente marcar revisão humana, mostrar aviso no painel.
- Se confiança baixa, bloquear envio até revisão/correção manual.
- Continuar a validar instalação, IVA, preços e promessas comerciais em `reply_safety_validator.py`.

## Nota sobre conhecimento

Esta integração usa a vector store indicada em `OPENAI_VECTOR_STORE_ID`. Para obter respostas com a versão mais recente do conhecimento BLIF, atualize a vector store no ambiente OpenAI e altere o ID no `.env`.
