mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-07 16:09:30 +00:00
390 lines
13 KiB
Plaintext
390 lines
13 KiB
Plaintext
---
|
|
title: Checkpointing
|
|
description: Salve automaticamente o estado de execucao para que crews, flows e agentes possam retomar apos falhas.
|
|
icon: floppy-disk
|
|
mode: "wide"
|
|
---
|
|
|
|
O checkpointing salva um snapshot do estado de execucao durante uma execucao para que uma crew, flow ou agente possa retomar apos uma falha ou ser bifurcado em uma branch alternativa.
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Explicacao" icon="lightbulb" href="#explicacao">
|
|
Como o checkpointing funciona: eventos, armazenamento e heranca.
|
|
</Card>
|
|
<Card title="Tutorial" icon="graduation-cap" href="#tutorial-retomar-uma-crew-com-falha">
|
|
Um passo a passo de 5 minutos: executar, interromper, retomar.
|
|
</Card>
|
|
<Card title="Guias de uso" icon="screwdriver-wrench" href="#guias-de-uso">
|
|
Receitas focadas em tarefas para fluxos comuns.
|
|
</Card>
|
|
<Card title="Referencia" icon="book" href="#referencia">
|
|
`CheckpointConfig`, eventos, provedores e CLI.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## Explicacao
|
|
|
|
### O que e um checkpoint
|
|
|
|
Um checkpoint e um snapshot serializado do `RuntimeState` gravado em um ponto da execucao. Ele registra quais tarefas foram concluidas, suas saidas, os inputs atuais e um ID de linhagem que identifica a execucao.
|
|
|
|
Ao restaurar a partir de um checkpoint, o CrewAI reconstroi esse estado, pula o trabalho ja concluido e continua. Ao fazer fork, o CrewAI restaura o estado sob uma nova linhagem para que a nova branch e a execucao original nao se sobreponham.
|
|
|
|
### Quando os checkpoints sao gravados
|
|
|
|
O checkpointing e orientado a eventos. O runtime se inscreve nos eventos selecionados em `on_events` e grava um checkpoint sempre que um e disparado. O padrao `task_completed` produz um checkpoint por tarefa finalizada — um equilibrio razoavel entre granularidade e uso de disco. Eventos de alta frequencia como `llm_call_completed` estao disponiveis para recuperacao mais granular, mas gravam muito mais arquivos.
|
|
|
|
### Armazenamento
|
|
|
|
Dois provedores acompanham o CrewAI:
|
|
|
|
- `JsonProvider` grava um arquivo por checkpoint. Legivel e facil de inspecionar.
|
|
- `SqliteProvider` grava em um unico banco SQLite. Melhor para checkpointing de alta frequencia.
|
|
|
|
Ambos removem os checkpoints mais antigos quando `max_checkpoints` esta definido.
|
|
|
|
<Note>
|
|
As gravacoes de checkpoint sao best-effort. Um checkpoint que falha e registrado em log, mas nao interrompe a execucao.
|
|
</Note>
|
|
|
|
### Modelo de heranca
|
|
|
|
`Crew`, `Flow` e `Agent` aceitam um argumento `checkpoint`. Filhos herdam do pai a menos que definam seu proprio valor ou passem `False` para desativar. Ative o checkpointing uma vez na crew e todos os agentes participam, ou exclua um agente seletivamente.
|
|
|
|
## Tutorial: Retomar uma crew com falha
|
|
|
|
Este passo a passo leva cerca de 5 minutos. Voce executara uma crew de duas tarefas, a interrompera no meio e a retomara a partir do checkpoint salvo.
|
|
|
|
<Steps>
|
|
<Step title="Crie a crew com checkpointing ativado">
|
|
```python
|
|
from crewai import Agent, Crew, Task
|
|
|
|
researcher = Agent(role="Researcher", goal="Research", backstory="Expert")
|
|
writer = Agent(role="Writer", goal="Write", backstory="Expert")
|
|
|
|
crew = Crew(
|
|
agents=[researcher, writer],
|
|
tasks=[
|
|
Task(description="Research AI trends", agent=researcher, expected_output="bullets"),
|
|
Task(description="Write a summary", agent=writer, expected_output="paragraph"),
|
|
],
|
|
checkpoint=True,
|
|
)
|
|
```
|
|
</Step>
|
|
<Step title="Execute e interrompa apos a primeira tarefa">
|
|
```python
|
|
result = crew.kickoff()
|
|
```
|
|
|
|
Pressione `Ctrl+C` apos a primeira tarefa concluir. Em `./.checkpoints/`, um arquivo `<timestamp>_<uuid>.json` e o checkpoint.
|
|
</Step>
|
|
<Step title="Retome a partir do checkpoint">
|
|
```python
|
|
from crewai import CheckpointConfig
|
|
|
|
result = crew.kickoff(
|
|
from_checkpoint=CheckpointConfig(
|
|
restore_from="./.checkpoints/<timestamp>_<uuid>.json",
|
|
),
|
|
)
|
|
```
|
|
|
|
A tarefa de pesquisa e pulada, o escritor executa contra a saida de pesquisa salva e a crew finaliza.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Guias de uso
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Ativar checkpointing com padroes" icon="play">
|
|
```python
|
|
crew = Crew(agents=[...], tasks=[...], checkpoint=True)
|
|
```
|
|
|
|
Grava em `./.checkpoints/` em cada `task_completed`.
|
|
</Accordion>
|
|
|
|
<Accordion title="Personalizar armazenamento e frequencia" icon="sliders">
|
|
```python
|
|
from crewai import Crew, CheckpointConfig
|
|
|
|
crew = Crew(
|
|
agents=[...],
|
|
tasks=[...],
|
|
checkpoint=CheckpointConfig(
|
|
location="./my_checkpoints",
|
|
on_events=["task_completed", "crew_kickoff_completed"],
|
|
max_checkpoints=5,
|
|
),
|
|
)
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Escolher um provedor de armazenamento" icon="database">
|
|
<CodeGroup>
|
|
```python JsonProvider
|
|
from crewai import Crew, CheckpointConfig
|
|
from crewai.state import JsonProvider
|
|
|
|
crew = Crew(
|
|
agents=[...],
|
|
tasks=[...],
|
|
checkpoint=CheckpointConfig(
|
|
location="./my_checkpoints",
|
|
provider=JsonProvider(),
|
|
max_checkpoints=5,
|
|
),
|
|
)
|
|
```
|
|
```python SqliteProvider
|
|
from crewai import Crew, CheckpointConfig
|
|
from crewai.state import SqliteProvider
|
|
|
|
crew = Crew(
|
|
agents=[...],
|
|
tasks=[...],
|
|
checkpoint=CheckpointConfig(
|
|
location="./.checkpoints.db",
|
|
provider=SqliteProvider(),
|
|
max_checkpoints=50,
|
|
),
|
|
)
|
|
```
|
|
</CodeGroup>
|
|
|
|
<Tip>
|
|
O SQLite ativa o modo journal WAL para leituras concorrentes. Prefira-o para checkpointing de alta frequencia.
|
|
</Tip>
|
|
</Accordion>
|
|
|
|
<Accordion title="Desativar um agente especifico" icon="user-slash">
|
|
```python
|
|
crew = Crew(
|
|
agents=[
|
|
Agent(role="Researcher", ...),
|
|
Agent(role="Writer", ..., checkpoint=False),
|
|
],
|
|
tasks=[...],
|
|
checkpoint=True,
|
|
)
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Retomar via classmethod" icon="rotate-left">
|
|
```python
|
|
config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
|
|
crew = Crew.from_checkpoint(config)
|
|
result = crew.kickoff()
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Fazer fork em uma nova branch" icon="code-branch">
|
|
`fork()` restaura um checkpoint sob uma nova linhagem para que a nova execucao nao colida com a original.
|
|
|
|
```python
|
|
config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
|
|
crew = Crew.fork(config, branch="experiment-a")
|
|
result = crew.kickoff(inputs={"strategy": "aggressive"})
|
|
```
|
|
|
|
O label `branch` e opcional; um e gerado se omitido.
|
|
</Accordion>
|
|
|
|
<Accordion title="Checkpoint em Crew, Flow ou Agent" icon="cubes">
|
|
<Tabs>
|
|
<Tab title="Crew">
|
|
```python
|
|
crew = Crew(
|
|
agents=[researcher, writer],
|
|
tasks=[research_task, write_task, review_task],
|
|
checkpoint=CheckpointConfig(location="./crew_cp"),
|
|
)
|
|
```
|
|
|
|
Gatilho padrao: `task_completed`.
|
|
</Tab>
|
|
<Tab title="Flow">
|
|
```python
|
|
from crewai.flow.flow import Flow, start, listen
|
|
from crewai import CheckpointConfig
|
|
|
|
class MyFlow(Flow):
|
|
@start()
|
|
def step_one(self):
|
|
return "data"
|
|
|
|
@listen(step_one)
|
|
def step_two(self, data):
|
|
return process(data)
|
|
|
|
flow = MyFlow(
|
|
checkpoint=CheckpointConfig(
|
|
location="./flow_cp",
|
|
on_events=["method_execution_finished"],
|
|
),
|
|
)
|
|
result = flow.kickoff()
|
|
|
|
config = CheckpointConfig(restore_from="./flow_cp/<file>.json")
|
|
flow = MyFlow.from_checkpoint(config)
|
|
result = flow.kickoff()
|
|
```
|
|
</Tab>
|
|
<Tab title="Agent">
|
|
```python
|
|
agent = Agent(
|
|
role="Researcher",
|
|
goal="Research topics",
|
|
backstory="Expert researcher",
|
|
checkpoint=CheckpointConfig(
|
|
location="./agent_cp",
|
|
on_events=["lite_agent_execution_completed"],
|
|
),
|
|
)
|
|
result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}])
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
</Accordion>
|
|
|
|
<Accordion title="Gravar um checkpoint manualmente" icon="code">
|
|
Registre um handler em qualquer evento e chame `state.checkpoint()`.
|
|
|
|
<CodeGroup>
|
|
```python Sync
|
|
from crewai.events.event_bus import crewai_event_bus
|
|
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
|
|
|
@crewai_event_bus.on(LLMCallCompletedEvent)
|
|
def on_llm_done(source, event, state):
|
|
path = state.checkpoint("./my_checkpoints")
|
|
print(f"Checkpoint salvo: {path}")
|
|
```
|
|
```python Async
|
|
from crewai.events.event_bus import crewai_event_bus
|
|
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
|
|
|
@crewai_event_bus.on(LLMCallCompletedEvent)
|
|
async def on_llm_done_async(source, event, state):
|
|
path = await state.acheckpoint("./my_checkpoints")
|
|
print(f"Checkpoint salvo: {path}")
|
|
```
|
|
</CodeGroup>
|
|
|
|
Um argumento `state` e fornecido automaticamente quando o handler recebe tres parametros. Veja [Event Listeners](/pt-BR/concepts/event-listener) para o catalogo completo de eventos.
|
|
</Accordion>
|
|
|
|
<Accordion title="Navegar, retomar e fazer fork pela CLI" icon="terminal">
|
|
```bash
|
|
crewai checkpoint # detecta automaticamente .checkpoints/ ou .checkpoints.db
|
|
crewai checkpoint --location ./my_checkpoints
|
|
crewai checkpoint --location ./.checkpoints.db
|
|
```
|
|
|
|
<Frame>
|
|
<img src="/images/checkpointing.png" alt="Checkpoint TUI" />
|
|
</Frame>
|
|
|
|
O painel esquerdo agrupa checkpoints por branch; forks aninham sob seu pai. Selecionar um checkpoint mostra seus metadados, estado da entidade e progresso das tarefas. **Resume** continua a execucao; **Fork** inicia uma nova branch.
|
|
|
|
O painel de detalhes expoe duas areas editaveis:
|
|
|
|
- **Inputs** — os inputs originais do kickoff, preenchidos e editaveis.
|
|
- **Saidas das tarefas** — saidas das tarefas concluidas. Editar uma saida e pressionar **Fork** invalida tarefas downstream para que sejam reexecutadas com o contexto modificado.
|
|
|
|
<Tip>
|
|
Util para exploracao de cenarios: fork, ajuste, observe.
|
|
</Tip>
|
|
</Accordion>
|
|
|
|
<Accordion title="Inspecionar checkpoints sem a TUI" icon="magnifying-glass">
|
|
```bash
|
|
crewai checkpoint list ./my_checkpoints
|
|
crewai checkpoint info ./my_checkpoints/<file>.json
|
|
crewai checkpoint info ./.checkpoints.db
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Referencia
|
|
|
|
### `CheckpointConfig`
|
|
|
|
<ParamField path="location" type="str" default='"./.checkpoints"'>
|
|
Destino do armazenamento. Diretorio para `JsonProvider`, caminho de arquivo de banco para `SqliteProvider`.
|
|
</ParamField>
|
|
|
|
<ParamField path="on_events" type="list[str]" default='["task_completed"]'>
|
|
Tipos de evento que disparam um checkpoint. Veja [tipos de evento](#tipos-de-evento).
|
|
</ParamField>
|
|
|
|
<ParamField path="provider" type="BaseProvider" default="JsonProvider()">
|
|
Backend de armazenamento. `JsonProvider` ou `SqliteProvider`.
|
|
</ParamField>
|
|
|
|
<ParamField path="max_checkpoints" type="int | None" default="None">
|
|
Maximo de checkpoints a reter. Os mais antigos sao removidos apos cada gravacao.
|
|
</ParamField>
|
|
|
|
<ParamField path="restore_from" type="Path | str | None" default="None">
|
|
Checkpoint a restaurar quando passado via `from_checkpoint`.
|
|
</ParamField>
|
|
|
|
### Valores do campo `checkpoint`
|
|
|
|
Aceito por `Crew`, `Flow` e `Agent`.
|
|
|
|
<ParamField path="None" type="padrao">
|
|
Herda do pai.
|
|
</ParamField>
|
|
|
|
<ParamField path="True" type="bool">
|
|
Ativa com padroes.
|
|
</ParamField>
|
|
|
|
<ParamField path="False" type="bool">
|
|
Desativacao explicita. Interrompe a heranca.
|
|
</ParamField>
|
|
|
|
<ParamField path="CheckpointConfig(...)" type="CheckpointConfig">
|
|
Configuracao personalizada.
|
|
</ParamField>
|
|
|
|
### Tipos de evento
|
|
|
|
Valores comuns para `on_events`:
|
|
|
|
| Caso de uso | Eventos |
|
|
|:------------|:--------|
|
|
| Apos cada tarefa | `["task_completed"]` |
|
|
| Apos cada metodo do flow | `["method_execution_finished"]` |
|
|
| Apos execucao do agente | `["agent_execution_completed"]`, `["lite_agent_execution_completed"]` |
|
|
| Apenas na conclusao da crew | `["crew_kickoff_completed"]` |
|
|
| Apos cada chamada LLM | `["llm_call_completed"]` |
|
|
| Tudo | `["*"]` |
|
|
|
|
<Warning>
|
|
`["*"]` e eventos de alta frequencia como `llm_call_completed` gravam muitos checkpoints e podem degradar o desempenho. Combine com `max_checkpoints`.
|
|
</Warning>
|
|
|
|
### Provedores de armazenamento
|
|
|
|
<ParamField path="JsonProvider" type="provider">
|
|
Um arquivo por checkpoint, nomeado `<timestamp>_<uuid>.json` dentro de `location`.
|
|
</ParamField>
|
|
|
|
<ParamField path="SqliteProvider" type="provider">
|
|
Arquivo de banco unico em `location` com journaling WAL.
|
|
</ParamField>
|
|
|
|
### CLI
|
|
|
|
| Comando | Proposito |
|
|
|:--------|:----------|
|
|
| `crewai checkpoint` | Inicia a TUI; detecta o armazenamento automaticamente. |
|
|
| `crewai checkpoint --location <path>` | Inicia a TUI em uma localizacao especifica. |
|
|
| `crewai checkpoint list <path>` | Lista checkpoints. |
|
|
| `crewai checkpoint info <path>` | Inspeciona um arquivo de checkpoint ou a entrada mais recente em um banco SQLite. |
|