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
slugstringLa chiave del tipo di post (massimo 20 caratteri, nessuna maiuscola, nessuno spazio)
singular_labelstringNome singolare leggibile, ad es. Portfolio Item
plural_labelstringNome 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
slugstringLa 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
slugstringLa chiave della tassonomia (massimo 32 caratteri)
singular_labelstringNome singolare leggibile, ad es. Project Category
plural_labelstringNome plurale leggibile, ad es. Project Categories
post_typesarraySlug 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
slugstringLa 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
cssstringCSS 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
slugstringIdentificatore del pattern, ad es. gratis/hero-dark
titlestringNome del pattern leggibile mostrato nell’editor
contentstringMarkup 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
presetstringNome 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
pathstringPuntatore JSON al valore da impostare, ad es. /color/palette
valueanyIl 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
namestringNome 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_idintegerID 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_idintegerID del menu di destinazione
typestringTipo 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_idintegerID 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_namestringLa 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_namestringLa chiave dell'opzione
valueanyIl 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
slugstringSlug 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
descriptionstringDescrizione 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"]
}
}