Passa al contenuto principale

Riferimento delle abilità

Le abilità sono le azioni atomiche che Gratis AI Agent può invocare sulla tua installazione WordPress. Ogni abilità è una classe PHP registrata che espone uno schema JSON — l’agente legge questo schema in fase di esecuzione per capire quali parametri sono richiesti e cosa restituisce l’abilità.

Questa pagina documenta tutte le abilità incluse con Gratis AI Agent v1.9.0.


Tipi di post personalizzati​

Queste abilità gestiscono tipi di post personalizzati (CPT) registrati tramite l’agente. Le registrazioni vengono salvate nella tabella delle opzioni di WordPress, così sopravvivono alla disattivazione e riattivazione del plugin.

register_post_type​

Registra un nuovo tipo di post personalizzato.

Parametri

ParametroTipoObbligatorioDescrizione
slugstringSìLa chiave del tipo di post (massimo 20 caratteri, nessuna maiuscola, nessuno spazio)
singular_labelstringSìNome singolare leggibile, ad es. Portfolio Item
plural_labelstringSìNome plurale leggibile, ad es. Portfolio Items
publicbooleanNoSe il tipo di post è accessibile pubblicamente. Predefinito true
supportsarrayNoFunzionalità da supportare: title, editor, thumbnail, excerpt, comments, revisions, custom-fields. Predefinito ["title","editor"]
has_archivebooleanNoSe è abilitata una pagina di archivio per il tipo di post. Predefinito false
menu_iconstringNoClasse Dashicons o URL per l’icona del menu di amministrazione. Predefinito "dashicons-admin-post"
rewrite_slugstringNoSlug URL per il tipo di post. Predefinito su slug

Esempio

{
"slug": "portfolio",
"singular_label": "Portfolio Item",
"plural_label": "Portfolio Items",
"public": true,
"supports": ["title", "editor", "thumbnail"],
"has_archive": true,
"menu_icon": "dashicons-portfolio"
}

Restituisce { "success": true, "slug": "portfolio" }


list_post_types​

Restituisce tutti i tipi di post personalizzati registrati dall’agente.

Parametri — nessuno

Restituisce

{
"post_types": [
{
"slug": "portfolio",
"singular_label": "Portfolio Item",
"plural_label": "Portfolio Items",
"public": true
}
]
}

delete_post_type​

Annulla la registrazione di un tipo di post personalizzato precedentemente registrato dall’agente. I post esistenti di quel tipo rimangono nel database ma non sono più accessibili tramite il tipo di post.

Parametri

ParametroTipoObbligatorioDescrizione
slugstringSìLa chiave del tipo di post da rimuovere

Restituisce { "success": true, "slug": "portfolio" }


Tassonomie personalizzate​

Queste abilità gestiscono tassonomie personalizzate. Come i CPT, le registrazioni delle tassonomie vengono salvate.

register_taxonomy​

Registra una nuova tassonomia personalizzata.

Parametri

ParametroTipoObbligatorioDescrizione
slugstringSìLa chiave della tassonomia (massimo 32 caratteri)
singular_labelstringSìNome singolare leggibile, ad es. Project Category
plural_labelstringSìNome plurale leggibile, ad es. Project Categories
post_typesarraySìSlug dei tipi di post a cui questa tassonomia deve essere collegata
hierarchicalbooleanNotrue per stile categoria, false per stile tag. Predefinito true
publicbooleanNoSe i termini sono accessibili pubblicamente. Predefinito true
rewrite_slugstringNoSlug URL per la tassonomia. Predefinito su slug

Esempio

{
"slug": "project-category",
"singular_label": "Project Category",
"plural_label": "Project Categories",
"post_types": ["portfolio"],
"hierarchical": true
}

Restituisce { "success": true, "slug": "project-category" }


list_taxonomies​

Restituisce tutte le tassonomie personalizzate registrate dall’agente.

Parametri — nessuno

Restituisce

{
"taxonomies": [
{
"slug": "project-category",
"singular_label": "Project Category",
"post_types": ["portfolio"],
"hierarchical": true
}
]
}

delete_taxonomy​

Annulla la registrazione di una tassonomia personalizzata precedentemente registrata dall’agente.

