Download the PHP package ultimate-multisite/ai-agent without Composer

SD AI Agent for WordPress

  Upload the zip to WordPress like any other plugin

Documentation

SD AI Agent is your AI teammate for the WordPress site you already run. Ask one assistant to improve content, prepare products, review SEO and site information, and automate repeatable work — while keeping your existing theme, plugins, and AI provider. The technical foundation below lets compatible plugins add tools the assistant can use as your site grows.

How it works

WordPress 7.0 introduced two core APIs that make this possible:

• AI Client SDK — A unified interface for AI providers. Any connector plugin (OpenAI, Anthropic, Google, Ollama, etc.) registered through the Connectors API works automatically. Switch providers or models at any time.
• Abilities API — A standard way for plugins to register actions an AI can take. AI Agent discovers every registered ability on your site and makes it available to the AI. Install a WooCommerce extension that registers abilities and the agent can manage orders without any extra configuration.

This means the agent gets more capable as your site grows. Every plugin that registers abilities expands what the AI can do — no glue code, no per-plugin setup.

What the agent can do out of the box

AI Agent ships with 28 built-in ability classes covering:

Any plugin can register additional abilities through the WordPress Abilities API — the agent discovers and uses them automatically.

Bring Your Own Key

Most WordPress AI plugins route calls through a proprietary proxy that marks up API costs. AI Agent talks directly to your provider:

• Direct API calls — Your site connects straight to OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint. No middleman.
• Full model choice — GPT-4o, Claude Opus 4, Gemini, a local Ollama instance, or anything the WordPress AI Client connector supports. Switch models per session.
• Transparent pricing — You see exactly what you spend in your provider's dashboard. The plugin tracks token counts and estimated costs locally.
• Privacy — Conversations go directly to your chosen provider. Nothing routes through a third-party relay.

AI Provider Connectors

AI Agent works with any connector plugin registered through the WordPress Connectors API. Install the ones that match your setup:

Official WP.org connectors

Community connectors

All connectors are included in the WordPress Playground demo.

Managed Superdav AI service

The bundled Superdav AI connector uses a service-managed site token instead of a customer-provided provider key. New installs default to the production Superdav edge at https://api.sdaiagent.com/v1; plugin activation and the first provider-list request both try to register the site automatically so the chat can open without a manual Connect step.

Registration is keyed by the plugin's durable site installation ID. The Superdav edge must treat repeated /site/installations calls for that ID as an idempotent refresh of the same free plan and starter-credit wallet, not a new free-credit grant.

For local Superdav AI Service testing, override the OpenAI-compatible /v1 base URL in wp-config.php:

Model listing and chat use GET /v1/models and POST /v1/chat/completions with the stored site token as Authorization: Bearer <SITE_ACCESS_TOKEN>. Override SD_AI_AGENT_CLOUD_REGISTRATION_ENDPOINT or SD_AI_AGENT_CLOUD_REVOCATION_ENDPOINT only when those endpoints live outside the configured base URL.

Features

Agentic chat

• Autonomous tool-calling loop — the AI plans, executes tools, reads results, and iterates until the task is done
• Configurable max iterations (1-50) to control how many tool calls per request
• Tool confirmation — approve or reject destructive actions before they run, with "always allow" memory
• Full markdown rendering with syntax-highlighted code blocks
• Message actions: regenerate, edit and resend, delete

Three chat interfaces

• Full-page admin panel (Tools > AI Agent) — two-column layout with session sidebar, folder organization, search, and filtering
• Floating widget — draggable button on every admin page, expandable chat panel with multi-tab sessions
• Screen meta panel — collapsible panel in the WordPress screen meta area (alongside Screen Options and Help)

Custom agents

Build specialized agents with the Agent Builder:

• Custom system prompts, greeting messages, and avatar icons
• Per-agent provider and model overrides
• Per-agent temperature and max iteration settings
• Enable or disable agents; users can switch between them in chat

Session management

• Persistent conversation history in a dedicated database table
• Organize sessions into folders, pin favorites, archive old conversations
• Search across all sessions by title or content
• Export to JSON (reimportable) or Markdown (human-readable)
• Per-session token usage tracking with cost estimates

Memory

• Persistent knowledge base the AI retains across sessions
• Categories: site info, user preferences, technical notes, workflows, general
• Auto-memory mode — the AI proactively saves important facts it learns
• Full CRUD through the settings UI and through chat

Skills

• Reusable instruction guides the AI can load on demand
• Define complex workflows once ("how to optimize images", "content publishing checklist") and the agent follows them when relevant
• Enable or disable per skill

Knowledge base (RAG)

• Index WordPress posts, pages, and custom post types into searchable collections
• Upload PDF documents and external URLs
• Automatic chunking with configurable size and overlap
• Full-text search across indexed content
• Auto-index on post publish/update (optional)
• The AI searches knowledge automatically when relevant context is needed

Custom tools

Create tools the AI can use without writing plugin code:

• HTTP tools — Call any external API (weather, Zapier, Slack, etc.) with {{placeholder}} substitution in URLs, headers, and body
• ACTION tools — Fire any WordPress do_action() hook with arguments
• CLI tools — Run WP-CLI commands with argument schemas

