# Plattio Forms AI Form Agent

The AI Form Agent is an optional premium module. It is disabled by default and its PHP class is not loaded on public frontend requests. Provider and privacy controls are available in the dedicated **AI Agent** tab under **Plattio Forms → Settings**. Its CSS and JavaScript are enqueued only on that settings screen and the Plattio Forms builder while the module is active and licensed.

## Providers

The module supports bring-your-own-key connections to OpenAI and Anthropic. OpenAI requests use the Responses API with strict JSON-schema output. Anthropic requests use the Messages API with a strict tool schema. The model selector is restricted to the providers' current recommended model families. OpenAI offers GPT-5.6 Sol, Terra, and Luna; Anthropic offers Claude Fable 5, Opus 4.8, Sonnet 5, and Haiku 4.5. Submitted model values are validated against this server-side allowlist.

## Data sent to providers

A request may contain:

- The administrator's current AI conversation.
- The active WordPress user locale.
- A small website color palette.
- The list of supported Plattio Forms field types and active modules.
- A reduced current-form context containing the title, field IDs, types, labels, choices, required state, widths, non-secret presentation settings, and a recipient-safe notification summary when the administrator has allowed this option.

The module does not send stored entries, uploaded files, signatures, API keys, SMTP credentials, webhook header values, payment-card data, or arbitrary database content.

## Credential storage

Provider API keys are encrypted with the existing `Plattio_Forms_Secrets` helper. Sodium secretbox is preferred, with OpenSSL AES-256-GCM as the fallback. If authenticated encryption is unavailable, the settings page blocks reliable key storage and displays an administrator warning. Keys are decrypted only for server-to-server requests and are never localized to JavaScript.

## Generated output

The provider must return a constrained blueprint rather than arbitrary PHP, HTML, SQL, or JavaScript. The server validates and normalizes the blueprint against:

- A fixed allowlist of supported field types.
- Active module availability for Signature and Page Break fields.
- Sanitized labels, descriptions, placeholders, choices, field IDs, widths, limits, and styles.
- WordPress MIME and upload policies already enforced by the core form runtime.
- Fixed notification audience rules that prevent the model from choosing arbitrary recipient addresses.
- The existing Email Builder sanitizer when an email design is generated.

For a new form or an explicitly requested complete replacement, the normalized form is applied as a full builder schema. For a targeted request, such as renaming a field, changing choices, adjusting form settings, or updating a notification, the provider must return an `update` action containing only the requested changes. Plattio Forms converts that response into a constrained patch and leaves unrelated fields, settings, notifications, and designs untouched.

Both full builds and targeted patches are added to builder undo history and saved as drafts for administrator review. The AI module never publishes a generated form automatically.

## Request controls

- Capability checks require `manage_plattio_forms`.
- Every request uses a WordPress nonce.
- Messages and conversation length are capped.
- Requests are throttled per administrator.
- Provider endpoints are fixed constants, preventing administrator-controlled SSRF targets.
- HTTP redirects are disabled.
- Provider errors are sanitized before display.
- Conversations are not persisted by Plattio Forms.

Website owners remain responsible for reviewing provider privacy terms, data-processing arrangements, regional requirements, and the generated form before publishing it.


## Compatibility fixes

Version 2.1.2 sends the OpenAI system prompt through the Responses API `instructions` field and passes conversation turns as plain `user`/`assistant` messages. This avoids assigning the input-only `input_text` content type to assistant history. Provider refusals and incomplete outputs are handled explicitly before blueprint validation.

Version 2.1.3 uses a compact strict provider envelope containing `action`, `message`, `questions`, and `form_json`. The detailed form blueprint is encoded inside `form_json`, decoded with a bounded depth and size, and passed through the same server-side field, notification, settings, module, HTML, and recipient validation as before. This avoids provider grammar-compilation limits without allowing arbitrary code or bypassing Plattio Forms normalization.


## Task-aware updates and progress

Version 2.1.7 distinguishes between full form creation and targeted updates. The strict provider action allowlist includes `clarify`, `build`, and `update`. Update payloads can add, remove, reorder, or modify specific fields; change only supplied form settings; replace notifications when requested; and create or assign an email design without replacing the rest of the schema.

The builder applies updates through a dedicated patch API that preserves field IDs, unrelated configuration, and undo history. When a request is explicitly detected as a targeted edit, a provider response that incorrectly attempts a full build is corrected once and otherwise rejected before any builder data is changed. Progress plans are generated from the normalized operation. A field-only edit therefore shows field-edit, apply, and save stages, while a settings-only or notification job shows the corresponding stages. When clarification is required, progress enters a waiting state and resumes the same job after the administrator replies instead of restarting from the first step.


## Visual choice-card icons

Version 2.1.8 exposes the integrated Plattio Forms choice-icon allowlist to the AI Agent. When the agent creates a radio or checkbox field with `choice_style=cards`, each choice may include an exact built-in icon slug. The server strips an optional `dashicons-` prefix, validates the slug through `Plattio_Forms_Choice_Icons::sanitize()`, and stores only approved icons with `media_type=icon`. Unknown or invented icon names are discarded, and AI responses can never provide local image attachment IDs or arbitrary image URLs.

The safe current-form context includes the existing choice style, layout, media type, and validated icon slug. This lets targeted update requests modify visual options while preserving the rest of the form instead of triggering a full rebuild.
## Complete form translation

Version 2.1.9 treats a request to translate the complete current form as a targeted update, never as a rebuild. The agent receives only sanitized user-facing text and must preserve field IDs, choice values, media references, smart tags, recipients, logic, URLs, and all non-text configuration. It translates form and field text, upload prompts, choices, repeaters, navigation labels, confirmations, notifications, and linked email designs. The server validates translation coverage and retries once when any text path is missing; incomplete translations are rejected before changes are applied. Linked email designs are copied before translation so shared source templates are not modified.

## Suggested forms and WooCommerce product context

Version 2.2.2 shows localized suggested-form pills before the first agent request. When WooCommerce is active, the agent may use the `woocommerce_product` field for returns, warranties, repairs, support, and other product-selection workflows. Product selection remains a frontend, on-demand search by product name or SKU; the full WooCommerce catalog is not included in AI prompts.

