> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/docs/pt/programadores/tools.md).

# Ferramentas

A referência de ferramentas do servidor MCP do AirOps: dê ao Claude, Cursor e outros assistentes de IA acesso programático a análises AEO, Brand Kits, Grids, Bases de Conhecimento, Playbooks e Workflows no seu espaço de trabalho AirOps wo

O servidor MCP da AirOps dá a assistentes de IA como Claude e Cursor acesso programático e nativo de IA ao seu espaço de trabalho AirOps. Esta página lista as ferramentas que expõe para aceder e gerir os seus dados, ორგანიზadas em várias áreas: **AEO** (Otimização do Mecanismo de Resposta) para análises de visibilidade de IA, configuração de prompts e relatórios, **Gestão da Marca** para gerir a identidade da marca, o estilo de escrita e os ativos visuais, **Grids** para ler, escrever e criar dados do Grid programaticamente, **Bases de Conhecimento** para pesquisa semântica e ingestão de documentos, e **Playbooks e Workflows** para inspecionar definições, rever feedback e executar trabalho.

As ferramentas list e get suportam filtragem, seleção de campos, ordenação e paginação, quando aplicável. As ferramentas write documentam os seus campos obrigatórios em cada secção.

## Acesso ao plano

As ferramentas de recursos exigem um espaço de trabalho pago. As avaliações do nível pago continuam elegíveis. Espaços de trabalho gratuitos podem ligar-se, descobrir ferramentas e usar `list_workspaces`, mas os pedidos dos respetivos dados devolvem uma restrição de plano. Se pertencer a espaços de trabalho gratuitos e pagos, escolha um espaço de trabalho pago para consultas e alterações de recursos.

## Espaço de trabalho e Brand Kit

### `list_workspaces`

Liste todos os espaços de trabalho a que tem acesso.

**Devolve:** ID do espaço de trabalho, nome, slug e nível de subscrição.

| Parâmetro   | Valores           |
| ----------- | ----------------- |
| **Filtros** | name, tier        |
| **Ordenar** | name, created\_at |

***

### `list_brand_kits`

Liste todos os Brand Kits a que tem acesso. Devolve `brand_management_enabled` como no `aeo_enabled` sinalizadores para cada Brand Kit, para que saiba quais capacidades estão disponíveis.

* Use `get_brand_kit` para Brand Kits com `brand_management_enabled: true`
* Use `get_insights_settings` para Brand Kits com `aeo_enabled: true`

**Devolve:** ID do Brand Kit, nome, sobre, URL, nome do espaço de trabalho, `brand_management_enabled`, e `aeo_enabled`.

| Parâmetro   | Valores                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| **Filtros** | workspace\_name, brand\_name, brand\_url, brand\_management\_enabled, aeo\_enabled |
| **Ordenar** | brand\_name, created\_at                                                           |

***

### `get_brand_kit`

Obtenha um Brand Kit específico por ID para gestão da marca e criação de conteúdo. Devolve identidade da marca, estilo de escrita e entidades relacionadas.

**Requer:** `id`

**Devolve:** Nome da marca, URL, sobre, persona de escrita, tom de escrita, estado e marcas temporais. Opcionalmente inclui entidades relacionadas com dados aninhados.

| Parâmetro  | Valores                                                                                                                                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Inclui** | product\_lines, product\_lines.competitors, audiences, audiences.writing\_rules, content\_types, content\_types.content\_samples, content\_types.writing\_rules, regions, regions.writing\_rules, writing\_rules, custom\_variables |

***

### `get_insights_settings`

Obtenha a configuração de insights AEO para um Brand Kit. Devolve as informações necessárias para usar quaisquer ferramentas de AEO e análise.

**Requer:** `id`

**Devolve:** ID do Brand Kit, nome, URL, países, estado de AEO, contagem de prompts, descrição do cliente, concorrentes com URLs de domínio e personas.

***

### `update_brand_kit`

Atualize os campos base de um Brand Kit. Apenas os campos fornecidos são alterados.

**Requer:** `brand_kit_id`

**Campos atualizáveis:** `nome_da_marca`, `brand_url`, `brand_about`, `writing_persona`, `writing_tone`

***

### `list_topics`

Liste os tópicos configurados para um Brand Kit.

**Requer:** `brand_kit_id`

**Devolve:** ID do tópico, nome e cor.

| Parâmetro   | Valores           |
| ----------- | ----------------- |
| **Filtros** | nome              |
| **Ordenar** | name, created\_at |

***

### `create_topic`

Crie um novo tópico para um Brand Kit. Os tópicos agrupam prompts monitorizados e vistas de análise por tema.

**Requer:** `brand_kit_id`, `nome`

**Campos opcionais:** `cor`

***

### `update_topic`

Atualize o nome ou a cor de um tópico. As atribuições de prompts existentes permanecem associadas ao tópico.

**Requer:** `brand_kit_id`, `topic_id`

**Campos:** `nome`, `cor`

***

### `delete_topic`

Elimine um tópico de um Brand Kit.

**Requer:** `brand_kit_id`, `topic_id`

{% hint style="warning" %}
Eliminar um tópico pode afetar a organização de prompts e as vistas de relatórios. Confirme o tópico e o impacto a jusante antes de chamar esta ferramenta.
{% endhint %}

***

### `list_personas`

Liste as personas configuradas para um Brand Kit.

**Requer:** `brand_kit_id`

**Devolve:** ID da persona, título e descrição.

| Parâmetro   | Valores             |
| ----------- | ------------------- |
| **Filtros** | título              |
| **Ordenar** | título, created\_at |

***

### `publish_brand_kit`

Publique o rascunho atual de um Brand Kit para que as alterações se tornem ativas. Todas as alterações feitas via `update_brand_kit` como no `manage_brand_kit_*` são aplicadas a um rascunho. Publicar promove o rascunho para ativo e cria um novo rascunho a partir dele.

**Requer:** `brand_kit_id`

{% hint style="warning" %}
Confirme sempre com o utilizador antes de publicar. Isto torna todas as alterações pendentes ativas.
{% endhint %}

***

### `create_brand_kit_recap_entry`

Registe uma entrada de resumo que sintetize as alterações ao Brand Kit feitas durante uma sessão MCP. Use isto uma vez, perto do final de uma sessão que tenha alterado o Brand Kit, com evidências como URLs de origem, nomes de páginas ou citações curtas em `body_markdown`.

**Requer:** `brand_kit_id`, `título`

**Campos opcionais:** `body_markdown`

**Devolve:** ID da entrada de resumo, título, origem e mensagem de sucesso.

***

## Gestão do Brand Kit

Ferramentas para criar e atualizar entidades do Brand Kit. Cada ferramenta suporta criação (omita `id`) e atualização (forneça `id`) operações. Na atualização, apenas os campos fornecidos são alterados.

{% hint style="info" %}
As alterações são guardadas num **rascunho**. Utilize `publish_brand_kit` para as tornar ativas.
{% endhint %}