Parametri

ParametroTipoObbligatorioDescrizione
slugstringSìLa chiave della tassonomia da rimuovere

Restituisce { "success": true, "slug": "project-category" }


Sistema di design​

Le abilità del sistema di design modificano la presentazione visiva del sito WordPress — dal CSS personalizzato ai pattern di blocchi e al logo del sito.

inject_custom_css​

Aggiunge CSS al <head> del sito tramite wp_add_inline_style. Il CSS viene memorizzato nell’opzione gratis_ai_agent_custom_css e rimosso dalla coda in modo pulito quando l’abilità viene reimpostata.

Parametri

ParametroTipoObbligatorioDescrizione
cssstringSìCSS valido da iniettare
labelstringNoEtichetta leggibile per questo blocco CSS, usata nei log di debug. Predefinito "agent-injected"
replacebooleanNoSe true, sostituisce tutto il CSS precedentemente iniettato. Predefinito false (aggiunge)

Esempio

{
"css": ":root { --primary: #1a1a2e; --accent: #e94560; } body { font-family: 'Inter', sans-serif; }",
"label": "brand-colours",
"replace": false
}

Restituisce { "success": true, "bytes": 96 }


add_block_pattern​

Registra un pattern di blocchi riutilizzabile nella libreria dei pattern di WordPress.

Parametri

ParametroTipoObbligatorioDescrizione
slugstringSìIdentificatore del pattern, ad es. gratis/hero-dark
titlestringSìNome del pattern leggibile mostrato nell’editor
contentstringSìMarkup di blocchi serializzato (HTML) per il pattern
categoriesarrayNoSlug delle categorie di pattern, ad es. ["featured", "hero"]
descriptionstringNoBreve descrizione mostrata nel selettore di pattern
keywordsarrayNoParole chiave di ricerca

Restituisce { "success": true, "slug": "gratis/hero-dark" }


list_block_patterns​

Elenca tutti i pattern di blocchi registrati dall’agente.

Parametri — nessuno

Restituisce

{
"patterns": [
{
"slug": "gratis/hero-dark",
"title": "Dark Hero",
"categories": ["hero"]
}
]
}

Imposta il logo del sito WordPress su un dato ID allegato o su un URL di immagine remoto. Quando viene fornito un URL, l'immagine viene scaricata e importata nella Media Library.

Parametri

ParametroTipoObbligatorioDescrizione
attachment_idintegerNoID di un allegato esistente della Media Library
urlstringNoURL di immagine remoto da importare e impostare come logo

È necessario fornire uno tra attachment_id o url.

Restituisce { "success": true, "attachment_id": 42 }


apply_theme_json_preset​

Applica un preset denominato di colore/tipografia al theme.json (o global-styles) del theme attivo. I preset sono pacchetti curati mantenuti dal team di Gratis AI Agent.

Parametri

ParametroTipoObbligatorioDescrizione
presetstringSìNome del preset, ad es. minimal-dark, warm-editorial, corporate-blue
mergebooleanNoSe true, unisce ai valori esistenti invece di sostituirli. Predefinito false

Preset disponibili

PresetDescrizione
minimal-darkSfondo quasi nero, testo bianco, un unico colore di accento
warm-editorialSfondo caldo bianco sporco, titoli serif, colori di accento terrosi
corporate-bluePalette blu navy e bianca con tipografia professionale
vibrant-startupGradienti vivaci, angoli arrotondati, carattere sans-serif moderno
classic-blogGrigi neutri, altezza di riga confortevole, spaziatura del layout tradizionale

Restituisce { "success": true, "preset": "minimal-dark" }


Stili globali​

Le capacità degli Stili globali leggono e scrivono valori di theme.json tramite la WordPress Global Styles API, influenzando tutti i blocchi e i template nell'intero sito.

get_global_styles​

Restituisce la configurazione corrente degli stili globali.

Parametri

ParametroTipoObbligatorioDescrizione
pathstringNoPuntatore JSON a un valore specifico, ad es. /color/palette o /typography/fontSizes. Restituisce l'intero oggetto se omesso.

Restituisce l'oggetto completo degli stili globali o il valore in path.


