# Recupere uma integração de agentes

Recupere uma tarefa CLI interrompida ou MCP usando sua execução salva, trabalho ou resultado ID.

Referência canônica: https://flashdata.dev/pt/docs/guides/agent-recovery
2026-11-05 por FlashData

<a id="start"></a>

## Comece com o ID que você salvou

Pause a tarefa ou agenda falhando. Ache o recibo na pasta de tarefas ou no histórico do agente, e siga o caminho correspondente. Esses IDs não são intercambiáveis.

| Você tem | Use |
| --- | --- |
| CLI runId | O CLI segue abaixo, com o perfil original e o diretório do estado. |
| MCP trabalho ID · trabalho.. | get_job na conexão MCP existente. |
| MCP resultado ID · resultado.. | get_result para terminar de ler uma grande resposta. |
| OpenClaw roda ID | OpenClaw executar história, em seguida, o FlashData ID gravado por essa execução. |

- [CLI recuperação](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md#inspect)
- [MCP recuperação](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md#mcp)
- [OpenClaw executar histórico](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md#inspect-test)

<a id="inspect"></a>

## 1. Inspecione a corrida CLI

Abra Bash (Git Bash em Windows) como o usuário original OS, na pasta de saída da sua tarefa. Substitua os três valores abaixo pelos da tarefa original. Mantenha este terminal aberto para os passos 2 e 3. Desativar FLASHDATA_API_KEY permite que o CLI use a chave salva neste perfil.

### Selecione a tarefa existente · este terminal

```bash
# Replace these with the values used by the original task.
export FLASHDATA_PROFILE='research'
export FLASHDATA_STATE_DIR='/absolute/path/to/existing/flashdata-state'
export RUN_ID='scheduled-research:2026-11-04:Asia-Shanghai'
unset FLASHDATA_API_KEY
```

### Inspeção local, sem ligações do API

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${RUN_ID:?Set the run ID from the original receipt}"
flashdata doctor --offline --profile "${FLASHDATA_PROFILE:-research}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata runs show "$RUN_ID" --profile "${FLASHDATA_PROFILE:-research}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```


<a id="run-status"></a>

### Escolha a ação de recuperação

Leia data.status, data.remoteId e data.errorCode no registro de execução.

| Status gravado | O que fazer |
| --- | --- |
| succeeded | Verifique o acesso, então exporte o resultado salvo no passo 3. |
| accepted | Verifique o acesso, e recupere o trabalho aceito no passo 3. |
| uncertain / intent | Mantenha a tarefa pausada. Verifique remoteId, candidateRemoteIds e History antes de decidir se deve submeter algo novamente. |
| failed | Conserte errorCode primeiro. Um registro fracassado é mantido, um substituto é uma nova tarefa e pode usar créditos. |
| partial | Mantenha as saídas disponíveis. Recupere trabalhos conhecidos, para trabalho a granel, inspecione cada fila antes de substituir itens fracassados. |
| run_not_found | Verifique o perfil, o usuário OS e o diretório de estado. Procure recibos salvos ou History se o diário estiver perdido. |

- [Histórico de pedidos abertos](https://flashdata.dev/app/jobs)
- [Recupere os resultados em massa](https://flashdata.dev/pt/docs/guides/bulk/reference.md)

<a id="decide"></a>

## 2. Verifique o acesso da conta CLI

Essas verificações gratuitas requerem acesso à conta original e à origem do API. Resolva qualquer erro de autenticação antes de recuperar os resultados.

### Verifique o acesso e leia o balanço

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile "${FLASHDATA_PROFILE:-research}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata account balance --profile "${FLASHDATA_PROFILE:-research}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```


<a id="access-result"></a>

### Verifique estes campos

Um saldo zero é uma questão de financiamento para um novo trabalho. Não significa que a chave seja inválida.

| auth status campo | Esperado |
| --- | --- |
| data.accessVerified | Verdade, caso contrário, conserte o acesso antes de ler os resultados. |
| data.identity.identity.accountId | A conta que submeteu a tarefa. |
| data.identity.permittedSources | Inclui a fonte usada pela tarefa salva. |
| data.identity.identity.recurringAllowed | Verdade antes de retomar uma tarefa recorrente. |


<a id="account-change"></a>

### A conta mudou, ou eu apenas reivindiquei um teste.

run_account_mismatch significa que a corrida salva pertence a uma conta diferente ou origem API. Reusar o nome do perfil não transfere a execução.

| Situação | Ação |
| --- | --- |
| Conta errada | Verifique a chave do ambiente, perfil selecionado e origens management/data. Restaure a conta antes da recuperação. |
| Chave girada | Use uma chave de substituição para a mesma conta com a permissão de origem necessária. Mantenha o perfil original, diretório de estado e execute ID. |
| teste reivindicado | A conta do proprietário difere da conta temporária. Leia as saídas de teste que você já exportou. Use uma nova corrida ID apenas para uma nova tarefa de proprietário; ela usa o equilíbrio do proprietário. |

- [Substitua uma chave do proprietário](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Teste e vinculação à conta](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#owner-result)

<a id="handoff"></a>

### Retomar uma alegação interrompida

Para uma vinculação aprovada, execute auth finish em seu perfil original dentro da janela de entrega de 24-hora. Ele salva e verifica a chave do proprietário, e então reconhece a instalação. O segundo comando verifica o acesso salvo em um novo processo.

#### Termine a entrega existente

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
# Resume an already approved claim in its original profile.
flashdata auth finish --profile "${FLASHDATA_PROFILE:-research}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive

# A second process checks the saved owner access.
flashdata auth status --profile "${FLASHDATA_PROFILE:-research}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```

- [vinculação expirada ou perda de registro](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#help)
- [Protocolo de autenticação](https://flashdata.dev/auth.md)

<a id="recover"></a>

## 3. Recupere o resultado CLI

Escolha o status salvo do passo 1. Use um nome de arquivo de saída que não existe. Ambos os comandos verificam o acesso e mantêm a execução original; nenhum deles submete uma consulta de substituição.

### Economizei o sucesso

#### Exportar o resultado salvo

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${RUN_ID:?Set the run ID from the original receipt}"
flashdata runs show "$RUN_ID" --result --output recovered.json \
  --profile "${FLASHDATA_PROFILE:-research}" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```


### Aceito um trabalho de sincronia

Um tempo de votação para a espera local. Execute o comando de recuperação novamente para continuar esperando pelo mesmo trabalho.

#### Espere pelo trabalho original

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${RUN_ID:?Set the run ID from the original receipt}"
flashdata runs recover "$RUN_ID" --output recovered.json --timeout 10m \
  --profile "${FLASHDATA_PROFILE:-research}" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```


- [Leia um trabalho remoto conhecido ID](https://flashdata.dev/pt/docs/guides/async-batch/reference.md#job-status)

<a id="verify"></a>

### Confirmar recuperação antes de retomar

1. Verifique o código de saída 0 e ok: true, então abra recovered.json. Exportações de resultados salvos têm cached: true; uso refere-se à execução original.
2. Mantenha a mesma conta, perfil, estado e execute ID quando tentar novamente esta ocorrência. Não apague seu diário ou mude o nome da corrida para forçar uma repetição.
3. Retomar agendamento apenas após o acesso e o resultado são verificados. Dê a cada nova ocorrência programada sua própria execução ID.

- [Corredor de tarefas recorrentes](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md#slot)
- [Guarde resultados para uso posterior](https://flashdata.dev/pt/docs/guides/save-results/reference.md)

<a id="mcp"></a>

## Recuperar uma tarefa MCP

Chamadas MCP não criam registros CLI. Use a conexão MCP existente para a conta que enviou o trabalho. Substitua o trabalho ID neste alerta e envie para seu agente conectado.

### Cole em seu agente conectado

```text
Recupere minha existência FlashData Trabalho: job_REPLACE_WITH_SAVED_ID.
Use a conexão MCP atual. Ligue para get_balance com {} para verificar o acesso,
Então get_job com este job_id.
Se a resposta contém result_id, finish lendo seus pedaços get_result
e combiná-los antes de analisar o JSON.
Para job.status pendente ou processamento, pesquise o mesmo trabalho a cada segundo 5
Por até 2 minutos, em seguida, relatar o status mais recente e parar.
Para completar, salvar saída e sua fonte URLs e uso nesta tarefa.
Em um erro de acesso, trabalho fracassado ou resultado indisponível, pare e relate o ID.
Não execute uma ferramenta de origem, envie um lote ou crie novas credenciais.
```

- [Reconectar um host MCP](https://flashdata.dev/pt/docs/guides/agent-access/reference.md)
- [Referência da ferramenta MCP](https://flashdata.dev/pt/docs/mcp/reference.md)

<a id="mcp-job"></a>

### Leia o trabalho original

Para um cliente MCP personalizado, passe este objeto para callTool após substituir job_id. get_job verifica a conta de trabalho e a permissão de fonte; uma verificação get_balance bem sucedida sozinho não prova acesso a este trabalho.

#### get_job

```json
{
  "name": "get_job",
  "arguments": {
    "job_id": "job_REPLACE_WITH_SAVED_ID"
  }
}
```


<a id="mcp-status"></a>

### Verifique o status do trabalho do MCP

| Resposta | Próxima ação |
| --- | --- |
| job.status: pending / processing | Espere, então leia o mesmo trabalho ID. Um intervalo local não cancela. |
| job.status: completed | Economize saída. Seu uso pertence à consulta original, get_job não se submete ou cobra por uma nova consulta. |
| job.status: failed / isError: true | Leia o erro antes de usar qualquer saída. Não repita a fonte automaticamente. |
| code: result_unavailable | Tente novamente a leitura para uma falha de entrega transitória. Se o resultado salvo expirar, use exportações anteriores. Async JSON resultados são retidos para 24 horas. |


<a id="mcp-chunks"></a>

### Uma grande resposta MCP foi interrompida

Use o result_id salvo com a mesma chave API. Comece com 0 para reconstruir toda a resposta, se você ficar com os pedaços anteriores, use o next_offset exato. Substitua o placeholder antes de chamar esta ferramenta.

1. Anexar cada pedaço em ordem, usando next_offset até que seja null. Analisar o JSON combinado apenas após o último pedaço.
2. O cache dura 10 minutos e mantém as quatro mais novas grandes respostas por chave. Se expirou ou foi despejado e você salvou um trabalho ID, ligue para get_job novamente e leia seus novos pedaços.
3. Uma resposta em tempo real não tem nenhum trabalho de fundo recuperável garantido. Sem um trabalho salvo ID ou exportação, verifique History e pergunte antes de executar uma nova consulta paga.

#### get_result

```json
{
  "name": "get_result",
  "arguments": {
    "result_id": "REPLACE_WITH_RESULT_ID",
    "offset": 0
  }
}
```

- [Cliente MCP com manuseio de pedaços](https://flashdata.dev/pt/docs/guides/mcp-custom-client/reference.md)

<a id="missing-id"></a>

## Eu não tenho nenhum trabalho ID

Verifique os arquivos salvos da tarefa, o histórico de ferramentas do agente e o pedido do proprietário History. request_id é um diagnóstico ID, não um job_id. Se você não pode confirmar se a submissão foi aceita, mantenha a tarefa pausada. Repetir a chamada original pode criar outra carga.

- [Histórico de pedidos abertos](https://flashdata.dev/app/jobs)

<a id="errors"></a>

## Encontre uma correção pelo código de erro

| Sinal | Consertar |
| --- | --- |
| 400 / 422 | Verifique os argumentos contra a ferramenta ou o esquema final. Para pedidos CLI, use a consulta --dry-run antes de qualquer nova tarefa. |
| 401 / 403 | Para CLI, verifique o acesso no passo 2. Para MCP OAuth, deixe o anfitrião atualizar; uma concessão revogada precisa de reconexão aprovada pelo proprietário. Com uma chave API, verifique as permissões secretas e de origem do hospedeiro. |
| 402 | Pare o trabalho até o dono resolver o financiamento. |
| 406 | Use Accept: application/json. Para os terminais de conteúdo suportados, peça Markdown com X-Respond-With: markdown. |
| 429 | Honrar Retry-After e recuperar qualquer trabalho conhecido antes de submeter novamente. Esperar não limpa o registro de execução do CLI. |
| Tempo limite, 5xx, perda de resposta | Recupere trabalhos aceitos. Mantenha os resultados de submissão parados e verifique History. |
| run_id_input_conflict | Restaure a entrada original. Nova entrada precisa de uma nova tarefa deliberada e executar ID. |
| run_account_mismatch | Use a lista de verificação de mudança de conta no passo 2; uma nova corrida ID não é um atalho de recuperação. |
| output_exists | Escolha um novo nome de saída. Mantenha a corrida salva. |
| result_unavailable | Para MCP, verifique o trabalho ou os passos acima. Para CLI, recupere o trabalho remoto aceito. Os resultados expirados precisam de uma exportação mais cedo ou seu próprio armazenamento. |

- [HTTP referência de erro](https://flashdata.dev/pt/docs/errors/reference.md)
- [Reconectar um host MCP](https://flashdata.dev/pt/docs/guides/agent-access/reference.md)

<a id="support"></a>

## Envie um diagnóstico para apoiar

Para CLI, execute este filtro jq no error.json salvo por sua tarefa. Para MCP, código de cópia, http_status e request_id da resposta da ferramenta, além do job_id salvo ou result_id. Inclua a versão do cliente, ponto final, tempo UTC e se a aceitação é confirmada ou desconhecida. Excluir credenciais, cookies e assinatura URLs.

### Selecione os campos de diagnóstico. Somente local

```bash
# Read a saved CLI error envelope; no network request.
jq '{ok, runId, error: (.error | {
  code, httpStatus, retryAfter, runId, remoteId
})}' error.json
```

- [Falar com o suporte](https://flashdata.dev/pt/contact)
