Pular para o conteúdo principal

Visão geral

Um artefato é um arquivo nomeado que uma crew, um agent ou um flow produz: um relatório HTML, um documento markdown, um gráfico, um PDF ou um CSV. Cada artefato tem um identifier. Salvar o mesmo identifier novamente na mesma execução cria uma nova versão (v1, v2, …). Localmente, os artefatos são gravados em disco. No CrewAI AMP, eles aparecem ao lado da execução, onde as pessoas podem visualizá-los, baixá-los e compartilhá-los. Os artefatos são opcionais. Você pode salvar a saída de uma task ou de um agent, deixar os agents salvarem arquivos com uma tool ou salvar a partir do seu próprio código.

Salvar a saída de uma task ou de um agent

Defina artifact em uma task. Quando a task termina, a saída final é salva como artefato. Não há chamada de tool nem tokens extras, então o modelo não pode esquecer de salvar.
Em uma crew JSON, adicione à task em crew.jsonc:

Deixar o CrewAI dar o nome

Passe artifact=True para não precisar informar os detalhes. O CrewAI os preenche:
  • identifier e title vêm do nome da task (ou da sua descrição). Dentro de um flow, vêm do nome do método do flow. Caso contrário, vêm do role do agent.
  • kind vem da saída: html se começar com <!doctype html ou <html, svg se começar com <svg, json se for um objeto ou uma lista JSON, e markdown para qualquer outra coisa.
O nome continua o mesmo quando a mesma task ou o mesmo método de flow roda de novo, então uma nova execução cria a próxima versão, e não um novo artefato.

Agents individuais

Agent.kickoff aceita o mesmo argumento artifact, como um Artifact ou True:
kickoff_async e akickoff também aceitam.

Flows declarativos

Em uma declaração de flow, defina artifact em with em um passo call: agent:
artifact: true dá ao artefato o nome do método, aqui write-report. Use um objeto, como {identifier: weekly-report, title: Weekly report, kind: html}, para definir os detalhes você mesmo. Para entregar ao agent um artefato que a execução salvou antes, liste-o em input_files. Cada entrada é uma referência, carregada quando o passo é executado:
Sem version, a versão mais recente é usada. Se o artefato não existir, o passo falha antes de o agent ser executado. Arquivos de entrada exigem crewai[file-processing].

Salvar um arquivo que o agent grava

Para um gráfico, um PDF ou qualquer outro arquivo que as tools do agent gravam em disco, defina file_path com o local onde o arquivo vai ficar. O CrewAI salva esse arquivo no lugar da saída em texto. Os tipos image, pdf e file exigem file_path.
  • Diga ao agent onde gravar o arquivo, por exemplo na descrição da task.
  • Em uma task, os {placeholders} em file_path são preenchidos com os inputs do kickoff, como em output_file. Em uma declaração de flow, use expressões ${...}, como output/${state.quarter}.png.
  • O arquivo deve estar dentro do diretório de trabalho. Caminhos fora dele são recusados, então grave gráficos e PDFs no diretório do projeto.

Usar o artefato salvo

A versão salva fica em artifact na saída, então um callback, um passo posterior do flow ou o seu próprio código pode enviar o link adiante:
Em uma declaração de flow, leia com ${outputs.write_report.artifact.url}.

Deixar os agents salvarem artefatos

Defina artifacts=True em uma crew para dar a todos os agents uma tool save_artifact, ou em um agent para dar a tool apenas a ele.
A tool recebe identifier, title, kind e content (texto) ou file_path (um arquivo criado pelo agent, como um PNG de gráfico). Ela retorna JSON:
Uma task posterior pode usar a url, por exemplo para publicá-la no Slack ou anexá-la a um e-mail.

Salvar a partir do código

Chame save_artifact de qualquer código Python, como um passo de flow. Nenhum agent é necessário.
Passe content (um str ou bytes) ou file_path, não ambos. A função retorna um SavedArtifact com id, identifier, title, kind, version, content_type, size, url e share_url.

Ler um artefato salvo

Chame load_artifact para ler de volta um artefato que a execução salvou. A função retorna os bytes da versão mais recente, ou da versão que você pedir:
Isso é mais importante em um flow que pausa para feedback humano. O flow pode ser retomado depois em outra máquina, onde os arquivos gravados antes da pausa não existem mais, mas seus artefatos são mantidos. A execução retomada lê o relatório de volta, revisa e salva a próxima versão.
  • load_artifact lê da execução atual, a mesma que um flow retomado continua.
  • Se nenhum artefato ou versão corresponder, a função lança ArtifactNotFoundError.

Identifiers e versões

  • identifier deve corresponder a [a-z0-9][a-z0-9_.-]{0,63}, por exemplo q3-report.
  • Um artefato pertence a uma execução. Crews dentro de um flow compartilham a execução do flow, então todos os seus artefatos ficam agrupados.
  • Salvar o mesmo identifier novamente na execução cria a próxima versão. Isso se encaixa em flows com humano no loop que regeneram um relatório após feedback.

Tipos

Onde os artefatos são armazenados

Localmente, os artefatos vão para:
url é uma URL file:// e share_url fica vazio. No CrewAI AMP, a plataforma registra seu próprio store na inicialização, então o mesmo código envia os artefatos para a execução. Nada muda na sua crew.

Falhas

Salvar um artefato nunca faz a execução falhar:
  • A tool save_artifact retorna o texto do erro para o agent.
  • Task(artifact=...) e kickoff(artifact=...) registram um aviso, e a execução é concluída mesmo assim. Isso inclui um file_path ausente.
  • Chamar save_artifact no seu próprio código lança o erro, para que você decida o que fazer.

Eventos

Cada salvamento emite ArtifactCreatedEvent no event bus, com id, identifier, version, title, kind, content_type, size e url.
Veja Event Listeners.

Stores personalizados

Para enviar artefatos para outro lugar, crie uma subclasse de ArtifactStore e registre-a antes do kickoff:
Se o seu store repete uploads, envie o mesmo artifact_id em cada tentativa para que o destino possa descartar duplicatas. load é opcional: sem ele, load_artifact lança NotImplementedError.