Projetos e 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, então os seus próprios projetos continuam intactos.

Uma sessão típica

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 ou GET /v1/nodes.

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

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.

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.

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

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.

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.

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.

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.

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

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.

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_.

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:

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 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.

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.

delete_workflow

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

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

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.

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

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.

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.

Retorna: executionId e name. Acompanhe a execução com get_app_run ou explique uma falha com diagnose_run. Os clientes com MCP Apps mostram o progresso da execução num cartão.