### `manage_brand_kit_product_line`

Crie ou atualize uma linha de produto para um Brand Kit.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `URL`, `details`, `positioning`, `ideal_customer_profile`

***

### `manage_brand_kit_competitor`

Crie ou atualize um concorrente para um Brand Kit. Os concorrentes têm de estar associados a, pelo menos, uma linha de produto.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `domain`, `product_line_ids` (pelo menos um obrigatório)

***

### `manage_brand_kit_audience`

Crie ou atualize uma audiência para um Brand Kit.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `descrição`

***

### `manage_brand_kit_region`

Crie ou atualize uma região para um Brand Kit.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `descrição`, `icon_name` (ícone de bandeira, por exemplo, `flag-us`)

***

### `manage_brand_kit_content_type`

Crie ou atualize um tipo de conteúdo para um Brand Kit. Na criação, pode fornecer um `sample_url` para semear o tipo de conteúdo. O sistema fará scraping do URL e usará IA para gerar campos automaticamente.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `template_outline`, `cta_text`, `cta_url`, `header_case` (title\_case, sentence\_case, custom), `header_case_custom_value`, `sample_url` (apenas criação)

***

### `manage_brand_kit_content_sample`

Crie ou atualize uma amostra de conteúdo para um Brand Kit. Na criação, o URL da amostra é processado de forma assíncrona para extrair conteúdo.

**Requer:** `brand_kit_id`

**Campos:** `URL` (obrigatório na criação), `content_type_id` (obrigatório na criação), `conteúdo` (apenas atualização), `audience_ids`, `region_ids`

***

### `manage_brand_kit_writing_rule`

Crie ou atualize uma regra de escrita para um Brand Kit. As regras podem ser globais ou limitadas a um único tipo de conteúdo, audiência ou região (mutuamente exclusivas). O âmbito é definido apenas na criação.

**Requer:** `brand_kit_id`

**Campos:** `texto` (obrigatório na criação), `content_type_id` (apenas criação), `audience_id` (apenas criação), `region_id` (apenas criação)

***

### `manage_brand_kit_custom_variable`

Crie ou atualize uma variável personalizada para um Brand Kit. As variáveis personalizadas são desaconselhadas para a maioria dos casos de uso. Prefira usar regiões, audiências, tipos de conteúdo ou regras de escrita.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `value` (obrigatório na criação)

***

### `create_brand_kit_direct_upload`

Inicie um carregamento direto para ativos visuais do Brand Kit, como logótipos, exemplos visuais e ficheiros de fontes. A ferramenta devolve um URL de carregamento pré-assinado, cabeçalhos de carregamento e um `signed_id` para passar à ferramenta de gestão do ativo visual relevante.

**Requer:** `brand_kit_id`, `filename`, `content_type`, `byte_size`, `checksum`

**Devolve:** `signed_id`, `upload_url`, e `upload_headers`.

***

### `manage_brand_kit_palette`

Crie ou atualize uma paleta de cores para um rascunho do Brand Kit.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação)

***

### `manage_brand_kit_palette_color`

Crie ou atualize uma cor dentro de uma paleta do Brand Kit.

**Requer:** `brand_kit_id`

**Campos:** `palette_id` (obrigatório na criação), `nome` (obrigatório na criação), `value` (obrigatório na criação), `usage_instructions`

***

### `manage_brand_kit_logo_variant`

Crie ou atualize uma variante de logótipo para um rascunho do Brand Kit. Anexe um ficheiro com `signed_id` de `create_brand_kit_direct_upload` ou com um `file_url`.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `background_color`, `usage_instructions`, `signed_id`, `file_url`

***

### `manage_brand_kit_logo_size`

Crie ou atualize dimensões recomendadas do logótipo e instruções de utilização.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `largura`, `altura`, `usage_instructions`

***

### `manage_brand_kit_font`

Crie ou atualize uma fonte do Brand Kit. Anexe um ficheiro de fonte com `signed_id` de `create_brand_kit_direct_upload` ou com um `file_url`.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `usage_instructions`, `google_font_link`, `signed_id`, `file_url`

***

### `manage_brand_kit_type_size`

Crie ou atualize um tamanho tipográfico associado a uma fonte do Brand Kit.

**Requer:** `brand_kit_id`

**Campos:** `font_id`, `nome` (obrigatório na criação), `peso`, `tamanho`, `altura da linha`, `usage_instructions`

***

### `manage_brand_kit_usage_rule`

Crie ou atualize uma regra de utilização do Brand Kit. `applies_to` é definido na criação e não pode ser alterado depois.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `applies_to` (obrigatório na criação)

***

### `manage_brand_kit_visual_use_case`

Crie ou atualize um caso de uso visual, um grupo nomeado de exemplos visuais com instruções partilhadas.

**Requer:** `brand_kit_id`

**Campos:** `nome` (obrigatório na criação), `instruções`

***

### `manage_brand_kit_visual_example`

Crie ou atualize um exemplo visual para um Brand Kit. Os exemplos visuais têm de ser agrupados sob um caso de uso visual. Anexe uma imagem com `signed_id` de `create_brand_kit_direct_upload` ou com um `file_url`.

**Requer:** `brand_kit_id`

**Campos:** `visual_use_case_id` (obrigatório na criação), `título` (obrigatório na criação), `sample_url`, `usage_instructions`, `signed_id`, `file_url`

***

### Edite um rascunho do Brand Kit <a href="#suggest_brand_kit_edits" id="suggest_brand_kit_edits"></a>

Use `update_brand_kit` para campos base e a ferramenta adequada `manage_brand_kit_*` para entidades relacionadas. Resuma as alterações pretendidas e obtenha a confirmação do utilizador antes de as aplicar.

Estas ferramentas escrevem diretamente no rascunho. Leia novamente o rascunho para verificar o resultado e diga ao utilizador que as alterações ainda não estão ativas. Peça confirmação explícita antes de chamar `publish_brand_kit`; publicar é uma ação separada que torna todas as alterações pendentes ativas.

O anterior `suggest_brand_kit_edits` a ferramenta de revisão interativa já não está disponível.

***

## Prompts & Respostas AEO

### `list_aeo_prompts`

Liste os prompts de IA monitorizados para um Brand Kit.

**Requer:** `brand_kit_id`

**Devolve:** ID do prompt, texto, palavra-chave, se a marca é mencionada, volume, ID do tópico, marcas temporais, mention\_rate, citation\_rate e tendências.

| Parâmetro           | Valores                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------ |
| **Filtros**         | text, strategy, brand\_mentioned, topic\_id, prompt\_volume, mention\_rate, citation\_rate |
| **Ordenar**         | text, created\_at, prompt\_volume, mention\_rate, citation\_rate                           |
| **Inclui**          | topic, tags                                                                                |
| **Filtros de data** | start\_date, end\_date, providers, countries, personas                                     |

