Usando arquivos em workflows

Um arquivo é um documento, imagem, planilha ou PDF no seu workspace. Um workflow pode ler um arquivo para agir sobre o conteúdo, passar um arquivo a um bloco ou ferramenta que precisa dele (anexar um PDF a um e-mail, enviar uma imagem a um modelo de visão) ou produzir um arquivo novo e salvá-lo. O bloco File é como um arquivo entra ou sai de um workflow; o trabalho no meio fica a cargo do bloco que a tarefa pedir.

O que você faz com um arquivo depende da tarefa, então esta página cobre as operações do bloco File e como um arquivo se move entre blocos, em vez de uma receita fixa. O exemplo usado ao longo da página lê report.pdf, pede a um agente para resumir e salva o resumo como summary.md, exercitando leitura, processamento e escrita em um só workflow.

O bloco File

O bloco File é um bloco com cinco operações, escolhidas em um dropdown. Cada operação é uma forma diferente de um arquivo, ou do seu conteúdo, entrar ou sair do workflow.

Read entrega ao próximo bloco o arquivo em si; Get Content entrega o texto de dentro. Fetch traz os dois para uma URL externa. Write e Append colocam um arquivo para fora. Um workflow usa só as operações de que a tarefa precisa, muitas vezes só Read. As duas seções abaixo cobrem Read e Write; as outras operações são variantes anotadas ao lado.

Lendo um arquivo

No nosso exemplo, o primeiro bloco File está em Read, com report.pdf escolhido no seletor. Ao rodar, produz files: uma lista de objetos de arquivo, um por arquivo lido. O primeiro é <file1.files[0]>.

Quando o próximo passo precisa do texto do arquivo em vez do arquivo em si, use Get Content: ele extrai o texto e devolve contents, um array com uma string por arquivo, lido como <file1.contents[0]>.

Um objeto de arquivo é o formato padrão que o Zoen usa para todo arquivo. Ele carrega os detalhes:

{
  "id": "wf_V1StGXR8z5jdHi6B…", // workspace file ID
  "name": "report.pdf",
  "url": "https://…",         // where to access it
  "size": 248120,             // bytes
  "type": "application/pdf"
}

Você raramente digita uma referência à mão. Onde um parâmetro de bloco aceita um arquivo ou um valor, o builder lista as saídas disponíveis e você escolhe a que quer. O modo Read também aceita um ID de arquivo direto no modo avançado, que é como você lê um arquivo produzido antes na mesma execução.

Processando o arquivo

Depois que um arquivo é lido, um bloco de processamento lê essa saída pelo nome. Dois blocos fazem isso, e consomem o arquivo de formas diferentes.

Bloco Agent

Um bloco Agent tem uma entrada Files. Referencie o arquivo lido ali, <file1.files[0]>, e escreva a instrução no prompt: "Summarize this document." O agente recebe o objeto de arquivo, não só o texto, então um modelo com visão pode analisar imagens e páginas digitalizadas diretamente. Outros modelos trabalham a partir do conteúdo em texto do arquivo.

No nosso exemplo o Agent lê <file1.files[0]>, resume e guarda o resumo sob o próprio nome como <agent1.content>.

Bloco Function

Um bloco Function executa código e costuma trabalhar com o texto do arquivo. Leia o arquivo com Get Content e passe o texto extraído, <file1.contents[0]>; o código pode fazer parse, filtrar ou remodelar e devolver o resultado como saída própria. Um Function também pode receber o objeto de arquivo e lê-lo no código com os helpers sim.files, como await sim.files.readText(file) — veja o bloco Function. Use um Function quando o arquivo for texto estruturado (um CSV ou dump JSON) e você quiser processamento exato e determinístico em vez da interpretação de um modelo.

Escrevendo um arquivo

Escrever um arquivo é opcional, e muitos workflows pulam isso. O resumo do agente pode voltar na resposta, ir para o Slack ou ser enviado por e-mail sem nunca virar um arquivo do workspace. Escreva um arquivo quando você precisar de um novo para guardar, baixar ou entregar a uma execução posterior.

O último bloco do nosso exemplo é um File em Write. Dê um nome de arquivo e o conteúdo a salvar:

• fileName: summary.md
• content: <agent1.content>

Write cria um arquivo novo no workspace e devolve id, name, size e url. Se já existir um arquivo com esse nome, Write mantém os dois adicionando um sufixo numérico ao novo. O arquivo salvo cai em arquivos do workspace, pronto para a próxima execução, um download ou outro workflow.

Compondo os passos

Cada bloco referencia o anterior pelo nome, então você compõe só os passos de que a tarefa precisa. Um contrato lido por um Agent que devolve um veredito para no processamento, e uma imagem enviada descrita por um modelo de visão nunca toca Write, enquanto um CSV buscado, limpo por um Function e salvo como arquivo novo usa os três. Ler um arquivo é comum; escrever um só quando o resultado for ele mesmo um arquivo.

Para o schema completo do objeto de arquivo, acesso em base64 e como arquivos se movem em triggers de API e chat, veja Passando arquivos.

Próximos passos