Pular para o conteúdo principal

Referência de habilidades

Habilidades são as ações atômicas que Gratis AI Agent pode invocar na sua instalação WordPress. Cada habilidade é uma classe PHP registrada que expõe um esquema JSON — o agente lê esse esquema em tempo de execução para entender quais parâmetros são necessários e o que a habilidade retorna.

Esta página documenta todas as habilidades incluídas no Gratis AI Agent v1.9.0.


Tipos de post personalizados

Estas habilidades gerenciam tipos de post personalizados (CPTs) registrados por meio do agente. Os registros são persistidos na tabela de opções do WordPress para que sobrevivam à desativação e reativação do plug-in.

register_post_type

Registra um novo tipo de post personalizado.

Parâmetros

ParâmetroTipoObrigatórioDescrição
slugstringSimA chave do tipo de post (máx. 20 caracteres, sem maiúsculas, sem espaços)
singular_labelstringSimNome singular legível por humanos, ex.: Portfolio Item
plural_labelstringSimNome plural legível por humanos, ex.: Portfolio Items
publicbooleanNãoSe o tipo de post é acessível publicamente. Padrão true
supportsarrayNãoRecursos a oferecer suporte: title, editor, thumbnail, excerpt, comments, revisions, custom-fields. Padrão ["title","editor"]
has_archivebooleanNãoSe uma página de arquivo do tipo de post está habilitada. Padrão false
menu_iconstringNãoClasse Dashicons ou URL para o ícone do menu administrativo. Padrão "dashicons-admin-post"
rewrite_slugstringNãoSlug de URL para o tipo de post. O padrão é slug

Exemplo

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

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


list_post_types

Retorna todos os tipos de post personalizados registrados pelo agente.

Parâmetros — nenhum

Retorna

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

delete_post_type

Remove o registro de um tipo de post personalizado registrado anteriormente pelo agente. Posts existentes desse tipo permanecem no banco de dados, mas não ficam mais acessíveis por meio do tipo de post.

Parâmetros

ParâmetroTipoObrigatórioDescrição
slugstringSimA chave do tipo de post a remover

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


Taxonomias personalizadas

Estas habilidades gerenciam taxonomias personalizadas. Assim como CPTs, os registros de taxonomia são persistidos.

register_taxonomy

Registra uma nova taxonomia personalizada.

Parâmetros

ParâmetroTipoObrigatórioDescrição
slugstringSimA chave da taxonomia (máx. 32 caracteres)
singular_labelstringSimNome singular legível por humanos, ex.: Project Category
plural_labelstringSimNome plural legível por humanos, ex.: Project Categories
post_typesarraySimSlugs de tipos de post aos quais esta taxonomia deve ser anexada
hierarchicalbooleanNãotrue para estilo de categoria, false para estilo de tag. Padrão true
publicbooleanNãoSe os termos são acessíveis publicamente. Padrão true
rewrite_slugstringNãoSlug de URL para a taxonomia. O padrão é slug

Exemplo

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

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


list_taxonomies

Retorna todas as taxonomias personalizadas registradas pelo agente.

Parâmetros — nenhum

Retorna

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

delete_taxonomy

Remove o registro de uma taxonomia personalizada registrada anteriormente pelo agente.

Parâmetros

ParâmetroTipoObrigatórioDescrição
slugstringSimA chave da taxonomia a remover

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


Sistema de design

As habilidades do sistema de design modificam a apresentação visual do site WordPress — de CSS personalizado a padrões de bloco e o logotipo do site.

inject_custom_css

Acrescenta CSS ao <head> do site via wp_add_inline_style. O CSS é armazenado na opção gratis_ai_agent_custom_css e removido da fila de forma limpa quando a habilidade é redefinida.

Parâmetros

ParâmetroTipoObrigatórioDescrição
cssstringSimCSS válido a injetar
labelstringNãoRótulo legível por humanos para este bloco de CSS, usado em logs de depuração. Padrão "agent-injected"
replacebooleanNãoSe true, substitui todo o CSS injetado anteriormente. Padrão false (acrescenta)

Exemplo

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

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


add_block_pattern

Registra um padrão de bloco reutilizável na biblioteca de padrões do WordPress.

Parâmetros

ParâmetroTipoObrigatórioDescrição
slugstringSimIdentificador do padrão, ex.: gratis/hero-dark
titlestringSimNome do padrão legível por humanos mostrado no editor
contentstringSimMarcação de bloco serializada (HTML) para o padrão
categoriesarrayNãoSlugs de categorias de padrão, ex.: ["featured", "hero"]
descriptionstringNãoBreve descrição mostrada no seletor de padrões
keywordsarrayNãoPalavras-chave de busca

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


list_block_patterns