***

### `create_aeo_prompt`

Crie um novo prompt AEO monitorizado para um Brand Kit. Tarefas em segundo plano analisam o prompt, extraem palavras-chave e calculam métricas de volume após a criação.

**Requer:** `brand_kit_id`, `texto`, `topic_id`

**Campos opcionais:** `countries`, `persona_ids`, `platforms`

{% hint style="warning" %}
Criar prompts pode afetar o volume de respostas. Confirme o texto do prompt, o tópico e as atribuições com o utilizador antes de chamar esta ferramenta.
{% endhint %}

***

### `get_prompt_answers`

Obtenha respostas de IA para um prompt específico.

**Requer:** `prompt_id`

**Devolve:** ID da resposta, texto (truncado), provider, country, brand\_mentioned, brand\_cited, marcas temporais e o `intent_stage` (`consciência`, `consideração`, `avaliação`, `compra`, ou `null`).

| Parâmetro   | Valores             |
| ----------- | ------------------- |
| **Filtros** | countries, personas |
| **Ordenar** | created\_at         |
| **Inclui**  | persona             |

***

### `get_answer`

Obtenha uma resposta de IA específica por ID com o conteúdo completo do texto.

**Requer:** `id`

**Devolve:** Texto completo da resposta (não truncado), provider, country, brand\_mentioned, brand\_cited, `intent_stage`e, opcionalmente, citações, menções e detalhes da persona.

| Parâmetro  | Valores                      |
| ---------- | ---------------------------- |
| **Inclui** | citations, mentions, persona |

Use isto depois de `get_prompt_answers` para obter o texto completo da resposta com URLs e posições das citações.

***

### `list_answers`

Liste respostas de IA em todo um Brand Kit com filtros por intervalo de datas, providers, countries, personas e outras dimensões AEO. Use isto quando precisar de respostas de vários prompts, em vez de respostas para um único prompt.

**Requer:** `brand_kit_id`

Cada resposta inclui o `intent_stage`, ou `null` quando a classificação não está disponível.

***

## Configuração de AEO e gestão de prompts

### `create_aeo_persona`

Crie uma nova persona AEO para um Brand Kit. As personas representam as perspetivas do utilizador usadas para simular consultas de pesquisa por IA.

**Requer:** `brand_kit_id`, `título`, `descrição`

**Campos opcionais:** `add_to_all_prompts`

***

### `add_aeo_region`

Adicione um código de país ISO alpha-2 às regiões AEO configuradas de um Brand Kit.

**Requer:** `brand_kit_id`, `country_code`

**Campos opcionais:** `add_to_all_prompts`

***

### `list_tags`

Liste as tags AEO configuradas para um Brand Kit.

**Requer:** `brand_kit_id`

| Parâmetro   | Valores           |
| ----------- | ----------------- |
| **Filtros** | nome              |
| **Ordenar** | name, created\_at |

***

### `create_aeo_tag`

Crie uma nova tag AEO num Brand Kit. As tags são etiquetas definidas pelo utilizador que podem ser aplicadas a prompts.

**Requer:** `brand_kit_id`, `nome`

**Campos opcionais:** `cor`

***

### `update_aeo_tag`

Atualize o nome ou a cor de uma tag AEO. As marcações de prompts existentes são preservadas.

**Requer:** `brand_kit_id`, `tag_id`

**Campos:** `nome`, `cor`

***

### `delete_aeo_tag`

Elimine uma tag AEO de um Brand Kit e remova-a de todos os prompts que a utilizam.

**Requer:** `brand_kit_id`, `tag_id`

{% hint style="warning" %}
Esta ação elimina permanentemente a tag e remove as suas marcações de prompts. Confirme a tag e o impacto antes de a chamar.
{% endhint %}

***

### `bulk_update_aeo_prompt_tags`

Adicione ou remova uma ou mais tags em lote numa transação única para vários prompts AEO.

**Requer:** `brand_kit_id`, `prompt_ids`, `operação`, `tag_ids`

**Operações:** `adicionar`, `remover`

***

### `update_aeo_prompt_assignments`

Prepare alterações de atribuição de rascunho para um ou mais prompts AEO. As atribuições incluem countries, personas e platforms. As alterações só se tornam ativas até `commit_aeo_prompt_assignments` executar.

**Requer:** `brand_kit_id`, `prompts`

**Campos do prompt:** `prompt_id`, `countries`, `persona_ids`, `platforms`

***

### `get_aeo_prompt_assignments_status`

Inspecione o estado atual do rascunho de atribuições de prompts para um Brand Kit. Use isto para verificar se existe um rascunho, se tem alterações e se a sua confirmação excederia o limite de respostas do espaço de trabalho.

**Requer:** `brand_kit_id`

***

### `commit_aeo_prompt_assignments`

Confirme o rascunho atual de atribuições de prompts para ativo. Isto substitui as atribuições ativas de countries, personas e platforms pelo estado do rascunho.

**Requer:** `brand_kit_id`

{% hint style="warning" %}
Isto afeta as atribuições ativas de monitorização AEO. Confirme com o utilizador antes de confirmar.
{% endhint %}

***

### `discard_aeo_prompt_assignments`

Descarte o rascunho atual de atribuições de prompts e crie um novo rascunho a partir das atribuições ativas.

**Requer:** `brand_kit_id`

{% hint style="warning" %}
Isto descarta todas as edições de atribuição pendentes no rascunho partilhado, incluindo edições de IU não guardadas. Peça confirmação ao utilizador antes de o chamar.
{% endhint %}

***

## Citações e domínios

Use `prompt_type` com operador `EQUALS` e valor `marca` ou `categoria` para filtrar com base em se o prompt nomeia a sua marca. Use `brand_mentioned` com operador `EQ` e valor `true` ou `false` para filtrar com base em se a página citada menciona a sua marca.

Os filtros mais antigos `brand_mentioned EQUALS brand/category` como no `brand_referenced EQ true/false` continuam aceites como aliases de compatibilidade. Prefira os nomes explícitos acima; eles têm precedência quando são fornecidos os filtros antigos e novos. O `brand_mentioned` filtro em `list_aeo_prompts` continua a referir-se ao texto do prompt.

### `list_aeo_citations`

Liste citações (URLs) com métricas para um Brand Kit. Mostra URLs individuais citadas em respostas de IA.

**Requer:** `brand_kit_id`

**Devolve:** URL, nome do domínio, categoria do domínio, contagem de citações, quota de citações, taxa de citações, pontuação de influência, tipo de página, sentimento da marca, tendências e metadados sociais quando disponíveis.

A `social` o objeto identifica a plataforma e contém `conteúdo` como no `conta` envelopes com metadados, métricas e estado de sincronização. É `null` quando não existe um registo social suportado. A conta pode ser `null` quando existe conteúdo sem uma conta associada. A recolha pendente ou falhada pode deixar os metadados incompletos.

