== Agent Builder Platform Reference ==

Agent Builder is a WordPress plugin for building and running AI assistants. Distributed free on WordPress.org and at agentic-plugin.com. Premium features require a license key (Personal or Agency tier).

Current version: 2.4.1 | Requires: WordPress 6.4+, PHP 8.1+

== Important Pages ==

https://agentic-plugin.com — Main website and homepage. Overview of the plugin, features, and getting started.
https://agentic-plugin.com/documentation/ — Full documentation hub. Covers setup, configuration, deployment, tools, and agent development.
https://agentic-plugin.com/pricing/ — Pricing page. Compare Free, Personal, and Agency license tiers and what each includes.
https://agentic-plugin.com/marketplace/ — Agent Marketplace. Browse, download, and install community-built assistants. Premium feature.
https://agentic-plugin.com/api-credits/ — API Credits. Purchase prepaid credits for premium services (RAG training, image generation, text-to-speech). Shared credit wallet across all services.
https://agentic-plugin.com/support/ — Support center. Submit tickets, browse FAQs, and get help with the plugin.
https://agentic-plugin.com/discussions/ — Community discussions. Ask questions, share agents, and connect with other users.
https://agentic-plugin.com/connecting-an-ai-provider/ — Provider setup guide. Step-by-step instructions for connecting OpenAI, Anthropic, Google, xAI, Mistral, Ollama, and other providers.
https://agentic-plugin.com/manage-llm-providers/ — Provider management. Configure provider API keys, models, and per-agent overrides.
https://agentic-plugin.com/agent-deployment/ — Deployment guide. How to deploy agents via shortcodes, modal widget, admin bar, Gutenberg blocks, and more.
https://agentic-plugin.com/using-shortcodes/ — Shortcode reference. Usage for [agentic_chat], [agentic_ask], and [agentic_form] shortcodes with attributes.
https://agentic-plugin.com/chat-interface/ — Chat interface documentation. Features, customization, voice input, file upload, and vision support.
https://agentic-plugin.com/chat-styles-and-themes/ — Chat styling. Customize colours, fonts, and layout of the chat interface with CSS variables and theme presets.
https://agentic-plugin.com/scheduled-tasks/ — Scheduled tasks guide. How agents run autonomously on a schedule via wp-cron.
https://agentic-plugin.com/event-automation/ — Event automation. How agents react to WordPress hooks like post publication, login failures, and comments.
https://agentic-plugin.com/agent-tools/ — Tools documentation. Browse available tools, risk levels, and how to build custom tools.
https://agentic-plugin.com/code-proposals/ — Code proposals. How the approval queue works for write operations in supervised mode.
https://agentic-plugin.com/permissions-and-safety/ — Permissions and safety. Agent modes, risk levels, permission scopes, and integrity verification.
https://agentic-plugin.com/important-security-settings/ — Security settings. Turnstile, rate limiting, anonymous chat, and IP anonymization configuration.
https://agentic-plugin.com/user-roles-and-privileges/ — User roles. Per-role daily query limits, token limits, and chat access control.
https://agentic-plugin.com/ai-data-training/ — Vector Store & RAG. Train agents on your content — posts, pages, PDFs, and documents for retrieval-augmented generation.
https://agentic-plugin.com/mcp-integration/ — MCP Integration. Turn any agent into an MCP server. STDIO and HTTP transport support.
https://agentic-plugin.com/installed-agents/ — Agent management. Activate, configure, and manage installed agents.
https://agentic-plugin.com/submit-agent/ — Submit an agent. Developer guide for publishing agents to the marketplace.
https://agentic-plugin.com/audit-log/ — Audit log. View and filter all agent actions by date, agent, and action type.
https://agentic-plugin.com/agent-performance/ — Performance. Caching, conditional loading, and optimization settings.
https://agentic-plugin.com/backups/ — File backups. How the backup system protects files before agent write operations.
https://agentic-plugin.com/changelog/ — Changelog. Full version history with feature additions, fixes, and improvements.
https://agentic-plugin.com/my-account/#licenses — License management. View active licenses, activations, and expiry dates.
https://agentic-plugin.com/my-account/#transactions — Transaction history. View credit purchases and usage history.
https://agentic-plugin.com/terms-of-service/ — Terms of Service.
https://agentic-plugin.com/privacy-policy/ — Privacy Policy.
https://agentic-plugin.com/gdpr-policy/ — GDPR Policy. Data processing, retention, and compliance details.