5 example tools are seeded on first activation (Weather API, Zapier Webhook, Clear Object Cache, Maintenance Mode, Site Health Check).

Scheduled automations

Cron-based AI tasks that run unattended:

• Define a prompt, pick a schedule (hourly / twice daily / daily / weekly), and let the agent work
• 5 quick-start templates: Daily Site Health Report, Weekly Plugin Update Check, Content Moderation, Broken Link Check, Database Optimization
• Per-automation max iteration limits
• Run any automation manually with "Run Now"
• Execution logs with duration, token usage, status, and full response

Event-driven automations

React to WordPress hooks in real time:

• 20+ pre-registered triggers across WordPress core, WooCommerce, and form plugins
• WordPress: post status changed, user registered, login, comment posted, plugin activated, theme switched, media uploaded, and more
• WooCommerce: new order, order status changed, low stock, payment complete, refund created
• Prompt templates with {{placeholder}} substitution from hook arguments (e.g., {{post.title}}, {{user.email}}, {{order.total}})
• Conditional execution — only fire when conditions match (post type, status, role, etc.)
• Shared logging infrastructure with scheduled automations

Tool discovery

When your site has many registered abilities (20+), the agent uses meta-tools to discover what's available instead of loading every tool definition into the system prompt:

• list-tools — Browse tools by category with pagination
• execute-tool — Run a discovered tool by name
• Configurable threshold and mode (auto / always / never)
• Reduces token usage on sites with dozens of tools

Smart conversation trimming

Prevents context window overflow in long agentic loops:

• Counts tool-call/response cycles and trims at safe boundaries
• Never cuts mid-tool-cycle or drops the first turn
• Configurable max history turns (default: 20)
• Transparent trimming marker so the AI knows context was compressed

Suggestion chips

After each AI response, clickable follow-up suggestions appear:

• AI generates 2-4 contextual suggestions
• One click sends the suggestion as your next message
• Configurable count (0-5)

Access and branding

• Role-based permissions — control which WordPress roles can access the agent
• Custom branding — set a custom name, logo, and colors for the chat interface

Usage dashboard

• Per-session and aggregate token counts (prompt + completion)
• Cost estimates based on current model pricing
• Breakdown by model and time period

Provider trace

Debug mode that captures the raw HTTP traffic between WordPress and your AI provider. Useful for troubleshooting connection issues and inspecting the exact prompts and responses.

Context providers

The AI automatically receives relevant context about the current page:

• Current admin page URL and title
• Site information (name, URL, WordPress version)
• Extensible — plugins can register additional context providers

Requirements

• WordPress 7.0+
• PHP 8.2+
• An AI provider connector plugin (see AI Provider Connectors above)
• An API key from your chosen provider (or a Claude Max subscription, or a local Ollama instance)

Installation

1. Upload the sd-ai-agent folder to /wp-content/plugins/
2. Activate through the Plugins screen
3. Configure an AI provider in Settings > AI Credentials (WordPress core Connectors API)
4. Go to Tools > AI Agent Settings to select your default provider and model
5. Open Tools > AI Agent to start chatting

Configuration

All settings live under Tools > AI Agent Settings with these tabs:

Architecture

REST API pattern

The agent uses an async job + polling pattern to handle long-running inference:

1. POST /sd-ai-agent/v1/run — Starts a background job, returns job_id
2. GET /sd-ai-agent/v1/job/{id} — Poll until status: completed (or awaiting_confirmation for tool approval)
3. POST /sd-ai-agent/v1/job/{id}/confirm or /reject — Handle tool confirmations

This avoids HTTP timeout issues with multi-step agentic loops that can take 30+ seconds.

Customer-agent runtime PHP contract

Trusted plugins on the same WordPress install can use the versioned, server-side customer-agent runtime without calling /public-chat/*, creating browser tokens, or depending on SessionController job arrays. There is intentionally no new unauthenticated REST endpoint.

Register a constrained profile from the consuming plugin, then discover the contract before use. V1 accepts only server-owned system instructions, the sd-ai-agent/knowledge-search ability, and declared knowledge collections. Client tools, browser tools, mutations, attachments, and caller-supplied prompts are unavailable.

enqueue_turn() is idempotent for the integration key, external session ID, and external message ID. inspect_job() is non-consuming: complete, failed, and cancelled jobs remain readable for at least seven days. cancel_job() prevents a late result from becoming deliverable, although an in-flight provider request may already be physically running. close_conversation() cancels and purges the constrained runtime history; the consumer remains responsible for its own customer transcript and routing state.

Extending

Register custom abilities that the agent can use:

The agent discovers and uses any registered ability automatically.

Add context providers:

Development

WordPress Playground testing

Test the plugin instantly in your browser without any local setup:

• Latest release: Open in WordPress Playground (login: admin / password)

The canonical blueprint lives at .wordpress-org/blueprints/blueprint.json — this is the path WordPress.org uses when displaying the plugin in the plugin directory.

License

GPL-2.0-or-later