wp-ai-workshop-demo\/*<\/code> abilities.<\/p>\n\n\n\nThis is incredibly reassuring as a checkpoint. You haven’t written any internal functionality for these Abilities yet, but you already have three discoverable, schema-described endpoints.<\/p>\n\n\n\n
Step 4: Describe the image (your first AI call)<\/h2>\n\n\n\n
Now for the fun part. You will need to implement the functionality for all Ability execute callback functions, which is where you\u2019ll connect to and use the AI providers.<\/p>\n\n\n\n
Start with wp_ai_workshop_demo_describe_image<\/code>, which executes the wp-ai-workshop-demo\/describe-image<\/code> Ability. This happens in the includes\/vision.php<\/code>. File, and it\u2019s where you make your first call to the WordPress AI Client.<\/p>\n\n\n\n$image_url = $arguments['image_url'];\n\n\/\/ Vision-capable providers (e.g. Anthropic) require the image to be sent\n\/\/ inline (base64), not as a remote URL, so fetch it and build a data URI.\n\/\/ A data URI is also accepted by URL-friendly providers such as OpenAI,\n\/\/ which keeps this ability portable across providers.\n$data_uri = wp_ai_workshop_demo_image_url_to_data_uri( $image_url );\nif ( is_wp_error( $data_uri ) ) {\n\treturn $data_uri;\n}\n\n$prompt = 'Describe this image in detail for someone who cannot see it. ';\n$prompt .= 'Focus on the main subject, the setting, the mood, notable colours, ';\n$prompt .= 'and any details that would help someone write an engaging blog post about it.';\n\n$description = wp_ai_client_prompt()\n\t->with_text( $prompt )\n\t->with_file( $data_uri )\n\t->generate_text();\n\nif ( is_wp_error( $description ) ) {\n\treturn $description;\n}\n\nreturn array(\n\t'description' => trim( $description ),\n);<\/code><\/pre>\n\n\n\nLook at how readable that AI Client call is. wp_ai_client_prompt()<\/code> gives you a fluent builder: add your prompt text, attach a file, ask for text back. And because the AI Client is provider-agnostic, this exact code works whether the user configured OpenAI, Anthropic, or Google.<\/p>\n\n\n\nYou’ll also need to add the wp_ai_workshop_demo_image_url_to_data_uri()<\/code> helper function. This fetches the remote image with wp_remote_get()<\/code> and base64-encodes it into a data URI to send to the AI model.<\/p>\n\n\n\nInformation:<\/strong> Generally, developers like to put helper functions like this in a separate file in the plugin. For the purposes of this tutorial, you can just add any helper functions at the bottom of the relevant file.<\/p>\n\n\n\n\/**\n * Fetch a remote image and return it as a base64-encoded data URI.\n *\n * @param string $image_url The URL of the image to fetch.\n * @return string|WP_Error The data URI on success, or WP_Error on failure.\n *\/\nfunction wp_ai_workshop_demo_image_url_to_data_uri( $image_url ) {\n\t$response = wp_remote_get(\n\t\t$image_url,\n\t\tarray(\n\t\t\t'timeout' => 30,\n\t\t\t'user-agent' => 'WP-AI-Workshop-Demo\/1.0; ' . home_url( '\/' ),\n\t\t)\n\t);\n\tif ( is_wp_error( $response ) ) {\n\t\treturn $response;\n\t}\n\n\t$code = (int) wp_remote_retrieve_response_code( $response );\n\tif ( 200 !== $code ) {\n\t\treturn new WP_Error(\n\t\t\t'image_fetch_failed',\n\t\t\tsprintf( 'Could not fetch the image (HTTP %d).', $code )\n\t\t);\n\t}\n\n\t$body = wp_remote_retrieve_body( $response );\n\tif ( '' === $body ) {\n\t\treturn new WP_Error( 'image_fetch_empty', 'The fetched image was empty.' );\n\t}\n\n\t$mime = wp_remote_retrieve_header( $response, 'content-type' );\n\tif ( ! is_string( $mime ) || 0 !== strpos( $mime, 'image\/' ) ) {\n\t\t$filetype = wp_check_filetype( $image_url );\n\t\t$mime = ! empty( $filetype['type'] ) ? $filetype['type'] : 'image\/jpeg';\n\t}\n\n\treturn 'data:' . $mime . ';base64,' . base64_encode( $body );\n}<\/code><\/pre>\n\n\n\nThere are two things to note here:<\/p>\n\n\n\n
\nwp_ai_client_prompt()->generate_text()<\/code> returns<\/em> a WP_Error<\/code> on failure \u2014 it doesn’t throw an exception. The AI Client’s WordPress wrapper catches exceptions for you and hands back a WP_Error<\/code>. So always check for is_wp_error()<\/code>.<\/li>\n\n\n\n- Vision providers such as Anthropic want the image sent inline as base64<\/strong>, not as a remote URL. That’s why you fetch it and build a data URI. Sending a URL works on some providers and fails on others \u2014 the data URI makes it the most portable.<\/li>\n<\/ul>\n\n\n\n
Step 5: Generate the post copy<\/h2>\n\n\n\n
The next Ability execute callback to update, wp_ai_workshop_demo_generate_post_from_description<\/code>, is inside includes\/content.php<\/code>. This function makes a second AI call that turns the description into a post title and body. Notice how the prompt asks the AI to return a specific JSON object, making it easier to return the title and content.<\/p>\n\n\n\n$description = $arguments['description'];\n$guidance = ! empty( $arguments['prompt'] ) ? trim( $arguments['prompt'] ) : '';\n\n$prompt = 'Write an engaging WordPress blog post inspired by the following image description.';\nif ( '' !== $guidance ) {\n\t$prompt .= ' Tone, angle, or extra guidance: ' . $guidance . '.';\n}\n$prompt .= ' Image description: ' . $description;\n$prompt .= ' Respond with a single JSON object containing exactly two keys: ';\n$prompt .= '\"title\" (a short, compelling post title as plain text) and ';\n$prompt .= '\"content\" (the full post body using valid WordPress Block Editor markup). ';\n$prompt .= 'Do not wrap the response in markdown code fences.';\n\n$text = wp_ai_client_prompt( $prompt )->generate_text();\n\nif ( is_wp_error( $text ) ) {\n\treturn $text;\n}\n\n$data = wp_ai_workshop_demo_decode_json_response( $text );\n\nif ( ! is_array( $data ) || empty( $data['title'] ) || empty( $data['content'] ) ) {\n\treturn new WP_Error(\n\t\t'post_copy_parse_failed',\n\t\t'The AI response could not be parsed into a title and content.'\n\t);\n}\n\nreturn array(\n\t'title' => trim( $data['title'] ),\n\t'content' => trim( $data['content'] ),\n);<\/code><\/pre>\n\n\n\nYou’ll also add a wp_ai_workshop_demo_decode_json_response()<\/code> helper function that deliberately strips any markdown code fences the model might wrap around the JSON before decoding.<\/p>\n\n\n\n\/**\n * Decode a JSON object from an AI text response, tolerating markdown fences.\n *\n * @param string $text The raw text returned by the AI.\n * @return array|null Decoded associative array, or null if no JSON could be parsed.\n *\/\nfunction wp_ai_workshop_demo_decode_json_response( $text ) {\n\t$text = trim( $text );\n\n\t$text = preg_replace( '\/^\\s*```(?:[a-z0-9_-]+)?\\s*\/i', '', $text );\n\t$text = preg_replace( '\/\\s*```\\s*$\/i', '', $text );\n\t$text = trim( $text );\n\n\t$data = json_decode( $text, true );\n\tif ( is_array( $data ) ) {\n\t\treturn $data;\n\t}\n\n\tif ( preg_match( '\/\\{.*\\}\/s', $text, $matches ) ) {\n\t\t$data = json_decode( $matches[0], true );\n\t\tif ( is_array( $data ) ) {\n\t\t\treturn $data;\n\t\t}\n\t}\n\n\treturn null;\n}<\/code><\/pre>\n\n\n\nYou might wonder why you\u2019re adding this when the prompt explicitly says not to. Here’s the thing about asking a language model for clean JSON: it’ll mostly comply, until it doesn\u2019t. AI models are not deterministic, meaning they don\u2019t follow a fixed set of rules. Rather, they recognize patterns and calculate the mathematical likelihood of the next output. Because of this, asking an AI the exact same question can produce different responses each time. So, adding a defensive check here and parsing the AI’s data ensures you get the correct response type every time.<\/p>\n\n\n\n
Step 6: Compose the abilities (the good bit)<\/h2>\n\n\n\n
Now for the really interesting part. Inside the includes\/post.php<\/code> file is the wp_ai_workshop_demo_create_post_from_photo<\/code>, which is the core of the plugin functionality. Here, this orchestrator function can call the other two abilities.<\/p>\n\n\n\n$image_url = $arguments['image_url'];\n$prompt = isset( $arguments['prompt'] ) ? $arguments['prompt'] : '';\n\n\/\/ Step 1: Describe the image (ability composition).\n$describe_ability = wp_get_ability( 'wp-ai-workshop-demo\/describe-image' );\nif ( ! $describe_ability instanceof WP_Ability ) {\n\treturn array( 'message' => 'Post creation failed: the describe-image ability is not available.' );\n}\n$description_result = $describe_ability->execute( array( 'image_url' => $image_url ) );\nif ( is_wp_error( $description_result ) ) {\n\treturn array( 'message' => 'Post creation failed while describing the image: ' . $description_result->get_error_message() );\n}\n\n\/\/ Step 2: Generate the post title and content (ability composition).\n$generate_ability = wp_get_ability( 'wp-ai-workshop-demo\/generate-post-from-description' );\nif ( ! $generate_ability instanceof WP_Ability ) {\n\treturn array( 'message' => 'Post creation failed: the generate-post-from-description ability is not available.' );\n}\n$copy_result = $generate_ability->execute(\n\tarray(\n\t\t'description' => $description_result['description'],\n\t\t'prompt' => $prompt,\n\t)\n);\nif ( is_wp_error( $copy_result ) ) {\n\treturn array( 'message' => 'Post creation failed while writing the post: ' . $copy_result->get_error_message() );\n}\n\n\/\/ Step 3: Create the draft post and set the featured image.\nreturn wp_ai_workshop_demo_create_post(\n\t$copy_result['title'],\n\t$copy_result['content'],\n\t$image_url\n);<\/code><\/pre>\n\n\n\nDo you see what’s happening? wp_get_ability()<\/code> fetches an ability by name, and ->execute()<\/code> runs it. Your orchestrator never touches the AI Client directly; it just composes two abilities that already know how to do their jobs, then hands off to a wp_ai_workshop_demo_create_post()<\/code> helper that calls wp_insert_post()<\/code> to create the post and sideloads the featured image with media_sideload_image()<\/code>helper. Now would be a good time to add these helper functions.<\/p>\n\n\n\n\/**\n * Create a draft post and set its featured image from an image URL.\n *\n * @param string $title The Post title.\n * @param string $content The Post content.\n * @param string $image_url The external image url.\n *\/\nfunction wp_ai_workshop_demo_create_post( $title, $content, $image_url ) {\n\t$post_id = wp_insert_post(\n\t\tarray(\n\t\t\t'post_title' => sanitize_text_field( $title ),\n\t\t\t'post_content' => $content,\n\t\t\t'post_status' => 'draft',\n\t\t\t'post_type' => 'post',\n\t\t)\n\t);\n\n\tif ( is_wp_error( $post_id ) || 0 === $post_id ) {\n\t\treturn array( 'message' => 'Post creation failed.' );\n\t}\n\n\t$attachment_id = wp_ai_workshop_demo_set_featured_image_from_url( $post_id, $image_url );\n\tif ( is_wp_error( $attachment_id ) ) {\n\t\treturn array(\n\t\t\t'message' => 'Post created, but the featured image could not be added: ' . $attachment_id->get_error_message(),\n\t\t\t'post_id' => $post_id,\n\t\t);\n\t}\n\n\treturn array(\n\t\t'message' => 'Post created successfully with featured image.',\n\t\t'post_id' => $post_id,\n\t);\n}\n\n\/**\n * Sideload an image from a URL into the media library and set it as the\n * featured image for a post.\n *\n * @param string $post_id ID of the Post.\n * @param string $image_url URL of the external image.\n *\/\nfunction wp_ai_workshop_demo_set_featured_image_from_url( $post_id, $image_url ) {\n\t\/\/ Verify that the image_url is a valid url, just to be safe.\n\tif ( ! wp_http_validate_url( $image_url ) ) {\n\t\treturn new WP_Error( 'invalid_url', 'Image URL failed validation.' );\n\t}\n\n\t\/\/ The media_sideload_image() function is typically only used in the admin context\n\t\/\/ This ensures that it can be used outside the admin context, such as in a REST API request or MCP tool.\n\tif ( ! function_exists( 'media_sideload_image' ) ) {\n\t\trequire_once ABSPATH . 'wp-admin\/includes\/media.php';\n\t\trequire_once ABSPATH . 'wp-admin\/includes\/file.php';\n\t\trequire_once ABSPATH . 'wp-admin\/includes\/image.php';\n\t}\n\n\t$attachment_id = media_sideload_image( $image_url, $post_id, null, 'id' );\n\tif ( is_wp_error( $attachment_id ) ) {\n\t\treturn $attachment_id;\n\t}\n\n\tset_post_thumbnail( $post_id, $attachment_id );\n\n\treturn $attachment_id;\n}<\/code><\/pre>\n\n\n\nThis is one of the greatest things about Abilities. Once your functionality is expressed as abilities, you and other developers extending your functionality can build new<\/em> functionality by combining existing abilities \u2014 like LEGO bricks. It’s the same instinct that made hooks and filters so powerful, applied to a new generation of features.<\/p>\n\n\n\nStep 7: Update the Admin Interface<\/h2>\n\n\n\n
At this point, you\u2019ve completed most of the core plugin functionality. Now we just need to make it available to the site owner. As mentioned earlier, the plugin ships with a settings page, so we need to connect it to the Abilities we just registered.<\/p>\n\n\n\n
The first step is to enqueue the Abilities script module in includes\/admin.php<\/code>:<\/p>\n\n\n\nwp_enqueue_script_module( '@wordpress\/core-abilities' );<\/code><\/pre>\n\n\n\n@wordpress\/core-abilities<\/code> enqueues everything you need to find and execute the Abilities you registered in PHP in JavaScript.<\/p>\n\n\n\nNext, you need to update the plugin\u2019s own script enqueuing to load it as a script module, and add the dependency on @wordpress\/core-abilities<\/code>:<\/p>\n\n\n\nwp_enqueue_script_module(\n\t'wp-ai-workshop-demo-script',\n\tplugins_url( 'build\/index.js', __DIR__ ),\n\tarray( '@wordpress\/core-abilities' ),\n\t$asset_file['version'],\n);<\/code><\/pre>\n\n\n\nNow open the file src\/components\/settings-page.jsx<\/code>, where you\u2019ll update the settings page interface.<\/p>\n\n\n\nStep one is to import ready<\/code> promise from the @wordpress\/abilities<\/code> package. This is a recent update<\/a> that ensures the Abilities REST API endpoints are loaded before any modules attempt to interact with them. Next, import the getAbility<\/code> and executeAbility<\/code> functions from the @wordpress\/abilities<\/code> package. This allows you to get and execute your registered Abilities. At the same time, you can create a constant that holds the name of the create-post-from-photo<\/code> Ability.<\/p>\n\n\n\nconst { ready } = await import( \/* webpackIgnore: true *\/ '@wordpress\/core-abilities' );\nawait ready;\nconst { getAbility, executeAbility } = await import( \/* webpackIgnore: true *\/ '@wordpress\/abilities' );\n\nconst ABILITY = 'wp-ai-workshop-demo\/create-post-from-photo';<\/code><\/pre>\n\n\n\nHeads up:<\/strong> note the \/* webpackIgnore: true *\/<\/code> comment. It tells