set_global_styles​

Aggiorna uno o più valori nella configurazione degli stili globali.

Parametri

ParametroTipoObbligatorioDescrizione
pathstringSìPuntatore JSON al valore da impostare, ad es. /color/palette
valueanySìIl nuovo valore

Esempio — aggiungere un colore alla palette

{
"path": "/color/palette",
"value": [
{ "slug": "primary", "color": "#1a1a2e", "name": "Primary" },
{ "slug": "accent", "color": "#e94560", "name": "Accent" }
]
}

Restituisce { "success": true, "path": "/color/palette" }


reset_global_styles​

Reimposta tutte le modifiche agli stili globali applicate dall'agent, ripristinando i valori predefiniti del theme.

Parametri — nessuno

Restituisce { "success": true }


Le capacità dei menu di navigazione creano e gestiscono i menu di navigazione WordPress e i relativi elementi.

create_menu​

Crea un nuovo menu di navigazione WordPress.

Parametri

ParametroTipoObbligatorioDescrizione
namestringSìNome del menu, ad es. Primary Navigation
locationstringNoPosizione del theme a cui assegnare questo menu, ad es. primary

Restituisce { "success": true, "menu_id": 7 }


update_menu​

Rinomina un menu o lo riassegna a una posizione del theme.

Parametri

ParametroTipoObbligatorioDescrizione
menu_idintegerSìID del menu da aggiornare
namestringNoNuovo nome del menu
locationstringNoPosizione del theme da assegnare o riassegnare

Restituisce { "success": true, "menu_id": 7 }


add_menu_item​

Aggiunge un elemento a un menu di navigazione esistente.

Parametri

ParametroTipoObbligatorioDescrizione
menu_idintegerSìID del menu di destinazione
typestringSìTipo di elemento: custom, post_type o taxonomy
titlestringNoEtichetta per l'elemento del menu (richiesta per il tipo custom)
urlstringNoURL per gli elementi custom
object_idintegerNoID del post o ID del termine per elementi post_type/taxonomy
parent_idintegerNoID dell'elemento del menu sotto cui annidare questo elemento
positionintegerNoPosizione a base zero nel menu

Restituisce { "success": true, "item_id": 12 }


remove_menu_item​

Rimuove un elemento da un menu di navigazione.

Parametri

ParametroTipoObbligatorioDescrizione
item_idintegerSìID dell'elemento del menu da rimuovere

Restituisce { "success": true, "item_id": 12 }


list_menus​

Elenca tutti i menu di navigazione WordPress, incluse le posizioni del theme assegnate.

Parametri — nessuno

Restituisce

{
"menus": [
{
"menu_id": 7,
"name": "Primary Navigation",
"location": "primary",
"item_count": 5
}
]
}

Gestione delle opzioni​

Le capacità delle opzioni leggono e scrivono le opzioni WordPress tramite get_option / update_option. Una blocklist di sicurezza integrata impedisce la modifica accidentale di impostazioni critiche.

get_option​

Legge un'opzione WordPress.

Parametri

ParametroTipoObbligatorioDescrizione
option_namestringSìLa chiave dell'opzione, ad es. blogname

Restituisce { "option_name": "blogname", "value": "My Site" }

Restituisce un errore se option_name è nella blocklist di sicurezza.


set_option​

Scrive un'opzione WordPress.

Parametri

ParametroTipoObbligatorioDescrizione
option_namestringSìLa chiave dell'opzione
valueanySìIl nuovo valore (serializzato automaticamente per array/oggetti)
autoloadstringNo"yes" o "no". Il valore predefinito conserva l'impostazione autoload esistente

Restituisce un errore se option_name è nella blocklist di sicurezza.

Restituisce { "success": true, "option_name": "blogname" }


delete_option​

Elimina un’opzione WordPress.

Parametri

ParameterTypeRequiredDescription
option_namestringYesLa chiave dell’opzione da eliminare

Restituisce un errore se option_name è nella blocklist di sicurezza.

Restituisce { "success": true, "option_name": "my_custom_option" }


list_options​

Elenca le opzioni WordPress che corrispondono a un pattern.

Parametri

