# Projetos e workflows

> Deixe um assistente de IA montar workflows do Nodaro em JSON, editá-los com verificação de versão, exportá-los, importá-los e executá-los no projeto mcp.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools/projects-and-workflows

As **ferramentas de projetos e workflows** permitem que um assistente monte workflows do Nodaro do jeito que o editor os armazena: como nós e conexões em JSON. O assistente aprende o formato com `start_workflow_editor` e `get_node_skill`, cria e edita workflows, move-os entre projetos com exportação e importação e os executa. Todo workflow que ele cria ou edita fica no [projeto mcp](https://nodaro.ai/docs/mcp/tools#the-mcp-project), então os seus próprios projetos continuam intactos.

## Uma sessão típica
### Aprenda o formato
Chame `start_workflow_editor`. A ferramenta retorna a estrutura JSON do workflow, as regras para ligar as conexões e o catálogo de tipos de nó. Chame `get_node_skill` para cada tipo de nó de que o workflow precisa e `get_picker_catalog` para os valores válidos de cada seletor.

### Crie o workflow
Chame `create_workflow` com um nome e, se quiser, os primeiros nós e conexões. O workflow abre no editor, em **Workflows MCP**.

### Edite com segurança
Leia o grafo atual com `get_workflow_json` e depois envie um `delta` para `update_workflow_json` com a versão que você leu. Só mudam os nós e as conexões que você indicar.

### Execute
Chame `run_workflow` e acompanhe a execução com [`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run). O resultado de cada nó é salvo na sua biblioteca.

## `start_workflow_editor`
Retorna o guia que um assistente lê antes de montar ou editar um workflow. O guia cobre a estrutura JSON do workflow, as convenções de ligação de conexões e entradas e as regras de `update_workflow_json`. Também lista os campos de resultado de cada nó de geração e o catálogo de tipos de nó.

**Permissão:** nenhuma, sempre visível. **Créditos:** grátis.

Esta ferramenta não tem parâmetros. Ela não altera nada e pode ser chamada quantas vezes você quiser.

## `get_node_skill`
Retorna o guia completo de um tipo de nó: os campos de dados com os valores padrão, quando usá-lo, erros comuns e um exemplo completo em JSON. Use-a antes de escrever um nó desse tipo num workflow.

O custo em créditos no guia é o preço de tabela do nó. Para o preço cobrado por uma execução, use [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models) ou `GET /v1/nodes`.

**Permissão:** nenhuma, sempre visível. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `node_type` | string | **Obrigatório.** O tipo de nó em kebab case, como listado por `start_workflow_editor`, por exemplo `generate-image`, `list` ou `trim-video`. |

**Retorna:** o guia do nó. Um tipo desconhecido retorna um erro com a lista de tipos válidos.

## `get_picker_catalog`
Retorna os valores válidos de um nó seletor, como **Cenário** (Setting), **Clima** (Mood), **Pessoa** (Person) ou **Lente** (Lens). Os seletores acrescentam uma frase ao prompt do nó que alimentam, então um workflow precisa usar um ID real do catálogo. Chame esta ferramenta antes de escrever o valor de um seletor num workflow.

**Permissão:** nenhuma, sempre visível. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `node_type` | string | O tipo do seletor em kebab case, por exemplo `setting`. Omita-o para listar todos os seletores. |
| `detail` | string | `compact` (padrão): `id`, `label`, `category`, `term`, `icon` e `imageUrl`. `full` também acrescenta a `description` e o `promptHint` de cada opção, a frase completa que ela adiciona ao prompt. |
| `category` | string | Para seletores de uma dimensão: só as opções de uma categoria. |
| `field` | string | Só uma dimensão de um seletor de várias dimensões, como **Pessoa**, **Figurino e beleza** (Styling) ou **Enquadramento** (Framing). Também as configurações extras de um seletor de uma dimensão, como a posição, a duração e a intensidade de **Transição** (Transition) e **Efeitos de personagem** (Character FX), ou a posição e o ritmo de **Movimento de personagem** (Character Motion). |

**Retorna:** sem `node_type`, um diretório de todos os seletores com `nodeType`, `label`, `kind` (`single` ou `multi`), o campo ou os campos de valor, `optionCount` e `imageCount`. Com `node_type`, as opções desse seletor. Um tipo desconhecido retorna um erro com os tipos válidos.

Cada opção traz um `term`, a frase curta e profissional a escrever no prompt, como `whip pan left`. `label` serve só para exibição. Uma opção sem efeito, como `auto` ou `none`, tem o `term` vazio. As opções com imagem trazem um `imageUrl` absoluto: mostre-o como está e nunca monte um a partir de um ID. **Pessoa** e **Figurino e beleza** também retornam `sections`, os tópicos deles em ordem, cada um com um rótulo, os campos e uma imagem opcional.

```json
{
"nodeType": "person",
"sections": [
{ "label": "Identity", "fields": ["type", "age", "ethnicity", "regionalAesthetic"],
"imageUrl": "https://app.nodaro.ai/picker-art/character/sections/identity.2d5ec1a4.webp" }
],
"dimensions": [
{ "field": "type", "label": "Type", "options": [
{ "id": "man", "label": "Man", "term": "man",
"imageUrl": "https://app.nodaro.ai/picker-art/character/person/man.d6bed999.webp" }
] }
]
}
```

As imagens dos seletores de look só são retornadas no Nodaro Cloud. [Catálogos de seletores](https://nodaro.ai/docs/developers/picker-catalogs) cobre os mesmos dados para desenvolvedores.

## `list_projects`
Lista todos os projetos da sua conta, ordenados por nome, com o ID, o nome, a descrição, o número de workflows e a data de criação de cada um. O assistente pode ler todos os seus projetos, mas só edita o projeto mcp.

**Permissão:** `workflows:read`. **Créditos:** grátis.

Esta ferramenta não tem parâmetros.

**Retorna:** `data`, a lista de projetos.

## `get_project`
Retorna um projeto pelo ID ou pelo nome.

**Permissão:** `workflows:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `project_id` | string | **Obrigatório.** Um ID de projeto ou um nome de projeto. O nome precisa ser idêntico, inclusive nas maiúsculas, por exemplo `My Feature Film`. |

**Retorna:** o ID, o nome, a descrição, o número de workflows e a data de criação do projeto.

## `list_workflows`
Lista os workflows do projeto mcp, dos mais recentes para os mais antigos.

**Permissão:** `workflows:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `limit` | integer | De 1 a 100. Padrão: `20`. |
| `cursor` | string | O `next_cursor` da página anterior. |
| `include_sub_workflows` | boolean | Padrão: `false`, que oculta os sub-workflows que pertencem a outro workflow, como faz a visualização de projeto do editor. Passe `true` para listá-los também. |

**Retorna:** `data`, com o ID, o nome, a descrição, a versão, a miniatura e as datas de cada workflow, e `next_cursor`. Um `next_cursor` igual a `null` indica a última página.

## `get_workflow`
Retorna os detalhes de um workflow do projeto mcp: o nome, a descrição, a versão e as datas.

**Permissão:** `workflows:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `workflow_id` | string | **Obrigatório.** Um ID de workflow do projeto mcp. |

## `get_workflow_json`
Retorna o grafo completo de um workflow do projeto mcp: os nós, as conexões, as configurações, o nome, `updated_at` e `version`.

**Permissão:** `workflows:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `workflow_id` | string | **Obrigatório.** Um ID de workflow do projeto mcp. |

**Retorna:** o grafo. Guarde `version` e envie-o de volta com a sua próxima alteração, para que a alteração falhe em vez de sobrescrever a edição de outra pessoa.

## `create_workflow`
Cria um workflow no projeto mcp, vazio ou com um grafo inicial.

**Permissão:** `workflows:write`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `name` | string | **Obrigatório.** De 1 a 200 caracteres. |
| `description` | string | Até 2.000 caracteres. |
| `nodes` | array | Os primeiros nós, no formato de nó do editor. |
| `edges` | array | As primeiras conexões. |
| `settings` | object | As configurações do workflow. |

**Retorna:** o `id` e o `name` do novo workflow. As configurações que um modelo não aceita são corrigidas, como descrito em [update_workflow_json](#update_workflow_json).

## `update_workflow_json`
Altera um workflow do projeto mcp: o grafo, as configurações ou a miniatura. Todos os campos, exceto `workflow_id`, são opcionais; assim, você pode, por exemplo, trocar só a miniatura.

**Permissão:** `workflows:write`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `workflow_id` | string | **Obrigatório.** Um ID de workflow do projeto mcp. |
| `delta` | object | Uma alteração parcial, aplicada em uma única etapa sobre `delta.base_version`. É a forma preferida de editar. Veja abaixo. |
| `nodes` | array | Substitui todos os nós. Envie junto com `edges`. |
| `edges` | array | Substitui todas as conexões. Envie junto com `nodes`. |
| `settings` | object | Substitui as configurações do workflow. |
| `thumbnail_url` | string or null | A URL de uma imagem que já está hospedada, ou `null` para remover a miniatura. |
| `expected_version` | integer | O `version` de `get_workflow_json`. A alteração é recusada se o workflow tiver mudado desde então. |
| `expected_updated_at` | string | O `updated_at` de `get_workflow_json`, uma forma mais antiga de fazer a mesma verificação. Prefira `expected_version`. |

**Retorna:** uma confirmação com o número de nós e a lista das configurações que o Nodaro corrigiu, se houver.

### Editar com um delta
Um `delta` indica só o que muda, pelo ID. Ele não pode ser combinado com `nodes`, `edges`, `settings`, `thumbnail_url` nem com os campos `expected_`.

| Campo do delta | O que faz |
| --- | --- |
| `base_version` | **Obrigatório.** O `version` de `get_workflow_json`. A alteração é recusada se o workflow tiver mudado desde então. |
| `upsert_nodes` | Nós inteiros a adicionar ou substituir, identificados pelo ID. |
| `delete_node_ids` | Nós a remover. As conexões deles também são removidas. |
| `upsert_edges` | Conexões inteiras a adicionar ou substituir, identificadas pelo ID. |
| `delete_edge_ids` | Conexões a remover. |
| `set` | Um novo `name`, ou novas `settings` que substituem as antigas. |

Prefira um delta a enviar o grafo inteiro. Uma gravação completa baseada numa cópia antiga apaga as alterações que outra sessão fez nesse meio-tempo.

### Quando o workflow mudou nesse meio-tempo
Com `expected_version`, `expected_updated_at` ou um delta, um workflow que mudou desde a sua leitura retorna um conflito: “Workflow was modified since you last read it. Fetch the latest JSON with get_workflow_json and retry.” Leia-o de novo e repita a alteração. Sem esses campos, a gravação sobrescreve o workflow incondicionalmente.

### Configurações que um modelo não aceita
Os nós de imagem recebem configurações específicas de cada modelo, como `aspectRatio`, `resolution` e `quality`, e cada modelo permite valores diferentes. Quando um nó pede um valor que o modelo dele não aceita, o Nodaro não recusa a gravação. Ele troca o valor por um que o modelo aceita, ou o remove quando o modelo não tem essa configuração, e a resposta lista cada alteração:

```text
Updated workflow 4f0c… (12 nodes).

Adjusted 2 parameter(s) the selected model does not accept:
  - node_8 (gpt-image): aspectRatio "16:9" → "1:1" — GPT Image 1.5 does not
support aspect_ratio "16:9". Supported: 1:1, 3:2, 2:3.
  - node_8 (gpt-image): resolution "2K" → removed — GPT Image 1.5 has no
resolution setting.
```

O resultado estruturado traz a mesma lista em `adjustments`. O valor armazenado não é o que você enviou, então não envie o valor original de novo. Confira os valores permitidos de cada modelo com [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models) ou escolha um modelo que aceite o que você precisa. `create_workflow` e `import_workflow` corrigem as configurações da mesma forma. Um nó configurado com vários modelos ao mesmo tempo fica como está.

### Texto antes e depois do prompt
O `data` de qualquer nó de IA pode trazer `promptPrefix` e `promptSuffix`, textos que o Nodaro adiciona antes e depois do prompt do nó quando ele é executado. Veja [Texto antes e depois do prompt](https://nodaro.ai/docs/concepts/prompt-pre-post-text).

### Produções do Studio
Um workflow que contém uma produção do Studio guarda as cenas e os resultados dela em `settings.studio`. Uma alteração de configurações que modifique ou descarte `settings.studio` é recusada. Copie-o sem mudanças de `get_workflow_json` ou omita `settings`. Para alterar uma produção, use as [ferramentas de produção do Studio](https://nodaro.ai/docs/mcp/tools/studio-productions).

## `delete_workflow`
Exclui um workflow do projeto mcp. A exclusão é permanente.

**Permissão:** `workflows:write`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `workflow_id` | string | **Obrigatório.** Um ID de workflow do projeto mcp. |

**Retorna:** uma confirmação, ou um erro quando o workflow não está no projeto mcp.

## `export_workflow`
Exporta qualquer um dos seus workflows, de qualquer projeto, como um pacote JSON portátil. É a única ferramenta de workflow que não se limita ao projeto mcp.

**Permissão:** `workflows:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `workflow_id` | string | **Obrigatório.** Qualquer um dos seus workflows. |
| `with_assets` | boolean | Padrão: `false`. `true` também inclui no pacote os personagens, objetos e locais que o workflow usa. |

**Retorna:** o pacote como uma string JSON. Passe a string inteira para `import_workflow`.

| Modo | O que o pacote contém | Para que usar |
| --- | --- | --- |
| Template, `with_assets: false` | O grafo, sem o conteúdo específico das entidades | Compartilhar a estrutura de um workflow como um template reutilizável |
| Completo, `with_assets: true` | O grafo e todos os personagens, objetos e locais que ele usa | Levar uma produção completa para outra conta ou instância |

Quando um nó usa uma mídia que outra instância não consegue baixar, como um arquivo no armazenamento local de uma instalação self-hosted, o pacote a lista em `portability.unreachableMedia`, com o nó, o campo e a URL. O pacote ainda pode ser importado, mas esses nós não são executados em outro lugar até que a mídia seja enviada de novo.

## `import_workflow`
Importa um pacote de `export_workflow` para o projeto mcp.

**Permissão:** `workflows:write`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `workflow_json` | string | **Obrigatório.** A string JSON inteira de `export_workflow`. |

**Retorna:** o `id` e o `name` do novo workflow e um `importReport` que diz quais mídias foram copiadas, quais ficaram como estavam e quais foram ignoradas.

- **As mídias são copiadas.** As mídias de outros hosts são copiadas para esta instância quando podem ser acessadas, e o workflow é executado a partir das cópias. Os limites são 25 arquivos para o grafo e mais 25 para as entidades do pacote, com imagens de até 20 MB e vídeos ou áudios de até 50 MB. As mídias num host privado que esta instância não consegue acessar ficam como estão e são listadas como `unreachable`.
- **As entidades são recriadas.** Os personagens, objetos, criaturas e locais do pacote são criados de novo na sua conta, com novos IDs. Os nós de entidade e cada menção com `@` no grafo ou nas configurações apontam para as novas cópias, e `assetIdMap` relaciona cada ID antigo ao novo.
- **As cópias contam no seu armazenamento.** As imagens das entidades do pacote são copiadas para o seu próprio armazenamento. Quando o armazenamento está cheio, `assetsSkipped` indica as entidades que não foram criadas; o workflow é importado mesmo assim.

## `run_workflow`
Executa um workflow do projeto mcp, exatamente como uma execução no editor.

**Permissão:** `workflows:execute`. **Créditos:** os créditos de cada nó executado, aos mesmos preços do editor.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `workflow_id` | string | **Obrigatório.** Um ID de workflow do projeto mcp. |
| `inputs` | object | Alterações para esta execução, indexadas pelo ID do nó. Um valor simples, como `"blue car"`, vai para o campo de entrada principal do nó. Um objeto, como `{ "prompt": "..." }`, define campos pelo nome. |
| `client_request_id` | string | Um token de nova tentativa: de 8 a 128 caracteres entre letras, dígitos e `_ - . :`. Reutilize-o ao repetir uma chamada que expirou, para que a execução não seja iniciada nem cobrada duas vezes. Use um valor novo para uma nova execução. |

**Retorna:** `executionId` e `name`. Acompanhe a execução com [`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run) ou explique uma falha com [`diagnose_run`](https://nodaro.ai/docs/mcp/tools/jobs#diagnose_run). Os clientes com MCP Apps mostram o progresso da execução num cartão.

## Frequently asked questions

### Um assistente pode editar os workflows dos meus próprios projetos?

Não. As ferramentas de workflow só editam e executam os workflows do projeto mcp. Para trabalhar em outro workflow, o assistente o exporta com export_workflow e importa uma cópia com import_workflow.

### Como um assistente aprende o formato dos workflows?

Ele chama primeiro start_workflow_editor, que retorna a estrutura JSON do workflow, as regras de ligação e a lista de tipos de nó. Depois, chama get_node_skill para cada tipo de nó que quer usar.

### O que acontece se duas sessões editarem o mesmo workflow?

Passe a versão de get_workflow_json como expected_version, ou envie um delta com base_version. Se o workflow mudou nesse meio-tempo, a gravação é recusada e nada é sobrescrito.

### E se um workflow pedir a um modelo uma configuração que ele não aceita?

O Nodaro a corrige em vez de falhar. Uma proporção, resolução ou qualidade não aceita é trocada por um valor aceito ou removida, e a resposta lista cada alteração em adjustments.

### Executar um workflow pelo MCP custa mais do que no editor?

Não. run_workflow gasta os mesmos créditos que uma execução no editor. Montar, ler e editar workflows é grátis.