# Teste para agentes e vinculação

Tente uma busca Google antes de se inscrever, e conecte uma conta do proprietário para continuar usando o mesmo perfil CLI.

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

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

## 1. Verifique o acesso existente

Faça esta verificação gratuita no ambiente do seu agente. Se data.accessVerified é true e Google Search é permitido, reutilize esse acesso e pule para o passo 3. Sem nenhum perfil salvo, continue a passo 2. Retomar o acesso pendente ou bloqueado usando a seção de recuperação abaixo.

### Verifique este perfil

```bash
flashdata auth status --json --non-interactive
```

- [Instale CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#install)
- [Já tem uma chave?](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#existing)
- [Recupere o acesso](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#help)

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

### Mantenha o mesmo perfil

Relatórios de acesso data.accessVerified: true, access: ready em data.identity.identity, e google_search em data.identity.permittedSources.

Esses comandos usam o perfil padrão e funcionam em Bash ou PowerShell. Para um perfil ou diretório de estado personalizado existente, adicione o mesmo nome --profile e --state-dir ABSOLUTE_PATH a todos os comandos, incluindo aqueles em um novo terminal.

FLASHDATA_API_KEY tem prioridade sobre a chave salva. Deixe essa variável sem definir ao testar o acesso temporário e a transferência de credenciais deste perfil. Use o mesmo usuário do sistema e preserve o diretório privado de estado; ele contém as credenciais, a prova de registro e o histórico de execuções.

Inspecione credentialProtection em auth status. Windows usa DPAPI, macOS usa Keychain, e Linux sem cabeça pode usar um arquivo credencial somente para proprietários. Uma loja OS disponível pode ser necessária com --credential-store os.


<a id="existing"></a>

### Use uma chave de proprietário existente

Uma pessoa em um terminal pode importar uma chave através do alerta escondido abaixo e pular o registro de teste e reivindicar. Os agentes devem fornecer no stdin com --api-key-stdin --non-interactive de sua loja secreta, nunca colocar uma chave em argumentos ou bate-papo.

Se o perfil já tem acesso diferente, reveja-o antes de usar auth login --replace. Importar outra chave não é a entrega da vinculação. MCP OAuth também é uma conexão de host separada.

#### Oculta chave prompt - terminal humano

```bash
flashdata auth login
flashdata auth status --json --non-interactive
```

- [Gerenciar chaves de API](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md)
- [MCP e outras opções de autenticação](https://flashdata.dev/pt/docs/guides/agent-access/reference.md)

<a id="trial"></a>

## 2. Inicie um teste elegível

Faça o discover primeiro. Verifique data.onboardingAvailable e a mesada em data.onboarding.trial. Se estiver disponível, execute init uma vez para Google Search. O servidor verifica a elegibilidade, o CLI salva a chave temporária sem abrir a inscrição ou enviar uma consulta.

### Verifique a disponibilidade. Livre

```bash
flashdata discover --json --non-interactive
```

### Iniciar acesso temporário

```bash
flashdata init --name "Research assistant" --scopes google_search --json --non-interactive
```

- [Protocolo atual](https://flashdata.dev/auth.md)

<a id="trial-receipt"></a>

### Verifique o recibo de registro

Espere ok: true, data.status: trial e google_search em data.connection.scopes. Leia data.connection.trialExpiresAt e data.startingAllowanceCredits. A chave é guardada localmente, não impressa. Se data.currentBalanceAvailable é false, reexecute a verificação de equilíbrio antes de consultar.

Se a configuração já criou um acesso, reutilize-o. Para identificar a origem do primeiro cadastro do agente, adicione --client codex --audience coding ou --client openclaw --audience personal. Em uma nova tentativa, mantenha exatamente a mesma entrada; os rótulos não concedem permissões.


<a id="trial-limits"></a>

### Créditos e limites do período de teste

Requisito equivalentes compartilhar o mesmo saldo de crédito inicial, não são pedidos ou quotas independentes. Fontes exclusivas de proprietários como YouTube Download não podem gastar créditos de teste.

| Limite | O que verificar? |
| --- | --- |
| Créditos / expiração | Padrão atual: crédito 1 para horas 72. Leia a descoberta para a bolsa e a vida útil, o recibo dá o prazo de validade e fontes concedidas. |
| Inscrições | Registros 3 por IP por hora 24, compartilhados por usuários desse IP. A cápsula de teste global também pode pausar novos registros. |
| Concurrência | Mantenha o teste sequencial: um item por lote e um trabalho pendente. Verifique os limites devolvidos antes de enviar mais. |

- [Créditos e pedidos contam](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md#estimate)
- [Acesso somente ao YouTube Download](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#download-only)

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

## 3. Faça uma pesquisa

Primeiro a visualização. Requer data.estimateAvailable, um preço google_search disponível em data.estimate.prices, e availableCredits cobrindo estimatedCredits. Pare se um verificação falhar. A prévia é gratuita, o próximo comando envia uma busca.

### Verifique o equilíbrio e o custo. Sem perguntas

```bash
flashdata account balance --json --non-interactive
flashdata search "battery recycling" --num 5 --dry-run --json --non-interactive
```

### Uma busca. Até cinco resultados

```bash
flashdata search "battery recycling" --num 5 --run-id trial-search --json --non-interactive
```


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

### Confira o resultado

Espere ok: true e data.status: done. Leia os títulos, links e trechos em data.results[].organic e os créditos cobrados em data.usage.credits. Resultados organic vazios são válidos. Antes de vincular a conta, repetir exatamente esta tarefa com trial-search retorna o resultado salvo. Preserve o perfil, o estado e os resultados do teste de que precisar.

#### Verifique o saldo restante. Livre

```bash
flashdata account balance --json --non-interactive
```

- [Leia uma resposta de busca](https://flashdata.dev/pt/docs/guides/http-quickstart/reference.md#result)

<a id="claim"></a>

## 4. Mantenha o acesso com uma conta do proprietário

A vinculação antes do teste expira se quiser uso contínuo ou recorrente. Quando o dono estiver pronto, faça isso no perfil original. Compartilhe apenas data.claimUrl e data.confirmationCode com eles; data.expiresAt dá o prazo.

O link dura 15 minutos, ou até o teste expirar, se antes. Criar o link não aprova acesso ou comprar créditos.

### Crie um link de vinculação quando o dono estiver pronto.

```bash
flashdata auth claim --json --non-interactive
```


<a id="owner-approval"></a>

### Aprovar no navegador

1. O proprietário abre o link e se conecta, ou cria uma nova conta e verifica o e-mail. Uma nova inscrição retoma a vinculação após a verificação.
2. Verifique a conta mostrada na página de reclamações. Para um proprietário diferente ou novo, use uma sessão de navegador separada. A conta assinada é a conta que pagará por pedidos posteriores.
3. Digite o código de oito dígitos nessa página, reveja as permissões de produtos e o acesso ao equilíbrio compartilhado, então aprove. O dono lida com inscrição, aceitação legal, verificação por e-mail e consentimento.


<a id="finish"></a>

### Termine no terminal original

Após a aprovação, execute finish no perfil original dentro de horas 24. O CLI salva a chave do proprietário, verifica em um novo processo e reconhece a instalação. Nenhuma chave é copiada do navegador.

#### Salve e verifique o acesso do proprietário

```bash
flashdata auth finish --wait --timeout 10m --json --non-interactive
```

#### Então verifique de um novo terminal, o mesmo usuário e perfil do OS.

```bash
flashdata auth status --json --non-interactive
flashdata account balance --json --non-interactive
```


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

### Confirme o proprietário e o equilíbrio

Em auth status, verifique o accountId pretendido e alcances concedidos, mais os campos abaixo. Leia o novo saldo separadamente, pedidos futuros gastam os créditos compartilhados do proprietário. Créditos temporários não usados não são transferidos. Uma nova conta segue a elegibilidade normal, alegando que não acrescenta nenhum subsídio extra.

Reclamar muda a conta faturada. Para uma nova tarefa sob o proprietário, escolha uma nova corrida ID. Reusando uma execução de teste ID retorna run_account_mismatch sem enviar outra consulta; não transfere que corre para o proprietário.

#### "Campos esperados" "Excerto de resposta"

```json
{
  "ok": true,
  "data": {
    "accessVerified": true,
    "identity": {
      "identity": {
        "accountType": "owned",
        "access": "ready",
        "installed": true,
        "recurringAllowed": true
      }
    }
  }
}
```

- [Configurar tarefas recorrentes](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)
- [Créditos depois de reivindicar](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md#trial)
- [Revogar esta conexão](https://flashdata.dev/pt/docs/guides/agent-access/reference.md#revoke)

<a id="permissions"></a>

## Escolha as permissões do produto

O catálogo de permissões HTTP separa trialEligible de ownerAllowed. Antes do primeiro registro, solicite apenas as fontes necessárias para a tarefa. requestedScopes contém os escopos solicitados; scopes contém o acesso atual da chave. Novos produtos exigem uma concessão explícita.

A aprovação permite usar o saldo compartilhado do titular, incluindo créditos comprados. Restringir as fontes não cria um limite de gastos por agente. MCP OAuth é uma conexão separada e não vincula este perfil da CLI.

- [Catálogo de Permissão e protocolo HTTP](https://flashdata.dev/auth.md)

<a id="download-only"></a>

## Só precisa de download YouTube?

Use uma chave do proprietário com permissão youtube_download, importe-a e configure o armazenamento de destino. O download não usa créditos temporários.

CLI 1.2.1 ainda requer uma fonte trial elegível para init. Para o download somente a bordo antes da inscrição, use o fluxo de vinculação HTTP em auth.md. Não adicione uma fonte de teste não relacionada apenas para contornar a restrição do cliente.

- [Importar uma chave de dono](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#existing)
- [Configure o armazenamento e o download](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md)
- [Fluxo HTTP](https://flashdata.dev/auth.md)

<a id="help"></a>

## Retomar um fluxo parado

| O que parou? | Próxima ação |
| --- | --- |
| Registrar | Para 429, espere por Retry-After. Para uma resposta perdida, tente novamente init com o mesmo perfil, prova e entrada exata. Mantenha o estado existente, não mude de IP ou inicie um teste de substituição. |
| Pesquisar | Inspecione trial-search abaixo. Um timeout não prova que nenhum trabalho foi aceito; não altere o ID da execução para forçar uma nova tentativa. |
| Reivindicar ligação | Se o link expirou, mas o teste é válido, crie um novo link no mesmo perfil quando o dono estiver pronto. verificação o proprietário antes da aprovação. |
| Demissão | Após a aprovação, reexecute auth finish no perfil original dentro de horas 24. Até a aprovação, uma espera interrompida ou um reconhecimento perdido não requer um novo registro. |
| Expirado / estado perdido | Para um teste ou transferência expirado, ou um diretório privado perdido, use reconexão aprovada pelo proprietário ou importe uma chave do proprietário. |

### Inspecione a pesquisa salva. Não há nenhuma nova consulta

```bash
flashdata runs show trial-search --json --non-interactive
```

- [Guia de recuperação](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)