Os metadados de conteúdo do YouTube incluem `duration_seconds`, `format`, e `sponsorship_status`. A duração pode ser `null`; o formato e o estado de patrocínio usam `desconhecido` quando indisponível.

| Parâmetro           | Valores                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Filtros**         | domain\_category, domain\_id, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment, mentioned\_competitor\_domains |
| **Ordenar**         | citation\_count, citation\_share, citation\_rate, influence\_score                                                                    |
| **Filtros de data** | start\_date, end\_date, providers, countries, personas                                                                                |

**Categorias de domínio:** Próprio, Concorrentes, Social, Comunidades, Avaliações, Mídia, Educacional, Marketplaces, Produtos, Afiliados, Outro

***

### `get_aeo_citation`

Obtenha detalhes e prompts que citam um URL específico.

**Requer:** `brand_kit_id`, `id` (o ID da citação/URL)

**Devolve:** Detalhes do URL, métricas de citação, decomposição da pontuação de influência, tipo de página, sentimento da marca, concorrentes mencionados e o mesmo `social` envelope devolvido por `list_aeo_citations`.

***

### `list_aeo_domains`

Liste domínios citados em respostas de IA para um Brand Kit. Agregado por domínio com métricas de citação.

**Requer:** `brand_kit_id`

**Devolve:** ID do domínio, nome, categoria, URL do logótipo, contagem de citações, contagem de URLs, quota de citações, taxa de citações e tendências.

| Parâmetro           | Valores                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------- |
| **Filtros**         | domain\_category, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment |
| **Ordenar**         | citation\_count, citation\_share, citation\_rate                                          |
| **Filtros de data** | start\_date, end\_date, providers, countries, personas                                    |

***

## Anúncios e anunciantes observados em AEO

Anúncios que a AirOps observa em respostas do ChatGPT e do Google AI Mode para os seus prompts monitorizados. Estas ferramentas consultam dados de anúncios observados usados por [Anúncios](/docs/pt/insights/ads.md), incluindo **Biblioteca de anúncios**, pelo que não precisam de ligação a uma conta do ChatGPT Ads.

{% hint style="info" %}
A cobertura limita-se aos anúncios que a AirOps viu na sua própria recolha de respostas. Estes números não descrevem a cobertura total do mercado, a intenção de segmentação, a entrega de impressões ou o gasto do anunciante.
{% endhint %}

### `list_aeo_ads`

Liste anúncios observados em respostas do ChatGPT e do Google AI Mode para um Brand Kit. Cada linha representa uma plataforma e um par de criativo observado. O mesmo criativo em duas plataformas produz duas linhas, cada uma com as suas próprias contagens de atividade.

**Requer:** `brand_kit_id`

**Devolve:** Provider, ID do criativo observado, ID da família observada, nome do anunciante, domínio, tipo e logótipo, título e corpo do anúncio, aparições, respostas, prompts, frequência, first\_seen, last\_seen e days\_active.

| Parâmetro           | Valores                                                      |
| ------------------- | ------------------------------------------------------------ |
| **Filtros**         | topic\_id, prompt\_id, prompt\_type                          |
| **Filtros de data** | start\_date, end\_date, providers, countries, personas, tags |

**Tipos de anunciante:** próprio, concorrente, outro

`list_aeo_ads` inclui, por predefinição, ambos os providers suportados. Passe `providers: ["chat_gpt"]` ou `providers: ["google_ai_mode"]` para restringir o âmbito. Use `prompt_type EQUALS brand/category` para classificação do prompt; o antigo `brand_mentioned` filtro de tipo de prompt continua a ser um alias de compatibilidade.

***

### `get_aeo_ad`

Obtenha um anúncio observado, incluindo a sua imagem criativa e URL de destino.

**Requer:** `brand_kit_id`, `id` (o `observed_creative_id` devolvido por `list_aeo_ads`)

**Devolve:** Provider, ID do criativo observado, ID da família observada, nome do anunciante, domínio, tipo e logótipo, título do anúncio, corpo, image\_url, target\_url, first\_seen, last\_seen e days\_active.

Passe o provider da linha como um array de um único elemento `providers` array juntamente com o seu ID criativo, por exemplo `providers: ["google_ai_mode"]`. As solicitações de detalhe usam ChatGPT por padrão quando nenhum fornecedor é especificado e exigem um único fornecedor quando um é fornecido.

As métricas em janela reportadas por `list_aeo_ads` (ocorrências, respostas, prompts, frequência) não são devolvidas aqui.

***

### `list_aeo_advertisers`

Liste os anunciantes observados nas respostas do ChatGPT e do Google AI Mode para um Brand Kit. Cada anúncio observado é agregado ao anunciante que o veiculou, identificado pelo domínio canónico.

**Requer:** `brand_kit_id`

**Devolve:** ID do anunciante, nome, domínio, tipo, URL do logótipo, contagem única de anúncios, ocorrências, respostas, prompts, first\_seen e last\_seen.

| Parâmetro           | Valores                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| **Filtros**         | topic\_id, prompt\_id, prompt\_type                                                               |
| **Ordenar**         | advertiser\_name, advertiser\_domain, ads, appearances, answers, prompts, first\_seen, last\_seen |
| **Filtros de data** | start\_date, end\_date, providers, countries, personas, tags                                      |

Os resultados são ordenados pela contagem única de anúncios, do mais prolífico para o menos, a menos que passe **Ordenar**. Utilize `list_aeo_ads` para os anúncios individuais por trás das contagens de cada anunciante.

***

## Playbooks e Feedback

Leia as definições do Playbook, inspecione os resultados da Session e os comentários do revisor, e execute ou publique Playbooks com as permissões existentes da sua workspace. Publicar e executar requer autenticação OAuth do utilizador. As execuções podem consumir créditos da workspace e realizar as ações configuradas no Playbook.

### `list_playbooks`

Liste Playbooks editáveis, incluindo metadados das versões rascunho e ativa.

**Requer:** `workspace_id`

**Opcional:** `search` (título), `page` (padrão 1), `per_page` (padrão 20, máximo 50).

### `get_playbook`

Leia a configuração e a definição de um Playbook em Markdown. As referências de integração não expõem credenciais.

**Requer:** `playbook_id`

**Opcional:** `version_number`. Omita-o para ler o rascunho atual (**Mais recente**); forneça um número para ler uma versão publicada imutável.

### `list_playbook_sessions`

Liste Sessions por ordem cronológica inversa.

**Requer:** `workspace_id`

**Opcional:** `playbook_id`, `estado`, `search` (Session ou nome do criador), `page` (padrão 1), `per_page` (padrão 20, máximo 50). As Sessions arquivadas usam o estado público `arquivado`.

### `get_playbook_session`

Inspecione os metadados da Session e uma página de eventos, incluindo texto, resultados de ferramentas, artefatos e estado de conclusão.

**Requer:** `session_id`