Lista todos os padrões de bloco registrados pelo agente.

Parâmetros — nenhum

Retorna

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

Define o logo do site WordPress como um ID de anexo fornecido ou uma URL de imagem remota. Quando uma URL é fornecida, a imagem é baixada e importada para a Biblioteca de Mídia.

Parâmetros

ParâmetroTipoObrigatórioDescrição
attachment_idintegerNãoID de um anexo existente da Biblioteca de Mídia
urlstringNãoURL de imagem remota a importar e definir como logo

Um de attachment_id ou url deve ser fornecido.

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


apply_theme_json_preset

Aplica uma predefinição nomeada de cor/tipografia ao theme.json do tema ativo (ou global-styles). As predefinições são pacotes selecionados mantidos pela equipe do Gratis AI Agent.

Parâmetros

ParâmetroTipoObrigatórioDescrição
presetstringSimNome da predefinição, por exemplo, minimal-dark, warm-editorial, corporate-blue
mergebooleanNãoSe true, mescla com os valores existentes em vez de substituir. Padrão false

Predefinições disponíveis

PredefiniçãoDescrição
minimal-darkFundo quase preto, texto branco, uma única cor de destaque
warm-editorialFundo branco quente, títulos com serifa, cores de destaque terrosas
corporate-bluePaleta azul-marinho e branca com tipografia profissional
vibrant-startupGradientes vivos, cantos arredondados, tipo moderno sem serifa
classic-blogCinzas neutros, altura de linha confortável, espaçamento de layout tradicional

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


Estilos globais

As habilidades de Estilos globais leem e gravam valores de theme.json por meio da WordPress Global Styles API, afetando todos os blocos e modelos em todo o site.

get_global_styles

Retorna a configuração atual de estilos globais.

Parâmetros

ParâmetroTipoObrigatórioDescrição
pathstringNãoPonteiro JSON para um valor específico, por exemplo, /color/palette ou /typography/fontSizes. Retorna o objeto inteiro se omitido.

Retorna o objeto completo de estilos globais ou o valor em path.


set_global_styles

Atualiza um ou mais valores na configuração de estilos globais.

Parâmetros

ParâmetroTipoObrigatórioDescrição
pathstringSimPonteiro JSON para o valor a definir, por exemplo, /color/palette
valueanySimO novo valor

Exemplo — adicionar uma cor à paleta

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

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


reset_global_styles

Redefine todas as alterações de estilos globais aplicadas pelo agente, restaurando os padrões do tema.

Parâmetros — nenhum

Retorna { "success": true }


As habilidades de Menu de navegação criam e gerenciam menus de navegação do WordPress e seus itens.

create_menu

Cria um novo menu de navegação do WordPress.

Parâmetros

ParâmetroTipoObrigatórioDescrição
namestringSimNome do menu, por exemplo, Primary Navigation
locationstringNãoLocalização do tema para atribuir este menu, por exemplo, primary

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


update_menu

Renomeia um menu ou o reatribui a uma localização do tema.

Parâmetros

ParâmetroTipoObrigatórioDescrição
menu_idintegerSimID do menu a atualizar
namestringNãoNovo nome do menu
locationstringNãoLocalização do tema a atribuir ou reatribuir

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


add_menu_item

Adiciona um item a um menu de navegação existente.

Parâmetros

ParâmetroTipoObrigatórioDescrição
menu_idintegerSimID do menu de destino
typestringSimTipo de item: custom, post_type ou taxonomy
titlestringNãoRótulo para o item de menu (obrigatório para o tipo custom)
urlstringNãoURL para itens custom
object_idintegerNãoID do post ou ID do termo para itens post_type/taxonomy
parent_idintegerNãoID do item de menu sob o qual aninhar este item
positionintegerNãoPosição baseada em zero no menu

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


remove_menu_item

Remove um item de um menu de navegação.

Parâmetros

ParâmetroTipoObrigatórioDescrição
item_idintegerSimID do item de menu a remover

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


list_menus

Lista todos os menus de navegação do WordPress, incluindo suas localizações de tema atribuídas.

Parâmetros — nenhum

Retorna

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

Gerenciamento de opções

As habilidades de opções leem e gravam opções do WordPress via get_option / update_option. Uma lista de bloqueio de segurança integrada impede a modificação acidental de configurações críticas.

get_option

Lê uma opção do WordPress.

Parâmetros

ParâmetroTipoObrigatórioDescrição
option_namestringSimA chave da opção, por exemplo, blogname

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

Retorna um erro se option_name estiver na lista de bloqueio de segurança.


set_option

Grava uma opção do WordPress.

Parâmetros

ParâmetroTipoObrigatórioDescrição
option_namestringSimA chave da opção
valueanySimO novo valor (serializado automaticamente para arrays/objetos)
autoloadstringNão"yes" ou "no". O padrão preserva a configuração de autoload existente

