> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reaproveitando Canvases, Agentes e templates

> Execute um Canvas ou Agente existente como etapa e gere documentos a partir de templates .docx

Três módulos permitem que um Workflow reaproveite coisas que existem fora dele: **Canvas Existente** e **Agent Existente** executam algo que o seu time já construiu e publicou, e **Document Templater** preenche um template `.docx` que você envia. Nos três, a configuração é principalmente **mapeamento**: decidir qual valor do Workflow entra em qual variável, input ou placeholder.

No exemplo desta seção, **Approval Letter** é um Document Templater que preenche `approval-letter.docx` com a contraparte, o valor formatado e o solicitante.

## Canvas Existente

**Canvas Existente** (grupo **Módulos**) executa um Canvas do seu Workspace como uma etapa. Use quando um Canvas já está testado e em produção: você mantém um só lugar para melhorar o prompt, e todos os Workflows que o usam se beneficiam.

**1. Selecione o Canvas**

Clique em **Selecionar Canvas** e busque por nome ou projeto. A lista mostra quando cada Canvas foi publicado pela última vez; um Canvas **Não Publicado** não pode ser usado. Você também pode selecionar um **Workflow** aqui para executar outro Workflow como etapa.

**2. Escolha como prosseguir**

* **Referenciar diretamente**: a etapa executa o Canvas como ele está publicado. Você não edita o prompt a partir do Workflow.
* **Fazer uma cópia**: duplica o Canvas dentro deste Workflow para você editá-lo diretamente, sem depender do original.

**3. Escolha a versão**

* **Sempre usar a versão de Production**: a etapa acompanha o que estiver publicado em Production. Publicar uma nova versão do Canvas muda o comportamento do Workflow.
* **Fixar versão publicada atual**: a etapa continua usando exatamente esta versão até você trocar.
* **Ambiente**: acompanha a versão publicada em um ambiente específico, por exemplo `staging`.

**4. Atribuir Variáveis**

**Variáveis do Canvas** lista as variáveis da versão publicada. Para cada uma, digite `@` e escolha a **Variável do Workflow** (uma Entrada ou uma saída anterior) que a preenche. Uma variável de arquivo do Canvas recebe uma Entrada de arquivo ou uma saída de arquivo.

![Etapa Canvas Existente com o ambiente Produção e o mapeamento Atribuir Variáveis](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/pt/workflow/existing-canvas.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=76deb745f76f8cfa80b86787b3bfeed4)

### O que a etapa devolve

