WordPress AI Client

WordPress 7.0 added a provider-agnostic WP AI Client. Plugin code asks WordPress for a prompt builder, declares what it needs, and lets configured providers/models handle execution. WordPress 7.1 improves Ability schema interoperability, mixed function-call resolution, and cache isolation. Credentials are managed through Settings > Connectors and the Connectors API.

When to use this skill

Trigger when ANY of the following is true:

Code calls wp_ai_client_prompt(), wp_supports_ai(), using_model_preference(), generate_text(), generate_image(), as_json_response(), or using_abilities().
A plugin adds AI-assisted content generation, summarization, analysis, media generation, chat, or agent workflow features.
The task mentions WP AI Client, AI providers, model preferences, AI Connectors, WP_AI_Client_Prompt_Builder, or AI-generated output in WordPress.
Reviewing whether an AI feature degrades correctly when no provider is configured.

Availability

The WP AI Client is available in WordPress 7.0+. Guard code for older sites and feature-detect 7.1 helpers/hooks when supporting 7.0:

if ( ! function_exists( 'wp_ai_client_prompt' ) || ! wp_supports_ai() ) {
    return new WP_Error( 'ai_unavailable', __( 'AI is not available on this site.', 'myplugin' ) );
}

wp_supports_ai() returns false when WP_AI_SUPPORT is defined as false, and can be filtered through wp_supports_ai. Treat it as a runtime feature flag, not a version check.

Basic workflow

Gate the feature by capability, nonce/request intent, and wp_supports_ai().
Build a prompt with wp_ai_client_prompt().
Prefer model capabilities or using_model_preference() instead of hard-coding one provider.
Call is_supported_*() before showing UI or starting expensive work.
Call a generate_* method and handle WP_Error.
Escape or sanitize AI output according to where it is used.

Text generation

$builder = wp_ai_client_prompt( 'Write a short product summary for: ' . $product_name )
    ->using_system_instruction( 'Return concise, factual marketing copy.' )
    ->using_temperature( 0.3 )
    ->using_model_preference(
        'provider-a/model-id',
        'provider-b/model-id'
    );

if ( ! $builder->is_supported_for_text_generation() ) {
    return new WP_Error( 'ai_text_unsupported', __( 'No configured AI model can generate text.', 'myplugin' ) );
}

$text = $builder->generate_text();
if ( is_wp_error( $text ) ) {
    return $text;
}

return sanitize_textarea_field( $text );

using_model_preference() is a preference list, not a hard requirement. Use model IDs that exist in the installed provider registry; if none of the preferred models is available, core can fall back to another compatible configured model.

Full result metadata

Use generate_*_result() when you need provider/model metadata, token usage, or a REST-serializable result object:

$result = wp_ai_client_prompt( 'Summarize the current post.' )
    ->generate_text_result();

if ( is_wp_error( $result ) ) {
    return $result;
}

$model_metadata = $result->getModelMetadata();
$token_usage    = $result->getTokenUsage();

Available result methods include generate_text_result(), generate_image_result(), convert_text_to_speech_result(), generate_speech_result(), and generate_video_result().

Structured JSON

For machine-consumed output, request JSON and validate again after generation:

$schema = array(
    'type'       => 'object',
    'properties' => array(
        'title' => array( 'type' => 'string' ),
        'tags'  => array(
            'type'  => 'array',
            'items' => array( 'type' => 'string' ),
        ),
    ),
    'required'   => array( 'title', 'tags' ),
);

$data = wp_ai_client_prompt( 'Extract a title and tags from: ' . $content )
    ->as_json_response( $schema )
    ->generate_text();

if ( is_wp_error( $data ) ) {
    return $data;
}

$decoded = json_decode( $data, true );
if ( ! is_array( $decoded ) ) {
    return new WP_Error( 'ai_invalid_json', __( 'AI returned invalid JSON.', 'myplugin' ) );
}

The AI Client helps request structured output; plugin code still owns validation before saving data. When exporting a WordPress-authored schema yourself, use wp_prepare_json_schema_for_client() on WordPress 7.1+. It removes server-only keywords and normalizes WordPress's older per-property required convention for draft-04 consumers. This preparation does not expand what WordPress validates.

Media generation

generate_image() returns a WordPress\AiClient\Files\DTO\File object:

$image = wp_ai_client_prompt( 'A clean icon for a WordPress analytics plugin.' )
    ->generate_image();

if ( is_wp_error( $image ) ) {
    return $image;
}

$data_uri = $image->getDataUri();