== Bundled Assistants (free, included with plugin) ==

1. WordPress Assistant — onboarding guide and Q&A. Read-only.
2. Content Writer — creates, edits, publishes posts and pages. Gutenberg sidebar integration.
3. SEO Assistant — audits and fixes on-page SEO. Works with Yoast, Rank Math, or standalone.
4. Security Assistant — monitors failed logins, outdated plugins, file tampering, user accounts.
5. Site Doctor — diagnoses database bloat, broken links, PHP errors. A-F health grading.
6. AI Radar — scores AI search visibility 0-100 (ChatGPT, Perplexity, Gemini). Weekly monitoring.
7. Assistant Trainer — meta-assistant that creates new assistants from plain English descriptions.
8. Site Auditor — full-site audit across 20 metrics (SEO, links, metadata, accessibility, Core Web Vitals).
9. Media Assistant — AI image generation, editing, upscaling via Imagen 4. Requires prepaid credits.
10. Forms Builder — creates contact forms from descriptions. [agentic_form id="X"] shortcode.

== AI Providers ==

10 supported providers. Users configure one as default; per-agent overrides are supported.

- Agentic AI — free built-in provider, no API key needed (default on fresh installs)
- OpenAI — GPT-4o, o3+
- Anthropic — Claude Sonnet, Opus
- Google — Gemini 2.0+
- xAI — Grok
- Mistral
- Meta Llama
- Cohere
- Ollama — 100% local, no external requests
- Custom — any OpenAI-compatible endpoint

Each provider supports dual models: a chat/reasoning model and a separate vision model.
Per-agent overrides: any agent can use a different provider, model, and operating mode.
Configuration: Agentic > Settings > Providers tab, or per-agent in Agentic > Settings > Agents tab.

== Agent Modes ==

Three operating modes (global default + per-agent override):
- supervised (default) — agent pauses for confirmation on write actions
- autonomous — agent executes without confirmation
- disabled — agent cannot run

== Tools & Abilities ==

137+ tools organized by category: database, plugins, themes, agents, wordpress.
Tools follow OpenAI function calling schema. Each tool has a 5-tier risk level:
- none — read-only, auto-executes
- low — minor side effects, auto-executes
- medium — moderate impact, may pause for approval
- high — significant changes, pauses in supervised mode
- extreme — disabled by default, must be explicitly enabled

Core database tools: db_get_option, db_update_option, db_get_posts, db_get_post, db_create_post, db_update_post, db_delete_post, db_get_users, db_get_terms, db_get_post_meta, db_get_comments.

File tools: read_file, list_directory, search_code, request_code_change (with backup).

Other key tools: manage_schedules, fetch_rendered_page, run_wp_cli, optimize_post_title.

Each agent declares which tools it can access via abilities.json with per-tool risk levels.
Runtime integrity verification: abilities.json is signed with HMAC-SHA256. Tampered or unsigned agents are blocked.

== Deployment Options ==

Agents can be invoked through multiple channels:

1. Chat interface — real-time conversation in the admin panel or frontend
2. Shortcodes — [agentic_chat] (full chat), [agentic_ask] (one-shot inline response)
3. Gutenberg Blocks — embed chat interface in any page via block editor
4. Modal widget — floating chat bubble on frontend pages (per-agent position, page targeting, login requirements)
5. Admin bar — toolbar chat overlay (per-agent, configurable for admin/frontend/everywhere)
6. Scheduled tasks — time-based autonomous execution via wp-cron
7. Event listeners — hook-driven, reacts to WordPress actions (e.g. post published, comment posted)
8. CLI — wp agent prompt <slug> "message"
9. Gutenberg sidebar — in-editor AI assistance that reads live draft context

Modal and admin bar support per-agent configuration: each agent can have its own position, page targeting rules, and visibility settings.

== Scheduled Tasks ==

Agents can define recurring tasks that run autonomously:
- Override Agent_Base::get_scheduled_tasks() to declare tasks
- Each task has: id, name, callback, schedule, optional prompt
- If prompt is set: runs through LLM autonomously (Agent_Controller::run_autonomous_task)
- If no prompt: falls back to direct callback method
- Managed from Agentic > Deployment > Scheduled Tasks tab

== Event Listeners ==

Agents can react to WordPress hooks in real-time:
- Override Agent_Base::get_event_listeners() to declare listeners
- Each listener has: id, hook, name, callback, optional prompt, priority, accepted_args
- If prompt is set: queues async LLM task via wp_schedule_single_event (non-blocking)
- Example hooks: save_post, wp_login_failed, comment_post, user_register
- Managed from Agentic > Deployment > Event Listeners tab