A saída do Canvas: um objeto com os atributos do [Formato de Saída](https://docs.tela.com/pt/craft/output-format.md) dele quando existe um, senão `content` com o texto. Esses atributos aparecem no menu `@` das etapas seguintes. Quando o item selecionado é um Workflow, a saída é um objeto com uma chave por etapa daquele Workflow, contendo a saída de cada etapa.

> [!NOTE]
>
> O Canvas precisa de uma versão publicada. A etapa executa o Canvas pelo mesmo caminho da API, então as execuções dela aparecem no **Usage** do Canvas e também em Depurar do Workflow.

## Agent Existente

**Agent Existente** executa um [Agente](https://docs.tela.com/pt/creating-your-first-agent.md) publicado do seu Workspace, sempre na versão publicada: publicar o Agente de novo muda o que a etapa faz. Use para a parte do processo que não dá para desenhar de antemão: pesquisa, uma interação de várias etapas com um sistema externo, trabalho que precisa de ferramentas.

**1. Selecione o Agent**

Clique em **Selecionar Agent** e escolha um Agente **Publicado**. Agentes não publicados aparecem na lista, mas não podem rodar.

**2. Atribuir Inputs**

**Inputs do Agent** lista os inputs declarados pelo Agente. Mapeie cada um para uma **Variável do Workflow** com `@`, como em um Canvas.

![Etapa Agent Existente com os inputs do Agent atribuídos a variáveis do Workflow](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/pt/workflow/existing-agent.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=4d5ec64fa69fcffe898aa4f7a24be65e)

A etapa devolve o que o Agente produz: texto, ou um objeto quando o Agente declara um formato de saída. As credenciais do Workspace ficam disponíveis para o Agente enquanto ele roda no Workflow, pelo nome, sem expor os valores; veja [Usando Credenciais em Agentes](https://docs.tela.com/pt/credentials.md#usando-credentials-em-agents).

> [!NOTE]
>
> Execuções de Agente demoram mais e custam mais do que um Módulo de IA, e o resultado é menos previsível. Prefira um Módulo de IA quando a tarefa cabe em uma instrução, e reserve o Agent Existente para as etapas que precisam de autonomia.

## Document Templater

**Document Templater** (grupo **Recursos**) gera um documento a partir de um template `.docx`, substituindo os placeholders por valores do Workflow. No grafo, a etapa aparece como **Gerar Documento**.

Monte o template primeiro; [Como criar templates .docx](https://docs.tela.com/pt/how-to-build-docx-templates.md) explica a sintaxe `{placeholder}` e as regras dela. Para a carta de aprovação:

```text theme={null}
Prezado(a) {counterparty},

Confirmamos a aprovação do contrato {approval_code}
no valor de {total_formatted}, solicitado por {requester}.
```

**1. Envie o template**

Solte o arquivo `.docx` na etapa ou **procure no seu computador**. Apenas `.docx` é aceito. O Tela extrai os placeholders e mostra **N placeholder(s) encontrado(s)**.

**2. Atribua os placeholders**

**Placeholders do Template** lista cada `{placeholder}`. Para cada um, digite `@` e escolha a **Variável do Workflow** que o preenche: `counterparty` ← `Extract Data › counterparty`, `total_formatted` ← `Normalize Values › total_formatted`, `requester` ← a Entrada `requester`. Todo placeholder precisa de um valor para a etapa ficar completa.

**3. Dê nome ao arquivo de saída**

**Nome do Arquivo de Saída**, por exemplo `approval-letter.docx`.

**4. Configurações opcionais**

* **Habilitar Mustache** ativa a sintaxe Mustache no template, para seções e repetições sobre listas. Quais recursos do Mustache são aceitos não está documentado aqui; teste com o seu template.
* **Criar Permalink** também produz um link compartilhável para o arquivo gerado.

![Etapa Gerar Documento com o template enviado, os placeholders atribuídos a variáveis e o nome do arquivo de saída](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/pt/workflow/generate-document.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=198738fdf5dba16b5b3a7d046c59b228)

### O que a etapa devolve

| Campo | Significado |
| - | - |
| `generatedDocument` | o arquivo: `name`, `mimeType`, `fileUrl`, `vaultReference` |
| `generatedAt` | quando foi gerado |
| `permalinkUrl`, `permalinkId`, `permalinkExpiresAt` | só quando **Criar Permalink** está ativo |

O arquivo gerado é um arquivo como qualquer outro: uma etapa seguinte pode passá-lo a um Módulo de IA (usado como Parser ou Multimodal) para uma checagem final, ou uma tarefa da Workstation o mostra para download. No painel de resultado você pode abri-lo em tela cheia.

> [!TIP]
>
> Os valores entram no template como texto. Formate números e datas na etapa que os produz (um Módulo de IA instruído a devolver `"125.000,00"`, ou uma etapa de [Execução de Código](https://docs.tela.com/pt/workflow/code-execution.md)) em vez de esperar que o template faça isso.

## Templates do seletor

A aba **Templates** do seletor de módulos insere um template de Workflow pronto no seu grafo, com as próprias etapas e variáveis a atribuir. É um ponto de partida que você adapta, não uma etapa reutilizável; depois de inserido, as etapas passam a ser suas e você pode editá-las livremente.

## Mapeamento de entradas, em resumo

| Módulo | O que você mapeia | De onde vêm os valores |
| - | - | - |
| Canvas Existente | as variáveis do Canvas | Entradas e saídas anteriores, com `@` |
| Agent Existente | os inputs do Agente | o mesmo |
| Document Templater | os `{placeholders}` do `.docx` | o mesmo |

Em todos os casos, o menu `@` mostra só o que está disponível naquela etapa; veja [O que uma etapa pode ver](https://docs.tela.com/pt/workflow/inputs-and-references.md#o-que-uma-etapa-pode-ver).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.