Handle generated files deliberately: validate MIME/type, avoid silently inserting generated media into content, and require an explicit user action for writes.

Abilities as AI tools

WordPress 7.0 can pass selected Abilities API entries as function declarations:

$result = wp_ai_client_prompt( 'Check the site environment and summarize risk.' )
    ->using_abilities( 'core/get-site-info', 'core/get-environment-info' )
    ->generate_text_result();

Only allowlist abilities that the prompt needs. For model function-call resolution, use WP_AI_Client_Ability_Function_Resolver with the same explicit list:

$resolver = new WP_AI_Client_Ability_Function_Resolver(
    'myplugin/get-report-status',
    'myplugin/create-report'
);

The resolver converts ability names to function names with the wpab__ prefix. Do not expose all abilities to a model. The ability permission_callback still runs, but the resolver allowlist prevents arbitrary tool selection.

WordPress 7.1 prepares Ability input schemas before creating model function declarations. Its resolver also ignores non-Ability function calls in a mixed model message instead of trying to execute every function call as an Ability. This means a resolver response contains Ability responses only; another tool resolver must handle calls outside the Ability allowlist. Do not assume unknown calls were rejected merely because they are absent from that response.

Controls and hooks

wp_ai_client_default_request_timeout: filter default request timeout in seconds.
wp_ai_client_prevent_prompt: last-chance filter to block prompt execution. Generation methods return WP_Error( 'prompt_prevented', ... ).
AI client events dispatch to hooks such as wp_ai_client_before_generate_result and wp_ai_client_after_generate_result.
wp_ai_client_cache_group (WordPress 7.1+) changes the object-cache group used by the AI Client adapter.

Use these for policy, observability, and operational control. Do not use them to smuggle credentials into prompts. Keep wp_ai_client_cache_group deterministic for the entire request and deployment; changing it dynamically fragments caches and makes clear() target only the currently selected group.

Critical rules

Never hard-code provider API keys. Configure providers through Connectors, env vars, or constants.
Do not assume a provider or model exists. Use wp_supports_ai() and is_supported_*().
Handle WP_Error from every generation call.
Use using_model_preference() for preferences, not provider lock-in.
Require explicit user intent for write actions. Avoid AI generation on every page load, cron tick, or unauthenticated request.
Treat AI output as untrusted input. Validate before saving, escape before rendering.
Allowlist abilities when using AI tools.
Route mixed tool calls explicitly. The Ability resolver handles only its allowlisted Ability calls in WordPress 7.1.
Avoid sending secrets, private user data, or personal data unless the feature explicitly requires it and the user/admin has consented.

Common mistakes

// WRONG - assumes AI exists and writes raw model output.
$summary = wp_ai_client_prompt( $_POST['content'] )->generate_text();
update_post_meta( $post_id, '_summary', $summary );

// RIGHT - gate, unslash/sanitize input, check support, handle WP_Error, sanitize output.
$content = sanitize_textarea_field( wp_unslash( $_POST['content'] ?? '' ) );
$builder = wp_ai_client_prompt( $content );

if ( ! $builder->is_supported_for_text_generation() ) {
    return new WP_Error( 'ai_unsupported', __( 'No configured text model is available.', 'myplugin' ) );
}

$summary = $builder->generate_text();
if ( is_wp_error( $summary ) ) {
    return $summary;
}

update_post_meta( $post_id, '_summary', sanitize_textarea_field( $summary ) );

Cross-references

Run wp-connectors-api for provider credential setup and Settings > Connectors behavior.
Run wp-abilities-api when exposing plugin operations as AI-callable tools.
Run wp-security-audit when AI features read requests or write WordPress data.

What this skill does NOT cover

Building a provider plugin for the underlying PHP AI Client SDK.
Prompt-engineering strategy beyond WordPress integration contracts.
Legal/privacy policy design for AI processing.

References

AI Client dev note: https://make.wordpress.org/core/2026/03/24/introducing-the-ai-client-in-wordpress-7-0/
WordPress 7.0 Field Guide: https://make.wordpress.org/core/2026/05/14/wordpress-7-0-field-guide/
WordPress 7.1 Field Guide: https://make.wordpress.org/core/2026/08/05/wordpress-7-1-field-guide/
Core files: wp-includes/ai-client.php, wp-includes/ai-client/class-wp-ai-client-prompt-builder.php, wp-includes/ai-client/class-wp-ai-client-ability-function-resolver.php.

wp-ai-client

SKILL.mdwordpress/wp-ai-client/SKILL.md