ParameterTypeRequiredDescription
patternstringNoPattern SQL LIKE per filtrare i nomi delle opzioni, ad es. gratis_%. Restituisce tutte le opzioni se omesso (da usare con cautela su database di grandi dimensioni).
limitintegerNoNumero massimo di risultati. Predefinito 50, massimo 500

Restituisce

{
"options": [
{ "option_name": "gratis_ai_agent_version", "autoload": "yes" }
],
"total": 1
}

Gestione dei contenuti​

Le capacità di Gestione dei contenuti creano e modificano post e pagine WordPress. Gli ID dei post vengono restituiti in modo che i passaggi successivi nei piani multi-capacità possano fare riferimento al contenuto creato.

create_post​

Crea un nuovo post WordPress, una pagina o una voce di tipo di post personalizzato.

Parametri

ParameterTypeRequiredDescription
titlestringYesTitolo del post
contentstringNoCorpo del post — accetta testo semplice, HTML o markup a blocchi serializzato
statusstringNodraft, publish, pending, private. Predefinito draft
post_typestringNoSlug del tipo di post, ad es. post, page o qualsiasi CPT registrato. Predefinito post
excerptstringNoBreve riepilogo mostrato negli archivi e nei risultati di ricerca
categoriesarrayNoArray di nomi o ID di categorie da assegnare
tagsarrayNoArray di nomi o ID di tag da assegnare
authorintegerNoID utente WordPress da impostare come autore del post. Il valore predefinito è l’utente corrente
datestringNoData di pubblicazione in formato ISO 8601, ad es. 2026-05-01T09:00:00
page_templatestringNoFile template da assegnare a questo post o a questa pagina, ad es. page-full-width.php. Ha significato solo quando post_type è page o un CPT che supporta i template di pagina.

Esempio

{
"title": "Welcome to Our New Site",
"content": "<!-- wp:paragraph --><p>Hello world!</p><!-- /wp:paragraph -->",
"status": "publish",
"post_type": "page",
"page_template": "page-full-width.php"
}

Restituisce { "success": true, "post_id": 42, "permalink": "https://example.com/welcome/" }


update_post​

Aggiorna un post o una pagina WordPress esistente.

Parametri

ParameterTypeRequiredDescription
post_idintegerYesID del post da aggiornare
titlestringNoNuovo titolo del post
contentstringNoNuovo corpo del post
statusstringNoNuovo stato: draft, publish, pending, private
excerptstringNoNuovo estratto
categoriesarrayNoSostituisci l’elenco completo delle categorie con questo array di nomi o ID
tagsarrayNoSostituisci l’elenco completo dei tag con questo array di nomi o ID
page_templatestringNoNuovo file template da assegnare a questo post o a questa pagina, ad es. page-full-width.php. Passa una stringa vuota per rimuovere l’assegnazione del template e tornare al valore predefinito del theme.

Esempio — cambia template dopo la creazione

{
"post_id": 42,
"page_template": "page-full-width.php"
}

Restituisce { "success": true, "post_id": 42 }


batch_create_posts​

Crea più post in una singola chiamata di capacità, riducendo i round-trip durante la creazione del sito o l’importazione massiva di contenuti. I post vengono creati in sequenza; se uno fallisce, gli altri continuano e l’errore viene riportato nell’array dei risultati.

Parametri

ParameterTypeRequiredDescription
postsarrayYesArray di oggetti post, ognuno dei quali accetta gli stessi parametri di create_post
stop_on_errorbooleanNoSe true, interrompe l’elaborazione dopo il primo errore. Predefinito false

Esempio

{
"posts": [
{
"title": "About Us",
"post_type": "page",
"status": "publish",
"page_template": "page-full-width.php"
},
{
"title": "Services",
"post_type": "page",
"status": "publish"
},
{
"title": "Contact",
"post_type": "page",
"status": "publish"
}
]
}

Restituisce

{
"created": 3,
"failed": 0,
"results": [
{ "success": true, "post_id": 42, "title": "About Us" },
{ "success": true, "post_id": 43, "title": "Services" },
{ "success": true, "post_id": 44, "title": "Contact" }
]
}

set_featured_image​