**Opcional:** `after_id` (cursor do evento), `limit` (padrão 20, máximo 50).

Passe o `next_after_id` como `after_id` devolvido para continuar até que seja `null`. As pré-visualizações de texto têm um limite de 2.000 caracteres; `content_truncated: true` indica que existe mais texto. Use `read_playbook_output` para o resultado completo.

### `read_playbook_output`

Leia um resultado de texto em páginas baseadas em caracteres. Os artefactos de texto colaborativos refletem o conteúdo atual do editor, incluindo edições feitas após a execução. Artefactos binários não são suportados.

**Requer:** `session_id` e exatamente um de `event_id` ou `artifact_path`. Os caminhos dos artefactos devem identificar um ficheiro em `artifacts/external/`.

**Opcional:** `offset` (padrão 0), `max_chars` (padrão 20.000, máximo 200.000).

**Devolve:** `conteúdo`, `offset`, `total_chars`, e `next_offset`. Passe `next_offset` de volta como `offset` até que seja `null`.

### `list_artifact_comments`

Leia os comentários do revisor com autor, carimbos de data/hora, estado de resolução e contexto disponível de âncora ou de texto circundante.

**Requer:** `session_id`

**Opcional:** `artifact_path` para limitar os resultados a um artefacto.

Use os comentários juntamente com `read_playbook_output` para rever o feedback no contexto. As sugestões de alterações rastreadas são contabilizadas separadamente em `suggestions_count`; não são fios de comentários. Esta ferramenta lê feedback sem o modificar.

### `publish_playbook`

Publique o rascunho atual como uma nova versão ativa.

**Requer:** `playbook_id` e autenticação OAuth do utilizador.

**Opcional:** `notas` para a versão publicada.

**Devolve:** O ID da versão ativa e os metadados da versão. Confirme o rascunho e a intenção de publicação antes de chamar esta ferramenta; publicar torna o rascunho pendente ativo.

### `run_playbook`

Inicie uma Session assíncrona. Cada chamada inicia uma nova execução.

**Requer:** `playbook_id` e autenticação OAuth do utilizador.

**Opcional:** `inputs` com chave pelo nome da entrada, `mensagem`, e `version_number`.

Por padrão, isto executa o rascunho atual (**Mais recente**). Passe `version_number` para executar uma versão publicada específica. Executar um rascunho não o publica. Confirme a versão pretendida, os inputs e a execução antes de iniciar.

**Devolve:** `session_id`, `session_uuid`, status e informações de versão. Faça polling em `get_playbook_session`, depois leia os resultados e comentários conforme necessário.

## Workflows

Liste Workflows executáveis e inicie ou inspecione execuções com as permissões da sua workspace. As execuções podem consumir créditos e realizar as ações configuradas do Workflow.

### `list_workflows`

Liste Workflows publicados que pode executar. Recursos apenas rascunho, eliminados, agent e legados são excluídos.

**Requer:** `workspace_id`

**Opcional:** `search`, `page` (padrão 1), `per_page` (padrão 20, máximo 50).

### `run_workflow`

Inicie uma execução assíncrona. Cada chamada inicia uma nova execução.

**Requer:** `workflow_id`

**Opcional:** `inputs` com chave pelo nome da entrada e `version_number`.

O padrão é a versão publicada ativa. Passe `version_number` para selecionar outra versão publicada. Confirme o Workflow, os inputs e a execução pretendidos antes de iniciar.

**Devolve:** `execution_id`, status e informações do Workflow/versão.

### `get_workflow_execution`

Inspecione o estado, o resultado ou o erro de uma execução.

**Requer:** `execution_id` devolvido por `run_workflow`.

Faça polling desta ferramenta para acompanhar a execução através de estados como `pendente`, `em execução`, `review_needed`, `sucesso`, `erro`, ou `cancelado`. Um ID de execução devolvido significa que a execução foi iniciada; verifique o estado antes de tratar o resultado como concluído.

## Exemplo: rever uma execução de Playbook

1. Encontre o Playbook com `list_playbooks` e inspecione a sua definição com `get_playbook`.
2. Encontre uma Session com `list_playbook_sessions`, depois leia os seus eventos com `get_playbook_session`.
3. Leia o texto completo com `read_playbook_output` e o feedback do revisor com `list_artifact_comments`.
4. Resuma o resultado e o feedback não resolvido para o revisor.

## Análise de Página

### `list_pages`

Liste páginas com métricas de AEO, Google Search Console e GA4.

**Requer:** `brand_kit_id`

**Devolve:** Para cada página: URL, caminho da pasta, palavra-chave principal e métricas:

* **AEO:** citations\_count, citation\_rate, prompts\_count e tendências
* **GSC:** cliques, impressões, ctr, posição e tendências
* **GA4:** tráfego, sessões, engagement, average\_session\_engagement e tendências
* **Agent Analytics:** `navegação do utilizador` (Visitas de Agente de IA), `treino de IA` (Crawls de Treino), e `pesquisa de IA` (Rastreios de pesquisa na Web)

O Agent Analytics deve ser ligado primeiro. Os seus três contadores suportam filtragem e ordenação para as datas selecionadas, sem variantes de alteração. Use `list_aeo_agent_analytics` para Total Crawls e detalhamentos diários.

| Parâmetro                | Valores                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Filtros**              | Qualquer campo de métrica, url, folder\_name, primary\_keyword, session\_source, session\_medium       |
| **Ordenar**              | Todos os campos de métrica, url, folder\_name                                                          |
| **Filtros inteligentes** | almost\_page\_one, losing\_clicks, rankings\_slipping, losing\_ai\_visibility, citation\_rate\_decline |

**Filtros inteligentes** (use em vez de filtragem manual):

| Filtro                  | Descrição                                                             |
| ----------------------- | --------------------------------------------------------------------- |
| `almost_page_one`       | Páginas classificadas entre #11-20 (vitórias rápidas para a página 1) |
| `losing_clicks`         | Cliques em declínio com posição estável                               |
| `rankings_slipping`     | Posição em declínio ao longo do tempo                                 |
| `losing_ai_visibility`  | Perda de citações AEO                                                 |
| `citation_rate_decline` | Perda de autoridade de IA com SEO estável                             |

***

### `create_page`

Adicione uma página às páginas AEO de um Brand Kit. A AirOps normaliza a URL, verifica que ela pertence ao domínio AEO configurado do Brand Kit e exige que seja única dentro desse Brand Kit.

**Requer:** `brand_kit_id`, `URL`

**Devolve:** ID da página, ID do Brand Kit, ID do domínio AEO, URL normalizada, estado rastreado, carimbo de data/hora de criação e uma mensagem de confirmação.

Confirme a URL e o Brand Kit com o utilizador antes de criar a página. Verifique o resultado com `list_pages` filtrado por URL. Isto adiciona a página à AirOps; não publica conteúdo para um CMS.

***

### `get_page_details`

Obtenha métricas detalhadas para uma página específica.