Retorna um erro se option_name estiver na lista de bloqueio de segurança.

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


delete_option

Exclui uma opção do WordPress.

Parâmetros

ParâmetroTipoObrigatórioDescrição
option_namestringSimA chave da opção a ser excluída

Retorna um erro se option_name estiver na lista de bloqueio de segurança.

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


list_options

Lista opções do WordPress que correspondem a um padrão.

Parâmetros

ParâmetroTipoObrigatórioDescrição
patternstringNãoPadrão SQL LIKE para filtrar nomes de opções, por exemplo, gratis_%. Retorna todas as opções se omitido (use com cautela em bancos de dados grandes).
limitintegerNãoNúmero máximo de resultados. Padrão 50, máximo 500

Retorna

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

Gerenciamento de conteúdo

Os recursos de Gerenciamento de conteúdo criam e editam publicações e páginas do WordPress. IDs de publicações são retornados para que etapas subsequentes em planos com múltiplos recursos possam referenciar o conteúdo criado.

create_post

Cria uma nova publicação, página ou entrada de tipo de publicação personalizada do WordPress.

Parâmetros

ParâmetroTipoObrigatórioDescrição
titlestringSimTítulo da publicação
contentstringNãoCorpo da publicação — aceita texto simples, HTML ou marcação de bloco serializada
statusstringNãodraft, publish, pending, private. Padrão draft
post_typestringNãoSlug do tipo de publicação, por exemplo, post, page ou qualquer CPT registrado. Padrão post
excerptstringNãoResumo curto exibido em arquivos e resultados de busca
categoriesarrayNãoArray de nomes ou IDs de categorias a atribuir
tagsarrayNãoArray de nomes ou IDs de tags a atribuir
authorintegerNãoID de usuário do WordPress a definir como autor da publicação. O padrão é o usuário atual
datestringNãoData de publicação em formato ISO 8601, por exemplo, 2026-05-01T09:00:00
page_templatestringNãoArquivo de template a atribuir a esta publicação ou página, por exemplo, page-full-width.php. Só faz sentido quando post_type é page ou um CPT que oferece suporte a templates de página.

Exemplo

{
"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"
}

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


update_post

Atualiza uma publicação ou página existente do WordPress.

Parâmetros

ParâmetroTipoObrigatórioDescrição
post_idintegerSimID da publicação a atualizar
titlestringNãoNovo título da publicação
contentstringNãoNovo corpo da publicação
statusstringNãoNovo status: draft, publish, pending, private
excerptstringNãoNovo resumo
categoriesarrayNãoSubstitui a lista completa de categorias por este array de nomes ou IDs
tagsarrayNãoSubstitui a lista completa de tags por este array de nomes ou IDs
page_templatestringNãoNovo arquivo de template a atribuir a esta publicação ou página, por exemplo, page-full-width.php. Passe uma string vazia para remover a atribuição de template e reverter para o padrão do tema.

Exemplo — alterar o template após a criação

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

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


batch_create_posts

Cria várias publicações em uma única chamada de recurso, reduzindo idas e vindas durante criações de sites ou importação de conteúdo em massa. As publicações são criadas em sequência; se uma falhar, as outras continuam e a falha é relatada no array de resultados.

Parâmetros

ParâmetroTipoObrigatórioDescrição
postsarraySimArray de objetos de publicação, cada um aceitando os mesmos parâmetros que create_post
stop_on_errorbooleanNãoSe true, interrompe o processamento após a primeira falha. Padrão false

Exemplo

{
"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"
}
]
}

Retorna

