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 dele, passar um arquivo para um block ou uma ferramenta que precisa de um (anexar um PDF a um e-mail, enviar uma imagem para um modelo de visão), ou produzir um novo arquivo e salvá-lo. O block File é como um arquivo entra ou sai de um workflow; o trabalho no meio fica com o block que a tarefa exigir.

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

O block File

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

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

Lendo um arquivo

No nosso exemplo, o primeiro block File está configurado como Read, com report.pdf escolhido no seletor de arquivos. Quando executa, ele produz files: uma lista de objetos de arquivo, um por arquivo lido. O primeiro é <file1.files[0]>.

Quando o passo seguinte precisa do texto do arquivo, e não do arquivo em si, use Get Content: ele extrai o texto e produz contents, um array com uma string por arquivo, lido como <file1.contents[0]>.

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

{
  "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 block aceita um arquivo ou um valor, o workflow builder lista as saídas disponíveis e você escolhe a que quer. O modo Read também aceita um ID de arquivo diretamente 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 block de processamento lê essa saída pelo nome. Dois blocks fazem isso, e cada um consome o arquivo de forma diferente.

Block Agent

Um block Agent tem uma entrada Files. Referencie ali o arquivo lido, <file1.files[0]>, e escreva a instrução no prompt: "Summarize this document." O agente recebe o objeto de arquivo, não apenas o texto dele, então um modelo com capacidade de 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 o conteúdo e guarda o resumo sob o próprio nome, como <agent1.content>.

Block Function

Um block Function executa código e normalmente trabalha com o texto do arquivo. Leia o arquivo com Get Content e passe o texto extraído, <file1.contents[0]>; o código pode processar, filtrar ou remodelar esse texto e retornar o resultado como sua própria saída. Uma Function também pode receber o objeto de arquivo em si e lê-lo em código com os helpers studio.files, como await studio.files.readText(file) — veja o block Function para esses casos. Use uma Function quando o arquivo é texto estruturado (um CSV ou um dump JSON) e você quer processamento exato e determinístico em vez da interpretação de um modelo.

Gravando um arquivo

Gravar um arquivo é opcional, e muitos workflows nem fazem isso. O resumo do agente pode ser devolvido na resposta, postado no Slack ou enviado por e-mail como está, sem nunca se tornar um arquivo do workspace. Grave um arquivo quando você realmente precisa de um novo para guardar, baixar ou entregar a uma execução posterior.

O último block do nosso exemplo é um block File configurado como Write. Dê a ele um nome de arquivo e o conteúdo a salvar:

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

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

Compondo os passos

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

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

Próximos passos