← Studio

# Agente de IA — Survey Studio (opção A)

Documentação de manutenção. **Prompts não são editáveis em produção** — ficam versionados neste repositório.

Para o **agente de voz 3C Plus** (mailing, WhatsApp, callStudy, n8n), ver `04_surveyjs/docs/AGENT_3C_PLUS.md` e `04_surveyjs/agente/prompt/` — é outro produto.

## Decisão

| Escolha | Detalhe |
|---------|---------|
| Arquitetura | **Opção A** — chat + tools HTTP sobre a API admin existente |
| Diff | Via `survey_versions` (histórico já gravado) |
| Prompts | Só neste arquivo / git — sem CMS de prompt |
| Publish | Sempre com confirmação humana |
| Draft IA | `PATCH` com `skipVersion: true` — atualiza `surveys` sem nova linha em `survey_versions` |
| Versão | Só no **Salvar** explícito do Studio (`note: studio_json`) |

Não construir IDE custom nem editor de prompt no Studio.

## Tools previstas (quando implementar o chat)

Todas com header `X-Admin-Token`:

| Tool | Endpoint |
|------|----------|
| list_folders | `GET /v1/folders` |
| create_folder | `POST /v1/folders` |
| list_surveys | `GET /v1/surveys` |
| get_survey | `GET /v1/surveys/{id}` |
| create_survey | `POST /v1/surveys` |
| patch_survey | `PATCH /v1/surveys/{id}` |
| set_status | `POST /v1/surveys/{id}/status` |
| list_versions | `GET /v1/surveys/{id}/versions` |
| restore_version | `POST /v1/surveys/{id}/versions/{n}/restore` |
| list_responses | `GET /v1/admin/responses` |
| reopen_response | `POST /v1/admin/responses/{id}/reopen` |

## Contexto fixo do system prompt (rascunho)

1. SurveyJS Form Library schema (`pages`, `elements`, tipos, validators)
2. Uploads: `storeDataAsText: false` + API `/v1/uploads`
3. Prefill: nomes de pergunta → `data`; resto → `customs`
4. `settings.webhooks`: `onStarted` / `onCompleted` / `onFiltered` · `settings.filters` (screen-out → status `filtro`)
5. URL pública: env `PUBLIC_BASE_URL` + `/{publicName}` (hoje legado ou `r.`)
6. Resume: `{PUBLIC_BASE_URL}/r/{responseId}`
7. **Piping:** `{questionName}` no `title`/`description` — interpretar pedidos tipo “{nota da q1}” como referência ao `name` da pergunta, não texto fixo
8. **visibleIf** para “se sim / se não”

## Regras de segurança

- Não expor token no chat do usuário final
- Não executar SQL direto
- Não publish automático sem confirmação
- Toda alteração de JSON gera versão

## Survey Creator “já vem com IA”?

**Não.** O Survey Creator é o editor visual/JSON. A [IA oficial SurveyJS](https://surveyjs.io/faq/ai) é um **exemplo de integração**: você pluga um LLM (sua API), monta um chat e aplica o JSON gerado no Creator. Não há modelo incluso na licença do Creator.

## Opção A (este doc) vs IA oficial SurveyJS

| | Opção A (GMR) | IA oficial SurveyJS |
|--|---------------|---------------------|
| Onde | Chat no nosso Studio | Painel no Survey Creator |
| Como altera o form | Tools HTTP → `PATCH /v1/surveys` (+ versões) | Gera JSON e atribui ao Creator (`creator.JSON`) |
| LLM | Nosso (escolhemos) | Nosso (SurveyJS só mostra o padrão) |
| Status aqui | Spec pronta; UI backlog | Exige Creator embutido de novo |

Prefill de teste na URL pública: `?isTest=true` → `customs.isTest` (não é pergunta do schema).

### Fluxo Studio (atual)

1. Alterar `surveyJson` no textarea (assistente Opção A, quando existir, ou colar do Creator).
2. **Salvar** (+ **Pub** se ainda draft).
3. **Atualizar preview** → iframe com `/{publicName}?isTest=true`.
4. Ou **Abrir em nova guia** / colar estrutura nova no Creator e devolver ao textarea.

## Endpoint chat

| | |
|--|--|
| Status | `GET /v1/admin/agent/status` → `{ provider, model, configured }` |
| Chat | `POST /v1/admin/agent/chat` body: `{ surveyId?, title?, publicName?, surveyJson, message, history? }` |
| Env | `OPENAI_API_KEY`, `LLM_PROVIDER=openai`, `LLM_MODEL` (default `gpt-4.1-mini`) |

Resposta: `{ reply, summary, surveyJson|null, model, usage }`. O Studio aplica `surveyJson` no editor e faz `PATCH` com `skipVersion: true`.

## Status

Preview isTest + UI chat Opção A (OpenAI): feito. Anthropic/Grok: backlog.