Assegna un’immagine in evidenza (miniatura del post) a un post o a una pagina esistente. Accetta l’ID di un allegato esistente della Media Library o l’URL di un’immagine remota; quando viene fornito un URL, l’immagine viene scaricata e importata automaticamente.

Parametri

ParameterTypeRequiredDescription
post_idintegerYesID del post o della pagina da aggiornare
attachment_idintegerNoID di un allegato esistente della Media Library
urlstringNoURL dell’immagine remota da importare e impostare come immagine in evidenza
alt_textstringNoTesto alt da applicare all’allegato se viene importato da un URL

Deve essere fornito uno tra attachment_id o url.

Restituisce { "success": true, "post_id": 42, "attachment_id": 17 }


create_contact_form​

Crea un modulo di contatto utilizzando il plugin per moduli attivo (Contact Form 7, WPForms, Fluent Forms o Gravity Forms, a seconda di quale è installato). Restituisce uno shortcode che può essere incorporato in qualsiasi post o pagina.

Parametri

ParameterTypeRequiredDescription
titlestringYesNome del modulo mostrato nell'admin del plugin del modulo
fieldsarrayYesElenco ordinato dei campi del modulo (vedi oggetto Campo sotto)
recipientstringNoIndirizzo email per ricevere gli invii. Predefinito: email dell'admin WordPress
subjectstringNoRiga dell'oggetto dell'email. Supporta i placeholder [your-name] e [your-subject] quando si usa Contact Form 7
confirmation_messagestringNoMessaggio visualizzato dopo un invio riuscito. Predefinito: "Thank you for your message. We'll be in touch soon."

Oggetto Campo

KeyTypeRequiredDescription
namestringYesNome interno del campo / chiave macchina
labelstringYesEtichetta leggibile mostrata sul modulo
typestringYestext, email, tel, textarea, select, checkbox, radio, file, date
requiredbooleanNoSe il campo deve essere compilato prima dell'invio. Predefinito false
optionsarrayNoOpzioni per i campi select, checkbox e radio
placeholderstringNoTesto segnaposto per input di tipo testo

Esempio

{
"title": "Restaurant Booking Enquiry",
"fields": [
{ "name": "your-name", "label": "Name", "type": "text", "required": true },
{ "name": "your-email", "label": "Email", "type": "email", "required": true },
{ "name": "party-size", "label": "Party size", "type": "select", "options": ["1–2", "3–5", "6–10", "10+"] },
{ "name": "your-message", "label": "Special requests", "type": "textarea", "required": false }
],
"recipient": "[email protected]",
"subject": "New booking enquiry from [your-name]"
}

Restituisce

{
"success": true,
"form_id": 3,
"shortcode": "[contact-form-7 id=\"3\" title=\"Restaurant Booking Enquiry\"]"
}

Revisione visiva​

Le capacità di Revisione visiva consentono all'agente di acquisire screenshot di pagine live e analizzarli, abilitando la revisione autonoma del design, confronti prima/dopo e controlli di regressione visiva senza richiedere alcuna estensione del browser.

capture_screenshot​

Acquisisce uno screenshot di una pagina WordPress a un determinato URL usando un browser headless lato server. L'immagine viene salvata nella Libreria Media e viene restituito un URL CDN.

Parametri

ParameterTypeRequiredDescription
urlstringYesURL completo della pagina di cui acquisire lo screenshot, ad es. https://example.com/about/
widthintegerNoLarghezza del viewport in pixel. Predefinito 1280
heightintegerNoAltezza del viewport in pixel. Predefinito 800
full_pagebooleanNoAcquisisci l'intera pagina scorrevole invece del solo viewport. Predefinito false
delay_msintegerNoMillisecondi da attendere dopo il caricamento della pagina prima dell'acquisizione, utile per contenuti animati. Predefinito 500
labelstringNoEtichetta leggibile memorizzata con l'allegato nella Libreria Media

Restituisce

{
"success": true,
"attachment_id": 88,
"url": "https://example.com/wp-content/uploads/2026/04/screenshot-about.png",
"width": 1280,
"height": 800
}

compare_screenshots​

