# Executar tarefas de agente recorrentes

Reutilizar acesso aprovado, fazer uma busca por ocorrência programada, e se recuperar sem acidentalmente enviar o mesmo trabalho novamente.

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

<a id="choose"></a>

## Escolha como a tarefa corre

Seu agente anfitrião ou programador OS fornece o tempo. FlashData fornece os dados. Escolha um caminho de execução e teste-o no ambiente que será executado sem vigilância.

| Use | Por.. | Estado a preservar |
| --- | --- | --- |
| CLI | Um agente com acesso terminal, cron, ou um roteiro agendado. | O perfil CLI, o diretório de estado e a execução original ID. |
| MCP | Um host de agente com um servidor FlashData conectado. | Credenciais do anfitrião, registro de ocorrência, trabalho IDs e resultados. |

- [CLI tarefa](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md#input)
- [MCP tarefa](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md#mcp)
- [Construa um briefing diário](https://flashdata.dev/pt/docs/guides/daily-research-briefing/reference.md)

<a id="prepare"></a>

## Verifique o acesso no ambiente programado

Reutilize uma conexão existente com a permissão google_search. Reivindicar acesso temporário antes do uso recorrente. Teste de um novo processo ou sessão programada, não apenas interativo.

### CLI

Use Bash e jq (Git Bash em Windows), sob o usuário OS que salvou a chave. Defina seu perfil e diretório de estado absoluto abaixo. Executar ambos os blocos no mesmo terminal, o corredor reutiliza essas configurações.

A verificação de acesso deve imprimir true. Compare availableCredits com estimatedCredits antes da primeira busca. Esses verificações não enviam uma pergunta.

#### Defina sua conexão salva

```bash
# Use the profile and state directory that already hold your owner key.
export FLASHDATA_PROFILE='research'
export FLASHDATA_STATE_DIR='/absolute/path/to/existing/flashdata-state'
export FLASHDATA_BIN="$(command -v flashdata)"
unset FLASHDATA_API_KEY
```

#### Livre acesso, equilíbrio e verificação de preços

```bash
set -euo pipefail
export FLASHDATA_BIN="${FLASHDATA_BIN:-$(command -v flashdata)}"
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${FLASHDATA_BIN:?Set the absolute path to the FlashData executable}"
profile=${FLASHDATA_PROFILE:-research}
test -d "$FLASHDATA_STATE_DIR" || { echo 'Existing state directory not found.' >&2; exit 1; }
"$FLASHDATA_BIN" --version
jq --version
"$FLASHDATA_BIN" auth status --profile "$profile" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
  jq -e '.ok and .data.accessVerified
    and (.data.identity.identity.recurringAllowed == true)
    and (.data.identity.permittedSources | index("google_search") != null)'
"$FLASHDATA_BIN" account balance --profile "$profile" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
"$FLASHDATA_BIN" account pricing --source google_search --request-count 1 \
  --profile "$profile" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```


### MCP

Faça isso em uma nova sessão agendada. Deixe o hospedeiro reutilizar e atualizar suas credenciais OAuth aprovadas. Ele deve ser capaz de alcançar FlashData sem um login interativo em cada corrida.

#### Livre controle de host

```text
Reutilize a conexão FlashData MCP existente neste ambiente agendado.
Chame get_balance com {}.
Chame get_pricing com {"source":"google_search","request_count":1}.
Relate o saldo e o preço estimado. Não procurem ou criem novos acessos.
```


- [Instale o CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#install)
- [Conectar MCP](https://flashdata.dev/pt/docs/integrations/mcp-clients/reference.md)
- [Alegar acesso ao teste](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#claim)

<a id="input"></a>

## CLI Salvar uma tarefa por ocorrência

Crie a pasta de tarefas abaixo e salve request.json e run-research.sh dentro dela. Mantenha esta pasta separada do diretório de estado credencial existente. Uma data representa uma consulta Google; num define o número de resultados. Dê a um fluxo de trabalho diferente seu próprio prefixo run-ID antes de sua primeira execução.

### Crie a pasta de tarefas

```bash
mkdir -p flashdata-research
cd flashdata-research
```

### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
```


<a id="runner"></a>

### Salve run-research.sh

Crie run-research.sh ao lado de request.json na pasta de tarefas. Copie o script completo abaixo e salve-o antes de executar ou agendar a tarefa.

O script congela a entrada para cada data e mantém um recibo, resultado e arquivo de erro para cada tentativa. Apenas tentativas bem sucedidas publicam result.json e... receipt.json No nível superior da pasta datada. --recurring Verifica o acesso do proprietário, não cria uma programação.

#### run-research.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
slot=${1:?Pass the scheduled date as YYYY-MM-DD}
[[ "$slot" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || exit 2
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${FLASHDATA_BIN:?Set the absolute path to the FlashData executable}"
profile=${FLASHDATA_PROFILE:-research}
cd -- "$(dirname -- "$0")"
dir="runs/$slot"
mkdir -p "$dir"
if [[ -e "$dir/request.json" ]]; then
  cmp -s request.json "$dir/request.json" || {
    echo 'Input changed for this slot. Inspect its saved run.' >&2; exit 1;
  }
else
  (set -C; cat request.json > "$dir/request.json")
fi
attempt=$(mktemp -d "$dir/attempt.XXXXXX")
if ! "$FLASHDATA_BIN" query --input "$dir/request.json" --recurring \
  --run-id "scheduled-research:$slot:Asia-Shanghai" \
  --profile "$profile" --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$attempt/result.json" --timeout 2m --json --non-interactive \
  > "$attempt/receipt.json" 2> "$attempt/error.json"; then
  cat "$attempt/error.json" >&2
  exit 1
fi
jq -e '.ok == true' "$attempt/receipt.json" >/dev/null
jq -e '.source == "google_search" and .status == "done"
  and (.results[0].organic | type == "array")' "$attempt/result.json" >/dev/null
# Publish a stable path only after the query and its receipt both succeed.
cp "$attempt/result.json" "$dir/result.next.json"
mv "$dir/result.next.json" "$dir/result.json"
cp "$attempt/receipt.json" "$dir/receipt.next.json"
mv "$dir/receipt.next.json" "$dir/receipt.json"
jq '{runId, cached, usage}' "$attempt/receipt.json"
printf 'Saved result: %s\n' "$dir/result.json"
```


<a id="slot"></a>

### Corra uma vez, então teste uma nova tentativa de processo

Corra da pasta de tarefas. O primeiro comando envia uma busca. O segundo usa a mesma conta, entrada, perfil e estado para ler o resultado salvo depois de verificar que o acesso ainda é válido.

#### Uma ocorrência, dois processos começam

```bash
# Use the date of the intended occurrence, including on retries.
bash run-research.sh 2026-11-04

# Same account, input, profile and state: reuse the completed run.
bash run-research.sh 2026-11-04
```


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

### Confirme que o resultado foi reutilizado

O segundo recibo deve mostrar cached: true. Seu uso pertence à busca original. Uma matriz orgânica vazia ainda pode ser um resultado bem sucedido.

#### Inspecione o resultado salvo e o recibo

```bash
jq '{ok, runId, cached, usage}' runs/2026-11-04/receipt.json
jq '.results[0].organic | map({title, link})' runs/2026-11-04/result.json
```

#### Segundo recibo · Excerto

```json
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "scheduled-research:2026-11-04:Asia-Shanghai",
  "cached": true
}
```


<a id="files"></a>

### Mantenha os arquivos entre as corridas

| Arquivo | Use |
| --- | --- |
| runs/DATE/request.json | Entrada exata para essa ocorrência, mudando-a faz o corredor parar. |
| runs/DATE/result.json + receipt.json | A última tentativa bem sucedida. Só os consuma depois que o comando sair com sucesso. |
| runs/DATE/attempt.*/ | Resultado, recibo e erro para cada tentativa, incluindo falhas. |
| FLASHDATA_STATE_DIR | Credenciais protegidos e CLI executam registros. Mantenha o mesmo perfil e use OS. |

- [Recupere uma corrida interrompida](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)

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

## MCP: persistir na ocorrência e no trabalho ID

Use este corpo de tarefas com um hospedeiro que mantenha o estado de tarefa durável e permita uma execução ativa por ocorrência. Salve o trabalho de volta ID imediatamente; após um reinício, leia o trabalho aceito em vez de procurar novamente.

### MCP tarefa recorrente · salvar como recurring-task.txt

```text
Use a ocorrência original do programador ID e horário agendado.
Reutilize a conexão FlashData MCP existente e salve o registro de ocorrência.
1. Se esta ocorrência estiver completa, devolva seu resultado salvo sem procurar.
2. Se ele tem um trabalho ID, ligue para get_job com esse job_id para ler o trabalho existente.
3. Se uma submissão começou mas não tem resultado ou trabalho ID, pare para revisão.
4. Para uma nova ocorrência, verifique get_balance e get_pricing para um google_search.
   Continue apenas dentro do orçamento aprovado por tarefa e equilíbrio disponível.
5. Persista em submission_started antes de chamar google_search uma vez com:
   {"query":"battery recycling pilot plant announcements","num":5,"gl":"us","hl":"en","tbs":"qdr:w","mode":"async"}
6. Salve o trabalho de volta ID imediatamente. Leia com get_job até o terminal, pare com a falha.
   Mantenha o ID em intervalos e pare de esperar no prazo do anfitrião.
7. Salve o resultado, fonte URLs e uso, então marque esta ocorrência completa.
Em 401, 403, 402, 429 ou um resultado desconhecido, pare e relate o registro salvo.
Honrar Retry-After. Não crie acesso de substituição ou outra consulta paga.
Mantenha o relatório local, use um destino de entrega somente se configurado separadamente.
```

- [MCP ferramentas](https://flashdata.dev/pt/docs/mcp/reference.md)
- [Leia um trabalho aceito](https://flashdata.dev/pt/docs/mcp/reference.md#jobs)

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

### O que o hospedeiro deve persistir

Um alerta sozinho não pode evitar duplicatas. Chamadas MCP não herdam proteção CLI run-ID. Seu anfitrião deve persistir na ocorrência original, estado de submissão e trabalho ID. Se não puder, use o corredor CLI para a etapa de dados. Este registro de exemplo pertence ao seu anfitrião, não é um pedido MCP.

#### Registro de hospedeiras... ilustrativo

```json
{
  "occurrence": "research:2026-11-04:Asia-Shanghai",
  "state": "accepted",
  "job_id": "<returned job ID>",
  "output": null
}
```


<a id="schedule"></a>

## Agende a tarefa testada

O exemplo abaixo usa OpenClaw em 09:00 Asia/Shanghai. Crie o trabalho desativado, execute o trabalho salvo manualmente, inspecione sua saída, e então habilite-o. Para outro programador, siga a mesma sequência com seus controles de teste.

| Ajustando | Use |
| --- | --- |
| Concurrência | Uma execução ativa para esse fluxo de trabalho, com estado durável. |
| Tempo de corrida | Use o mesmo usuário OS e caminhos absolutos para CLI, pasta de tarefas e estado credencial. Exportações de terminais não são automaticamente herdadas por um Gateway. |
| Repetições | Mantenha a ocorrência original e data marcada, inclusive depois da meia-noite. Um teste manual usa sua data de invocação em Asia/Shanghai. |
| Ocorrências perdidas | Escolha se deve pular ou pôr o papo em dia. Uma busca hoje devolve dados atuais, mesmo que marcados com a data de ontem. |
| Entrega | Salve a região primeiro. Configure uma política de destino e notificação antes de enviar relatórios. |

- [Prepare um servidor ou recipiente](https://flashdata.dev/pt/docs/guides/production-deployment/reference.md)

<a id="cli-task"></a>

### CLI corpo de tarefas para um hospedeiro de agentes

Substitua os placeholders do perfil e do caminho, então salve recurring-task.txt na pasta de tarefas. Use este corpo para execução CLI, ou o corpo MCP acima para execução MCP. Um programador OS direto pode executar o script Bash com essas variáveis de ambiente sem um modelo.

#### recurring-task.txt

```text
Execute a tarefa de pesquisa FlashData aprovada sob o usuário OS que salvou a chave.
Corredor: <caminho absoluto para run-research.sh>
Defina estas variáveis de ambiente para o processo de corredor:
FLASHDATA_BIN* Caminho absoluto para flashdata>
FLASHDATA_PROFILE: <Nome do perfil existente>
FLASHDATA_STATE_DIR: <Relatório de estado absoluto existente>
Mantenha FLASHDATA_API_KEY desligado para reutilizar a credencial salva.
Use a data agendada original em Asia/Shanghai, como YYYY-MM-DD.
Para uma execução manual, guarde sua data de invocação antes da execução.
Correr: bash "<absolute path to run-research.sh>" YYYY-MM-DD
Mantenha essa data em repetições, mesmo depois da meia-noite. Permita uma execução ativa.
Mantenha o mesmo perfil, request.json e diretório de estado.
Apenas leia o result.json datado após as saídas de comando com sucesso.
Relate links de origem, execute ID e use. Mantenha as saídas locais.
No erro, pare e relate o erro salvo. Não comece a substituir o trabalho ou criar um novo acesso.
```


<a id="openclaw-schedule"></a>

### 1. Criar um trabalho OpenClaw deficiente

Use uma Gateway e um agente existente que passou na verificação de acesso. Os comandos abaixo usam OpenClaw 2026.10.10; atualizem clientes mais velhos se --wait não estiver disponível. Na pasta que contém recurring-task.txt, defina OPENCLAW_AGENT_ID para ID daquele agente.

O comando salva openclaw-job.json sem sobrescrever um arquivo existente. Leia e coloque OPENCLAW_JOB_ID para o trabalho devolvido ID. Se a criação perder sua resposta, inspecione a lista de automação. --all --json Antes de criar outro trabalho. --no-deliver Desativa o anúncio automático, o corpo de tarefas também mantém relatórios locais.

#### Bash · cria um trabalho deficiente

```bash
: "${OPENCLAW_AGENT_ID:?Set the existing OpenClaw agent ID}"
test -s recurring-task.txt || exit 1
# Keep the receipt. An existing file blocks accidental recreation.
(
  set -o noclobber
  openclaw automations add --name flashdata-daily-research \
    --agent "$OPENCLAW_AGENT_ID" \
    --cron "0 9 * * *" --tz Asia/Shanghai --exact \
    --session isolated --disabled --no-deliver \
    --message "$(cat recurring-task.txt)" --json > openclaw-job.json
)
```

- [Configuração OpenClaw](https://flashdata.dev/pt/docs/integrations/openclaw/reference.md)
- [OpenClaw referência de agendamento](https://docs.openclaw.ai/cli/cron)

<a id="test-schedule"></a>

### 2. Teste o trabalho salvo antes de permitir

Faça o trabalho salvo uma vez enquanto sua agenda fica desativada. Orçamento para uma pesquisa de teste e custos do modelo, uma ocorrência completa de CLI pode reutilizar seu resultado. Este comando espera até 10 minutos.

Espere completionStatus: sucesso, então verifique o resultado salvo, links de origem e uso. Por... CLI, leia runs/DATE/result.json e... receipt.json- Por quê? MCP, leia a ocorrência salva do anfitrião e o resultado do trabalho. enqueued: true Sozinho significa aceito, não completado.

#### Corra uma vez, guarde o recibo do teste

```bash
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
# Run the saved job once; its schedule stays disabled.
(
  set -o noclobber
  openclaw automations run "$OPENCLAW_JOB_ID" \
    --wait --wait-timeout 10m --json > openclaw-test-run.json
)
```

#### Leia o recibo do teste

```bash
cat openclaw-test-run.json
```


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

### Inspecione um teste cronometrado ou falhou

Um intervalo para esperar, não a tarefa do Gateway. Leia o histórico recente se o recibo estiver vazio. Defina OPENCLAW_RUN_ID para OpenClaw runId a partir do recibo ou histórico, em seguida, inspecione essa execução. Não repita o comando para verificar o progresso.

Esta é a execução do programador ID, não a execução recorrente FlashData ID ou um trabalho MCP ID. Se o agente não conseguiu entrar ou executar a tarefa de dados, mantenha o cronograma desativado e repare esse passo primeiro.

#### Inspecione a mesma execução

```bash
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
cat openclaw-test-run.json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --json

# Set this from the receipt or history; this is OpenClaw's run ID.
: "${OPENCLAW_RUN_ID:?Set the OpenClaw test run ID}"
openclaw automations runs "$OPENCLAW_JOB_ID" \
  --run-id "$OPENCLAW_RUN_ID" --json
```

- [Recupere o passo de dados FlashData](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)

<a id="manage-schedule"></a>

### 3. Activar depois de verificar a saída

Revise o agente salvo, o horário, o fuso horário e o teste completo. Ativar somente após a saída estar correta e o custo recorrente ser aprovado. Desativar depois para futuras invocações, não cancela uma consulta já submetida.

#### Revise o trabalho salvo e teste histórico

```bash
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
openclaw automations show "$OPENCLAW_JOB_ID" --json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --json
```

#### Activar a programação diária

```bash
openclaw automations enable "$OPENCLAW_JOB_ID"
```

#### Pausa para o futuro quando necessário

```bash
openclaw automations disable "$OPENCLAW_JOB_ID"
```


<a id="budget"></a>

## Definir o custo e as regras de falha

| Situação | Ação |
| --- | --- |
| Planejamento de custos | Preço por consulta × ocorrências planejadas. Adicione custos de modelo e host separadamente, contagem de resultados não é contagem de consultas. |
| Saldo da conta compartilhada | Forçar seu orçamento no agendador ou anfitrião. Esses exemplos não impõem um limite de gastos em chave separada. |
| 401 / 403 / 402 | Pausar futuras mensagens. Conserte credenciais, permissão ou equilíbrio, retome com a ocorrência original e o estado salvo. |
| 429 | Respeito Retry-After. Inspecione a corrida CLI ou a ocorrência MCP antes de decidir se uma nova submissão é segura. |
| Resultado desconhecido da submissão | Mantenha o estado salvo e pare. Recupere um trabalho conhecido ID; não crie uma nova corrida ID para contornar a incerteza. |

- [Preço atual](https://flashdata.dev/pt/pricing)
- [Decisões de recuperação](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)

<a id="stop"></a>

## Pare o horário e revogue o acesso separadamente

1. Pause o agendador para parar as futuras invocações.
2. Revogue a conexão do agente, aplicativo OAuth ou chave API no console. A revogação bloqueia o novo uso autenticado, não apaga arquivos exportados.
3. Repita a verificação de acesso livre de um novo processo. Deve falhar após a revogação. CLI logout só remove credenciais locais, não revoga o acesso remoto.

- [Connected apps e agentes](https://flashdata.dev/app/settings/connections)
- [Teclas API](https://flashdata.dev/app/api-keys)
- [Acesse o ciclo de vida](https://flashdata.dev/pt/docs/guides/agent-access/reference.md)
