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 umidentifier. 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
Definaartifact 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.
crew.jsonc:
Deixar o CrewAI dar o nome
Passeartifact=True para não precisar informar os detalhes. O CrewAI os preenche:
identifieretitlevê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.kindvem da saída:htmlse começar com<!doctype htmlou<html,svgse começar com<svg,jsonse for um objeto ou uma lista JSON, emarkdownpara qualquer outra coisa.
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, definaartifact 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:
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, definafile_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}emfile_pathsão preenchidos com os inputs do kickoff, como emoutput_file. Em uma declaração de flow, use expressões${...}, comooutput/${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 emartifact na saída, então um callback, um passo posterior do flow ou o seu próprio código pode enviar o link adiante:
${outputs.write_report.artifact.url}.
Deixar os agents salvarem artefatos
Definaartifacts=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.
identifier, title, kind e content (texto) ou file_path (um arquivo criado pelo agent, como um PNG de gráfico). Ela retorna JSON:
url, por exemplo para publicá-la no Slack ou anexá-la a um e-mail.
Salvar a partir do código
Chamesave_artifact de qualquer código Python, como um passo de flow. Nenhum agent é necessário.
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
Chameload_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:
load_artifactlê 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
identifierdeve corresponder a[a-z0-9][a-z0-9_.-]{0,63}, por exemploq3-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_artifactretorna o texto do erro para o agent. Task(artifact=...)ekickoff(artifact=...)registram um aviso, e a execução é concluída mesmo assim. Isso inclui umfile_pathausente.- Chamar
save_artifactno seu próprio código lança o erro, para que você decida o que fazer.
Eventos
Cada salvamento emiteArtifactCreatedEvent no event bus, com id, identifier, version, title, kind, content_type, size e url.
Stores personalizados
Para enviar artefatos para outro lugar, crie uma subclasse deArtifactStore e registre-a antes do kickoff:
artifact_id em cada tentativa para que o destino possa descartar duplicatas. load é opcional: sem ele, load_artifact lança NotImplementedError.