Prende due screenshot e restituisce un punteggio di differenza visiva più un'immagine di differenza che evidenzia le regioni modificate. Utile per confermare che una modifica di design abbia prodotto il risultato previsto o per rilevare regressioni non intenzionali.

Parametri

ParameterTypeRequiredDescription
before_urlstringYesURL della pagina da acquisire come stato "prima"
after_urlstringYesURL della pagina da acquisire come stato "dopo". Può essere lo stesso URL se si confronta nel tempo
widthintegerNoLarghezza del viewport per entrambe le acquisizioni. Predefinito 1280
thresholdfloatNoSoglia di differenza tra pixel (0.0–1.0). I pixel entro questa tolleranza sono considerati invariati. Predefinito 0.1

Restituisce

{
"success": true,
"diff_score": 0.04,
"changed_pixels": 2340,
"total_pixels": 1024000,
"diff_attachment_id": 91,
"diff_url": "https://example.com/wp-content/uploads/2026/04/diff-about.png"
}

Un diff_score di 0.0 significa nessun cambiamento visibile; 1.0 significa che ogni pixel è cambiato.


review_page_design​

Acquisisce uno screenshot di una pagina e lo invia al modello linguistico per l'analisi visiva. Restituisce una valutazione strutturata che copre layout, tipografia, uso del colore e problemi di accessibilità.

Parametri

ParameterTypeRequiredDescription
urlstringYesURL completo della pagina da revisionare
focusstringNoElenco separato da virgole delle aree di revisione da enfatizzare: layout, typography, colour, accessibility, mobile. Predefinito: tutte le aree
widthintegerNoLarghezza del viewport. Predefinito 1280

Restituisce

{
"success": true,
"screenshot_url": "https://example.com/wp-content/uploads/2026/04/review-about.png",
"assessment": {
"overall": "The page structure is clean and readable. Two accessibility issues detected.",
"layout": "Good visual hierarchy. Hero section is prominent.",
"typography": "Body text is 15px — consider increasing to 16px for readability.",
"colour": "Contrast ratio on the CTA button (#fff on #4a90e2) is 3.1:1 — below the WCAG AA threshold of 4.5:1.",
"accessibility": ["Low contrast on CTA button", "Missing alt text on hero image"],
"suggestions": ["Darken the CTA button to #1a5cb0 to pass WCAG AA", "Add descriptive alt text to the hero image"]
}
}

Capacità installabili​

Il Registro delle capacità installabili ti consente di estendere l'agente con pacchetti di capacità aggiuntivi distribuiti come plugin WordPress. Ogni pacchetto registra una o più capacità usando l'API standard delle capacità.

list_available_abilities​

Restituisce il catalogo dei pacchetti di capacità disponibili per l'installazione dal registro.

Parametri

ParametroTipoObbligatorioDescrizione
categorystringNoFiltra per categoria: ecommerce, seo, media, social, developer

Restituisce

{
"packs": [
{
"slug": "gratis-ai-agent-woocommerce",
"name": "WooCommerce Abilities",
"category": "ecommerce",
"version": "1.0.0",
"abilities": ["create_product", "update_pricing", "manage_inventory"],
"installed": false
}
]
}

install_ability​

Scarica e attiva un pacchetto di abilità dal registro.

Parametri

ParametroTipoObbligatorioDescrizione
slugstringSìSlug del plugin del pacchetto di abilità

Restituisce { "success": true, "slug": "gratis-ai-agent-woocommerce", "abilities_added": 3 }


recommend_plugin​

Interroga il registro delle abilità per trovare il miglior plugin per un caso d'uso descritto e, facoltativamente, lo installa.

Parametri

ParametroTipoObbligatorioDescrizione
descriptionstringSìDescrizione in linguaggio naturale della funzionalità desiderata
installbooleanNoSe true, installa immediatamente il plugin consigliato. Predefinito false

Esempio

{
"description": "I need a contact form with file upload support and spam protection",
"install": false
}

Restituisce

{
"recommendation": {
"slug": "contact-form-7",
"name": "Contact Form 7",
"reason": "Widely adopted, supports file uploads, and integrates with Akismet for spam filtering.",
"alternatives": ["wpforms-lite", "fluent-forms"]
}
}