**Requer:** `id`

**Devolve:** URL, pasta, palavra-chave principal, quota de citações, taxa de citação, contagem de perguntas citadas únicas, métricas GSC (cliques, impressões, posição, CTR) e todas as tendências.

| Parâmetro              | Valores                |
| ---------------------- | ---------------------- |
| **Intervalo de datas** | start\_date, end\_date |

***

### `get_page_prompts`

Obtenha os prompts de IA que citam uma página específica.

**Requer:** `brand_kit_id`, `web_page_id`

**Devolve:** ID do prompt, texto, palavra-chave, topic\_id, volume, total\_answers, answers\_with\_citations, citation\_rate, mention\_rate e tendências.

| Parâmetro              | Valores                                    |
| ---------------------- | ------------------------------------------ |
| **Filtros**            | providers, countries, personas, topic\_ids |
| **Inclui**             | topic                                      |
| **Intervalo de datas** | start\_date, end\_date                     |

***

## Agent Analytics

### `list_aeo_agent_analytics`

Liste pedidos diários de bots para as páginas rastreadas do Brand Kit. [Ligar Agent Analytics](/docs/pt/insights/onsite/traffic.md) antes de consultar estes dados.

**Requer:** `brand_kit_id`

**Devolve:** Linhas que contenham `date`, `plataforma`, `tipo de rastreio`, e `contagem`. Os tipos de crawl são `pesquisa de IA`, `treino de IA`, `navegação do utilizador`, e `outras`. As linhas sem pedidos são omitidas.

| Parâmetro              | Valores                                                                     |
| ---------------------- | --------------------------------------------------------------------------- |
| **Intervalo de datas** | `start_date`, `end_date`                                                    |
| **Filtros**            | `plataforma`, `tipo de rastreio`, ou um único `web_page_id` de `list_pages` |
| **Ordenar**            | `date` (padrão), `contagem`, ou `-count`                                    |
| **Paginação**          | `page`, `per_page` (25 por defeito, 100 no máximo)                          |