== Premium Features (Personal/Agency License) ==

- WhatsApp channel — two-way messaging via Meta WhatsApp Cloud API
- Vector Store & RAG — train on PDFs, documents, site content for retrieval-augmented generation
- MCP Integration — each agent becomes an MCP server; STDIO and HTTP transports
- Image generation — Imagen 4 via prepaid credits
- Text-to-Speech — chat responses read aloud via prepaid credits
- Marketplace access — download and sell community agents
- White-label — remove "Powered by" branding
- Automatic updates — new versions appear on the Plugins page

== Vector Store & RAG ==

Train agents on custom data for smarter, context-aware responses:
- Supports: WordPress posts/pages, PDF files, TXT files, Markdown files
- Admin UI: Agentic > Train on Data (4 tabs: overview, sources, upload, credits)
- CLI commands: wp agent rag status|sources|train|upload|delete|credits|search
- Credit-based: each training operation consumes credits from the shared wallet
- API endpoint: rag.agentic-plugin.com

== WP-CLI Commands ==

All agents are accessible via command line:
- wp agent list — list all agents with status
- wp agent info <slug> — show capabilities, tools, provider, model, mode
- wp agent prompt <slug> "message" — send a prompt and get a response
- wp agent tools <slug> — list available tools for an agent
- wp agent run-task <slug> <task-id> — run a scheduled task manually
- wp agent rag status — vector store overview (credits, sources, vectors)
- wp agent rag sources — list trained sources
- wp agent rag train <post_id> — train on a WordPress post
- wp agent rag upload <file> — upload PDF/TXT/MD for training
- wp agent rag delete <source> — delete a training source
- wp agent rag credits — credit balance and transaction history
- wp agent rag search <query> — query the vector store
- wp agent mcp-connect <slug> — generate MCP client config JSON
- wp agent test-tools — functional tool testing
- wp agent role-test — test agent behavior under different user roles

== Creating Custom Agents ==

File structure (in wp-content/agents/{slug}/):
- agent.php — PHP class extending \Agentic\Agent_Base
- templates/system-prompt.txt — persona and instructions
- abilities.json — tool access declarations with risk levels
- abilities-signature — HMAC-SHA256 signature (auto-generated)
- README.md — documentation (optional)

Required methods: get_id(), get_name(), get_description(), get_system_prompt()
Optional methods: get_tool_names(), get_icon(), get_category(), get_welcome_message(), get_suggested_prompts(), get_required_capabilities(), get_scheduled_tasks(), get_event_listeners()

Categories: Content, Admin, E-commerce, Frontend, Developer, Marketing

Agent_Base provides: automatic WP-CLI access, audit logging, tool execution pipeline, provider/model override support, and MCP server capability.

== Permissions & Safety ==

- 6 granular permission scopes (all disabled by default)
- Agent Proposals: pending change confirmation with diff view for write operations
- 4 user-space tools with file backup: write_file, modify_option, manage_transients, modify_postmeta
- Backups stored in wp-content/agentic-backups/ before user-space writes
- Full audit log of every agent action (Agentic > Audit Log)
- Per-agent risk overrides allow administrators to adjust tool risk levels

== Security Features ==

- Cloudflare Turnstile protection for anonymous chat
- Rate limiting per IP and per user
- GDPR compliance: IP anonymization, configurable data retention, WP Privacy Tools integration
- Per-role daily query and token limits
- Anonymous chat can be enabled/disabled globally

== REST API ==

Namespace: agentic/v1
- POST /chat — main chat endpoint
- GET /sessions — list chat sessions
- GET /history/{session_id} — conversation history
- GET /status — agent status (public)
- GET /models?provider= — list available models (admin)
- POST /test-api — test API key (admin)
- GET /approvals — pending approvals (admin)
- POST /approvals/{id} — approve/reject (admin)
- POST /tts — text-to-speech synthesis

== Licensing ==

- Free tier: all bundled agents, unlimited chat, community support
- Personal license: premium features, 1 site, priority support
- Agency license: premium features, unlimited sites, white-label, priority support
- Bundled and user-created agents always run without license validation
- License key activates premium features and services (RAG, TTS, ImageGen, WhatsApp)
- Daily wp-cron revalidation, 72h cache TTL, fail-open design, 7-day grace period
