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

# Artefatos

> Salve relatórios, gráficos, PDFs e outros arquivos de uma execução para que as pessoas possam visualizá-los, baixá-los e compartilhá-los.

## 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.

```python theme={null}
from crewai import Artifact, Task

report = Task(
    description="Write the Q3 report as HTML",
    expected_output="A full HTML page",
    agent=analyst,
    artifact=Artifact(identifier="q3-report", title="Q3 report", kind="html"),
)
```

Em uma crew JSON, adicione à task em `crew.jsonc`:

```jsonc theme={null}
"artifact": {"identifier": "q3-report", "title": "Q3 report", "kind": "html"}
```

### 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.

```python theme={null}
report = Task(name="Q3 report", description="...", expected_output="...", artifact=True)
# saved as identifier "q3-report", title "Q3 report"
```

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`:

```python theme={null}
result = analyst.kickoff(
    "Write the Q3 report as HTML",
    artifact=Artifact(identifier="q3-report", title="Q3 report", kind="html"),
)
```

`kickoff_async` e `akickoff` também aceitam.

### Flows declarativos

Em uma declaração de flow, defina `artifact` em `with` em um passo `call: agent`:

```yaml theme={null}
methods:
  write_report:
    start: true
    do:
      call: agent
      with:
        role: Analyst
        goal: Write the weekly report as a full HTML page
        backstory: Writes clear reports for executives.
        input: "Weekly report on ${state.topic}"
        artifact: true
```

`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:

```yaml theme={null}
revise_report:
  listen: needs_changes
  do:
    call: agent
    with:
      role: Analyst
      goal: Revise the weekly report from the reviewer's feedback
      backstory: Writes clear reports for executives.
      input: Apply the reviewer's feedback to the attached report.
      input_files:
        current_report: {artifact: write-report}
        first_draft: {artifact: write-report, version: 1}
      artifact: true
```

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`.

```python theme={null}
chart = Task(
    description="Draw the {quarter} sales chart and save it to output/{quarter}.png",
    expected_output="A short summary of the chart",
    agent=designer,
    artifact=Artifact(
        identifier="sales-chart",
        title="Sales chart",
        kind="image",
        file_path="output/{quarter}.png",
    ),
)
```

* 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:

```python theme={null}
output = report.execute_sync()
print(output.artifact.url)

result = analyst.kickoff("...", artifact=True)
print(result.artifact.url)
```

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.

```python theme={null}
from crewai import Agent, Crew

crew = Crew(agents=[analyst, writer], tasks=[...], artifacts=True)
# or
analyst = Agent(role="Analyst", goal="...", backstory="...", artifacts=True)
```

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:

```json theme={null}
{"id": "0b9e6c1e-...", "identifier": "q3-report", "version": 1, "url": "file:///.../v1.html", "share_url": null}
```

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.

```python theme={null}
from crewai import Artifact, save_artifact
from crewai.flow import Flow, listen, start

class ReportFlow(Flow):
    @start()
    def write(self):
        return "# Weekly report\n..."

    @listen(write)
    def publish(self, report: str):
        saved = save_artifact(
            Artifact(identifier="weekly-report", title="Weekly report", kind="markdown"),
            content=report,
        )
        return saved.url
```

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:

```python theme={null}
from crewai import Artifact, load_artifact, save_artifact

report = Artifact(identifier="board-report", title="Board report", kind="html")
save_artifact(report, content="<h1>Draft</h1>")
save_artifact(report, content="<h1>Revised</h1>")

latest = load_artifact("board-report")              # b"<h1>Revised</h1>"
first = load_artifact("board-report", version=1)    # b"<h1>Draft</h1>"
```

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

| Kind | Salvo como | Observações |
| :- | :- | :- |
| `markdown` | `.md` | |
| `html` | `.html` | Renderizado em sandbox no AMP |
| `svg` | `.svg` | |
| `json` | `.json` | |
| `a2ui` | `.json` | Payload A2UI |
| `text` | `.txt` | |
| `csv` | `.csv` | |
| `image` | a extensão do arquivo | Requer `file_path`. O AMP aceita PNG, JPEG, GIF e WebP |
| `pdf` | `.pdf` | Requer `file_path` em uma task ou agent |
| `file` | a extensão do arquivo | Requer `file_path`. Apenas download |

## Onde os artefatos são armazenados

Localmente, os artefatos vão para:

```
./artifacts/<run id>/<identifier>/v<N>.<ext>
```

`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`.

```python theme={null}
from crewai.events import ArtifactCreatedEvent, BaseEventListener

class ArtifactLogger(BaseEventListener):
    def setup_listeners(self, crewai_event_bus):
        @crewai_event_bus.on(ArtifactCreatedEvent)
        def on_artifact(source, event):
            print(f"Saved {event.identifier} v{event.version}: {event.url}")

ArtifactLogger()
```

Veja [Event Listeners](https://docs.crewai.com/pt-BR/concepts/event-listener.md).

## Stores personalizados

Para enviar artefatos para outro lugar, crie uma subclasse de `ArtifactStore` e registre-a antes do kickoff:

```python theme={null}
from crewai.artifacts import ArtifactStore, SavedArtifact, set_artifact_store

class S3ArtifactStore(ArtifactStore):
    def save(self, artifact_id, execution_id, artifact, data, extension, content_type):
        key = f"{execution_id}/{artifact.identifier}/{artifact_id}.{extension}"
        url = upload_to_s3(key, data, content_type)  # your code
        return SavedArtifact(
            **artifact.model_dump(),
            id=artifact_id,
            version=next_version(execution_id, artifact.identifier),  # your code
            content_type=content_type,
            size=len(data),
            url=url,
        )

    def load(self, execution_id, identifier, version=None):
        return download_from_s3(execution_id, identifier, version)  # your code

set_artifact_store(S3ArtifactStore())
```

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`.


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