Leia cada página antes de somar contagens. O Agent Analytics **Total de rastreios** resume as contagens de crawls de pesquisa e de treino para os motores de IA rastreados. A **Páginas** contagem Total Crawls da tabela contabiliza cada plataforma e tipo de crawl para essa página. Use o [guia de cálculo da API](/docs/pt/programadores/api.md#agent-analytics) para o conjunto exato de motores, receitas de gráficos e comportamento dos limites de data.

## Análises

### `query_analytics`

Consulte analytics com métricas, dimensões e filtros flexíveis. Interface ao estilo BI para análise personalizada.

**Requer:** `brand_kit_id`, `métricas`

**Devolve:** Resultados da consulta com as métricas solicitadas agrupadas por dimensões, além de metadados.

**Métricas:**

| Métrica              | Descrição                                               |
| -------------------- | ------------------------------------------------------- |
| `mention_rate`       | % de respostas que mencionam a marca (0-100)            |
| `share_of_voice`     | Menções da marca vs concorrentes (0-100)                |
| `citation_rate`      | % de respostas que citam o domínio da marca (0-100)     |
| `citation_share`     | Citações da marca vs todas as citações (0-100)          |
| `citation_count`     | Contagem absoluta de citações                           |
| `sentiment_score`    | Sentimento médio (0-100)                                |
| `average_position`   | Posição média nas listas de respostas                   |
| `answer_count`       | Total de respostas analisadas                           |
| `first_mention_rate` | % em que a marca é mencionada em primeiro lugar (0-100) |

**Dimensões** (máx. 3):

| Dimensão          | Descrição                            |
| ----------------- | ------------------------------------ |
| `date`            | Agrupar por período de tempo         |
| `fornecedor`      | Agrupar por fornecedor de IA         |
| `topic`           | Agrupar por tópico rastreado         |
| `concorrente`     | Agrupar por concorrente              |
| `country`         | Agrupar por região/país              |
| `persona`         | Agrupar por persona de cliente       |
| `domain`          | Agrupar por domínio citado           |
| `domain_category` | Agrupar por tipo de fonte de citação |

| Parâmetro              | Valores                                                       |
| ---------------------- | ------------------------------------------------------------- |
| **granularidade**      | diário, semanal, mensal, total (padrão: total)                |
| **Intervalo de datas** | start\_date, end\_date (padrão: últimos 7 dias)               |
| **Filtros**            | providers, topics, countries, personas, brand\_mentioned      |
| **Limite**             | máx. de linhas (padrão 100, máx. 1000)                        |
| **order\_by**          | ordenação personalizada (por exemplo, "citation\_count DESC") |

***

### `get_sentiment_theme_answers`

Obtenha as respostas por trás de um tema de sentimento para que possa inspecionar o texto da resposta de origem e exemplos desse tema.

**Requer:** `brand_kit_id`, `sentiment_theme_id`

**Campos opcionais:** `start_date`, `end_date`, `providers`, `countries`, `topic_ids`, `persona_ids`, `page`, `per_page`

***

### `analytics_chart`

{% hint style="info" %}
**App interativa:** Esta ferramenta renderiza um gráfico na conversa. Disponível em **Codex através do plugin AirOps, Claude Web e Claude Desktop**.
{% endhint %}

Consulte analytics e apresente como um gráfico interativo. Devolve dados com uma referência de UI para visualização.

**Requer:** `brand_kit_id`, `métricas`

**Devolve:** Dados do gráfico com visualização interativa renderizada na conversa.

| Parâmetro              | Valores                                                                  |
| ---------------------- | ------------------------------------------------------------------------ |
| **chart\_type**        | linha, barra, pizza, área (padrão: linha)                                |
| **métricas**           | Igual a query\_analytics                                                 |
| **dimensões**          | Igual a query\_analytics (máx. 2 para gráficos de linha com agrupamento) |
| **granularidade**      | diário, semanal, mensal, total                                           |
| **Intervalo de datas** | start\_date, end\_date                                                   |
| **Filtros**            | providers, topics, countries, personas, brand\_mentioned                 |
| **título**             | Título opcional do gráfico                                               |

**Restrições:**

* Apenas métricas da mesma escala podem ser plotadas em conjunto (percentagem, contagem ou posição)
* Gráficos de área e de barras suportam métricas únicas com dimensões únicas
* Gráficos de linha suportam até 2 dimensões, mas apenas uma métrica quando se usam 2

***

## Relatórios

### `list_reports`

Liste relatórios de analytics guardados.

**Requer:** `brand_kit_id`

**Devolve:** ID do relatório, nome, created\_at, updated\_at.

| Parâmetro   | Valores                        |
| ----------- | ------------------------------ |
| **Filtros** | nome                           |
| **Ordenar** | name, created\_at, updated\_at |
| **Inclui**  | módulos                        |

***

### `get_report`

Obtenha um relatório específico por ID.

**Requer:** `brand_kit_id`, `id`

**Devolve:** ID do relatório, nome, carimbos de data/hora. Com `includes: ['modules']`, devolve configurações completas dos módulos.

***

## Grids

Ferramentas para ler, escrever, criar e executar AirOps Grids programaticamente. Use-as para preencher dados, gerir colunas, desencadear execuções de workflow e obter resultados.

### `create_grid`

Crie um novo Grid vazio e de uso geral com uma folha vazia. Use `add_grid_column` para adicionar colunas e `write_grid` para adicionar linhas.

**Requer:** `nome`

**Campos opcionais:** `workspace_id`

***

### `create_grid_sheet`

Crie uma nova folha dentro de um Grid existente.

**Requer:** `grid_id`, `nome`

***

### `list_grids`

Liste os grids a que o utilizador autenticado tem acesso. Use `includes: ["grid_tables.grid_columns"]` para obter a estrutura da tabela e das colunas necessária para outras ferramentas de grid.

**Devolve:** ID do Grid, nome, ID da workspace e, opcionalmente, detalhes da tabela e das colunas (ID, título, tipo de dados, posição).

| Parâmetro   | Valores                        |
| ----------- | ------------------------------ |
| **Filtros** | name, workspace\_id            |
| **Ordenar** | name, updated\_at, created\_at |
| **Inclui**  | grid\_tables.grid\_columns     |

***

### `read_grid`

Leia linhas de uma tabela do grid. Devolve linhas como objetos com os títulos das colunas como chaves.

**Requer:** `grid_id`, `grid_table_id`

**Devolve:** Metadados do Grid, colunas (com sinalizador de escrita) e dados das linhas com informação de paginação.

As colunas do Playbook também incluem `playbook_id` como no `artefactos`, com o `nome` como no `artifact_type`de cada artefacto. Use estes nomes ao mapear o resultado de uma coluna do Playbook para outra coluna de execução.

| Parâmetro             | Digite  | Predefinido | Descrição                                                       |
| --------------------- | ------- | ----------- | --------------------------------------------------------------- |
| `filters`             | array   | nenhum      | Filtrar por valores de coluna                                   |
| `filters[].column_id` | inteiro | nenhum      | ID da coluna a filtrar                                          |
| `filters[].operator`  | string  | nenhum      | CONTAINS, NOT\_CONTAINS, EMPTY, NOT\_EMPTY, =, !=, >=, <=, >, < |
| `filters[].value`     | string  | nenhum      | Valor do filtro (não é necessário para EMPTY/NOT\_EMPTY)        |
| `column_ids`          | array   | todos       | IDs das colunas a incluir nos resultados                        |
| `limit`               | inteiro | 50          | Linhas por página (1–100)                                       |
| `offset`              | inteiro | 0           | Deslocamento de linhas para paginação                           |
| `truncate`            | inteiro | 0           | Máx. de caracteres por célula (0 = sem truncamento)             |

***

### `read_grid_cell`

Leia o valor completo de uma única célula do Grid. Use isto quando `read_grid` truncar uma célula longa, como um artigo completo, resumo, payload JSON ou campo HTML.

**Requer:** `grid_id`, `grid_table_id`, `row_id`, `column_id`

**Devolve:** Título da coluna, valor completo e tipo de valor.

***

### `write_grid`

Crie ou atualize linhas numa tabela de grid. Máximo de 1000 linhas por chamada.

**Requer:** `grid_id`, `grid_table_id`, `modo`, `linhas`

| Parâmetro | Digite | Descrição                                                                                                    |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `modo`    | string | `create` para adicionar novas linhas, `update` para modificar linhas existentes                              |
| `linhas`  | array  | Objetos de linha com os títulos das colunas como chaves. Para `update` modo, inclua `__id` com o ID da linha |

**Devolve:** `rows_created` (modo create) ou `rows_updated` como no `cells_updated` (modo update).

{% hint style="info" %}
Os valores podem ser strings, números, booleanos, arrays ou objetos. Arrays e objetos são armazenados como JSON. Os títulos das colunas têm de corresponder exatamente às colunas existentes do grid. Use `add_grid_column` para criar primeiro novas colunas.
{% endhint %}

***

### `run_grid_rows`

Dispare a execução de uma ou mais linhas do grid. Isto executa todas as colunas de workflow (execução da app) para cada linha especificada, por ordem de dependência. A execução é assíncrona — esta ferramenta devolve imediatamente metadados de execução.

**Requer:** `grid_id`, `grid_table_id`, `grid_row_ids`

| Parâmetro      | Digite | Descrição                                   |
| -------------- | ------ | ------------------------------------------- |
| `grid_row_ids` | array  | IDs das linhas do grid a executar (máx. 50) |

**Devolve:** Metadados de execução, incluindo os IDs de execução das linhas a acompanhar com `get_grid_row_execution_status`.

{% hint style="info" %}
Máximo de 50 linhas por chamada. Use `get_grid_row_execution_status` para verificar o progresso e a conclusão.
{% endhint %}

***

### `get_grid_row_execution_status`

Verifique o estado das execuções de linhas da Grid. Use isto depois de `run_grid_rows` para consultar até à conclusão.

**Requer:** `grid_id`, `row_execution_ids`

| Parâmetro           | Digite | Descrição                                         |
| ------------------- | ------ | ------------------------------------------------- |
| `row_execution_ids` | array  | IDs das execuções de linhas a verificar (máx. 50) |

**Devolve:** Estado geral e detalhes por coluna de cada execução.

***

### `add_grid_column`

Adicione uma nova coluna a uma tabela Grid. Use isto antes de `write_grid` quando precisar de escrever numa coluna que ainda não existe.

**Requer:** `grid_id`, `grid_table_id`, `título`, `data_type`

| Parâmetro   | Digite  | Descrição                                                                                                     |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `título`    | string  | Título da coluna                                                                                              |
| `data_type` | string  | text, number, datetime, markdown, url, html, image\_from\_url, json, single\_select, playbook, app\_execution |
| `posição`   | inteiro | Posição opcional da coluna (adicionada no fim se omitida)                                                     |

**Devolve:** ID, título, tipo de dados e posição da coluna criada.

Para uma coluna de Playbook, use `data_type: "playbook"` e forneça `playbook_id`. Para uma coluna de Workflow, use `data_type: "app_execution"` e forneça `workflow_id`. Configure `inputs` por nome de Input. Cada mapeamento requer `tipo` como no `value`.

Ao mapear a partir de uma coluna de Playbook, `value` é o ID da coluna de origem na mesma folha, e `artifact_name` é o nome exato do Artefacto:

```json
{
  "article": {
    "type": "column",
    "value": 123,
    "artifact_name": "Final Article"
  }
}
```

Este exemplo é um `inputs` objeto. Copie o nome do Artefacto de `read_grid`, ou dos `artefactos` metadados devolvidos quando `add_grid_column` cria a coluna de origem do Playbook.

***

### `update_grid_column`

Atualize o título, tipo de dados ou os mapeamentos de Input de Playbook/Workflow de uma coluna da Grid.

**Requer:** `grid_id`, `grid_table_id`, `grid_column_id`, e pelo menos um de `título`, `data_type`, ou `inputs`

**Devolve:** IDs da Grid e da folha, além do ID, título, tipo de dados e posição da coluna atualizada. As colunas de Playbook e Workflow também incluem os respetivos detalhes de configuração.

Ao passar `inputs` substitui todo o mapeamento de Input. Inclua todos os Inputs que pretende manter. A ferramenta não pode reposicionar uma coluna nem alterar qual Playbook ou Workflow ela executa.

***

### `delete_grid_column`

Elimine uma coluna da Grid e as suas colunas dependentes de saída de Workflow ou de Artefacto de Playbook.

**Requer:** `grid_id`, `grid_table_id`, `grid_column_id`

**Devolve:** `grid_id`, `grid_table_id`, e `deleted_column_ids` para todas as colunas afetadas.

{% hint style="warning" %}
Revise as colunas dependentes antes de eliminar. A eliminação é bloqueada enquanto execuções de linhas estiverem a decorrer na folha.
{% endhint %}

***

### Exemplo: Fluxo de trabalho de dados da Grid

Um fluxo de trabalho programático típico usando as ferramentas da Grid:

1. **Descobrir:** Chame `list_grids` com includes para localizar a Grid e a sua estrutura de colunas
2. **Preparar:** Chame `add_grid_column` para criar quaisquer colunas em falta
3. **Preencher:** Chame `write_grid` com o modo `create` para adicionar linhas
4. **Executar:** Chame `run_grid_rows` para acionar as colunas de workflow da linha e depois consultar `get_grid_row_execution_status` até concluir
5. **Recuperar:** Chame `read_grid` para obter os resultados
6. **Atualizar:** Chame opcionalmente `write_grid` com o modo `update` para escrever os dados de volta

***

## Bases de Conhecimento

### `list_knowledge_bases`

Liste todas as Bases de Conhecimento às quais tem acesso. As Bases de Conhecimento armazenam documentos para pesquisa semântica.

**Devolve:** ID da Base de Conhecimento, nome, ID do espaço de trabalho, estado e contagem de documentos. Apenas Bases de Conhecimento com estado `pronto` podem ser pesquisadas.

| Parâmetro   | Valores                              |
| ----------- | ------------------------------------ |
| **Filtros** | workspace\_name, name, workspace\_id |
| **Ordenar** | name, created\_at                    |

***

### `knowledge_base_manage`

Crie ou atualize uma Base de Conhecimento. Omita `knowledge_base_id` para criar uma nova Base de Conhecimento; forneça-o para atualizar uma existente.

**Campos:** `knowledge_base_id`, `nome`, `workspace_id`

**Obrigatório na criação:** `nome`, mais `workspace_id` quando o utilizador tem acesso a vários espaços de trabalho.

**Devolve:** ID da Base de Conhecimento, nome, ID do espaço de trabalho, estado, contagem de documentos e se foi criada.

***

### `search_knowledge_base`

Pesquise conteúdo relevante numa Base de Conhecimento usando similaridade semântica.

**Requer:** `knowledge_base_id`, `query`

**Parâmetros:** `top_k` (número de resultados, 1-20, predefinição 5)

**Devolve:** Conteúdo correspondente classificado por relevância.

***

### `knowledge_base_create_direct_upload`

Inicie o fluxo de carregamento de ficheiros em duas etapas para ingestão na Base de Conhecimento. A ferramenta devolve um URL de upload pré-assinado, os cabeçalhos necessários e um `signed_id`.

**Requer:** `knowledge_base_id`, `filename`, `content_type`, `byte_size`, `checksum`

**Devolve:** `signed_id`, `upload_url`, e `upload_headers`.

***

### `knowledge_base_add_file`

Registe um ficheiro carregado numa Base de Conhecimento depois de `knowledge_base_create_direct_upload`. O documento é colocado em fila para indexação.

**Requer:** `knowledge_base_id`, `signed_id`, `nome`, `document_type`

**Campos opcionais:** `metadata`

**Devolve:** IDs dos documentos criados e estado pendente.

***

### `knowledge_base_add_urls`

Ingestione em lote uma ou mais páginas web numa Base de Conhecimento. Cada URL torna-se um documento separado e é indexado assincronamente.

**Requer:** `knowledge_base_id`, `urls`

**Campos opcionais:** `metadata`

**Devolve:** IDs dos documentos criados e estado pendente.

***

### `knowledge_base_get_status`

Obtenha o estado de indexação da Base de Conhecimento e os estados por documento. Use isto depois de adicionar ficheiros ou URLs.

**Requer:** `knowledge_base_id`

**Campos opcionais:** `document_ids`, `cursor`, `items`

***

### `knowledge_base_get_document`

Obtenha um documento da Base de Conhecimento por ID, incluindo metadados do documento e conteúdo extraído quando disponível.

**Requer:** `knowledge_base_id`, `document_id`

***

### `knowledge_base_update_document_metadata`

Substitua os metadados visíveis ao utilizador de um documento. Os metadados são um objeto chave/valor de um único nível e podem ser usados nos filtros de pesquisa da Base de Conhecimento.

**Requer:** `knowledge_base_id`, `document_id`, `metadata`

***

### `knowledge_base_delete_document`

Elimine permanentemente um único documento de uma Base de Conhecimento.

**Requer:** `knowledge_base_id`, `document_id`

{% hint style="warning" %}
Esta ação não pode ser anulada. Confirme com o utilizador antes de eliminar um documento.
{% endhint %}

***

### `knowledge_base_delete`

Elimine permanentemente uma Base de Conhecimento e todos os seus documentos.

**Requer:** `knowledge_base_id`

{% hint style="warning" %}
Isto elimina a Base de Conhecimento, todos os documentos e os vetores subjacentes. Confirme com o utilizador antes de a chamar.
{% endhint %}

***

## Opções de consulta

Todas as ferramentas de listagem suportam:

| Opção         | Descrição                                                                         |
| ------------- | --------------------------------------------------------------------------------- |
| **Filtros**   | Restringir por valores de campo (EQUALS, CONTAINS, EQ, NEQ, GT, LT, GEQ, LEQ, IN) |
| **Inclui**    | Solicitar dados relacionados numa única chamada                                   |
| **Campos**    | Selecionar campos específicos a devolver                                          |
| **Ordenar**   | Ordenar por campos suportados (prefixe `-` para ordem decrescente)                |
| **Paginação** | Controle os resultados com `page` como no `per_page` (máx. 100)                   |

***

## Provedores de IA

Valores de provedor disponíveis para filtragem:

* `chat_gpt`
* `gemini`
* `perplexity`
* `google_ai_mode`
* `google_ai_overview`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/docs/pt/programadores/tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.