{
"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

Atribui uma imagem destacada (miniatura da publicação) a uma publicação ou página existente. Aceita um ID de anexo existente da Biblioteca de mídia ou uma URL de imagem remota; quando uma URL é fornecida, a imagem é baixada e importada automaticamente.

Parâmetros

ParâmetroTipoObrigatórioDescrição
post_idintegerSimID da publicação ou página a atualizar
attachment_idintegerNãoID de um anexo existente da Biblioteca de mídia
urlstringNãoURL de imagem remota para importar e definir como imagem destacada
alt_textstringNãoTexto alternativo a aplicar ao anexo se ele for importado de uma URL

Um de attachment_id ou url deve ser fornecido.

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


create_contact_form

Cria um formulário de contato usando o plugin de formulário ativo (Contact Form 7, WPForms, Fluent Forms ou Gravity Forms, dependendo de qual está instalado). Retorna um shortcode que pode ser incorporado em qualquer publicação ou página.

Parâmetros

ParâmetroTipoObrigatórioDescrição
titlestringSimNome do formulário mostrado no admin do plugin de formulário
fieldsarraySimLista ordenada de campos do formulário (veja o objeto Campo abaixo)
recipientstringNãoEndereço de email para receber envios. O padrão é o email do admin do WordPress
subjectstringNãoLinha de assunto do email. Suporta os placeholders [your-name] e [your-subject] ao usar Contact Form 7
confirmation_messagestringNãoMensagem exibida após um envio bem-sucedido. Padrão: "Thank you for your message. We'll be in touch soon."

Objeto Campo

ChaveTipoObrigatórioDescrição
namestringSimNome interno do campo / chave de máquina
labelstringSimRótulo legível por humanos mostrado no formulário
typestringSimtext, email, tel, textarea, select, checkbox, radio, file, date
requiredbooleanNãoSe o campo deve ser preenchido antes do envio. Padrão false
optionsarrayNãoOpções para campos select, checkbox e radio
placeholderstringNãoTexto de placeholder para entradas do tipo texto

Exemplo

{
"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]"
}

Retorna

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

Revisão Visual

Os recursos de Revisão Visual permitem que o agente capture screenshots de páginas ao vivo e as analise, possibilitando revisão de design autônoma, comparações de antes/depois e verificações de regressão visual sem exigir qualquer extensão de navegador.

capture_screenshot

Captura uma screenshot de uma página do WordPress em uma determinada URL usando um navegador headless no lado do servidor. A imagem é salva na Biblioteca de Mídia e uma URL de CDN é retornada.

Parâmetros

ParâmetroTipoObrigatórioDescrição
urlstringSimURL completa da página para capturar a screenshot, por exemplo, https://example.com/about/
widthintegerNãoLargura da viewport em pixels. Padrão 1280
heightintegerNãoAltura da viewport em pixels. Padrão 800
full_pagebooleanNãoCapturar a página rolável completa em vez de apenas a viewport. Padrão false
delay_msintegerNãoMilissegundos a aguardar após o carregamento da página antes de capturar, útil para conteúdo animado. Padrão 500
labelstringNãoRótulo legível por humanos armazenado com o anexo na Biblioteca de Mídia

Retorna

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

compare_screenshots

Recebe duas screenshots e retorna uma pontuação de diferença visual, além de uma imagem de diferença destacando as regiões alteradas. Útil para confirmar que uma alteração de design produziu o resultado esperado ou para detectar regressões indesejadas.

Parâmetros

ParâmetroTipoObrigatórioDescrição
before_urlstringSimURL da página a capturar como o estado "antes"
after_urlstringSimURL da página a capturar como o estado "depois". Pode ser a mesma URL se estiver comparando ao longo do tempo
widthintegerNãoLargura da viewport para ambas as capturas. Padrão 1280
thresholdfloatNãoLimite de diferença de pixels (0.0–1.0). Pixels dentro dessa tolerância são considerados inalterados. Padrão 0.1

Retorna

{
"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"
}

Um diff_score de 0.0 significa nenhuma alteração visível; 1.0 significa que todos os pixels mudaram.


review_page_design

Captura uma screenshot de uma página e a envia ao modelo de linguagem para análise visual. Retorna uma avaliação estruturada cobrindo layout, tipografia, uso de cores e preocupações de acessibilidade.

Parâmetros

ParâmetroTipoObrigatórioDescrição
urlstringSimURL completa da página a revisar
focusstringNãoLista separada por vírgulas de áreas de revisão a enfatizar: layout, typography, colour, accessibility, mobile. Padrão: todas as áreas
widthintegerNãoLargura da viewport. Padrão 1280

Retorna

{
"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"]
}
}

Recursos Instaláveis

O Registro de Recursos Instaláveis permite estender o agente com pacotes de recursos adicionais distribuídos como plugins do WordPress. Cada pacote registra um ou mais recursos usando a API de recursos padrão.

list_available_abilities

Retorna o catálogo de pacotes de recursos disponíveis para instalação a partir do registro.

Parâmetros

ParâmetroTipoObrigatórioDescrição
categorystringNãoFiltrar por categoria: ecommerce, seo, media, social, developer

Retorna

{
"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

Baixa e ativa um pacote de habilidades a partir do registro.

Parâmetros

ParâmetroTipoObrigatórioDescrição
slugstringSimSlug da extensão do pacote de habilidades

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


recommend_plugin

Consulta o registro de habilidades para encontrar a melhor extensão para um caso de uso descrito e, opcionalmente, instalá-la.

Parâmetros

ParâmetroTipoObrigatórioDescrição
descriptionstringSimDescrição em linguagem natural da funcionalidade desejada
installbooleanNãoSe true, instala a extensão recomendada imediatamente. O padrão é false

Exemplo

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

Retorna

{
"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"]
}
}