# Começar com o seu agente

> Do zero ao primeiro vídeo publicado com um agente de IA: o prompt para colar, o que só você faz (contas, chaves, canal, licença), o primeiro Short de teste, a publicação em duas etapas e como aprender com as métricas.

Fonte: https://praeko.app/docs/get-started-with-agent

Node 22 ou mais novo · Nada publica sem o seu sim · Remotion não é MIT

Você abre o seu agente de IA numa pasta vazia e cola **um prompt**. O agente cria o projeto, confere a máquina, faz a entrevista da sua marca, monta o primeiro vídeo e prepara a publicação. **Você só aprova e faz o que só você pode fazer**: criar a conta, guardar chaves, conectar o canal e aceitar a licença. Esta página é o roteiro; os detalhes de cada peça estão nas páginas que ela liga.

## 0. Para quem é e o que o agente precisa

| Você tem | Caminho | O que usar |
|---|---|---|
| Um agente **com terminal** (shell) | CLI | O agente roda `praeko studio …` e faz tudo, do projeto ao render. É o caminho deste guia. |
| Um agente **sem terminal** (por exemplo, o Claude Desktop sem shell) | MCP local | O servidor [`@praeko/studio-mcp`](https://praeko.app/docs/studio/mcp) roda na sua máquina e faz as etapas por ferramentas (`studio_new_episode`, `studio_render`…). Ele **nunca publica**. |

Nos dois caminhos, **quem publica é o servidor MCP remoto `praeko`** ([`praeko.app/mcp`](https://praeko.app/docs/mcp)), sempre em duas etapas: a prévia e o `confirm`. São dois servidores com papéis diferentes: o local (`praeko-studio`) cria e renderiza o vídeo; o remoto (`praeko`) olha a sua conta, sobe a mídia e publica. Conecte o seu agente ao remoto pela página do agente em [Agentes de IA](https://praeko.app/docs/agents).

Na máquina: Node 22, `ffmpeg` e Chrome (o `praeko studio doctor` confere e diz como corrigir; veja os [requisitos do Studio](https://praeko.app/docs/studio#requisitos)). O agente, a voz e o render são por sua conta; o Praeko não cobra nem intermedeia o agente.

> **Licença do motor de vídeo** O **Remotion**, motor padrão, não é MIT: grátis para pessoas e empresas de até 3 pessoas; acima disso precisa de licença. O HyperFrames (`--engine hyperframes`) é Apache-2.0. Leia [Licenças](https://praeko.app/docs/studio#licencas) antes do primeiro render.

## 1. O prompt de partida

Crie uma pasta vazia, abra o agente nela e cole o prompt abaixo, trocando o que está entre `<` e `>` pelas suas respostas. O agente cria o projeto com `init --yes` (sem perguntas no terminal), roda o `doctor`, faz a entrevista de marca **por conversa** e **nunca pede nem lê chaves**.

**Prompt para colar no agente**

```text
Você vai me levar do zero ao primeiro vídeo do meu canal com o Praeko Studio, nesta pasta vazia. Faça você mesmo tudo o que puder. Regras:
- Nunca peça, leia nem imprima chaves (de voz, do Praeko ou de qualquer rede). Se uma chave for necessária, me diga o comando para eu rodar no MEU terminal.
- Não gaste crédito de voz nem publique nada sem o meu sim, depois de me mostrar o que vai acontecer.
- Se o seu terminal não existir, pare e me diga: o caminho sem terminal usa o servidor MCP local do Studio.

1. Pergunte quais agentes de IA eu uso (pode ser mais de um, por exemplo claude,codex) e use a lista em --agent. Depois crie o projeto (use as minhas respostas abaixo; o que eu não souber, deixe de fora):
   npx @praeko/studio@latest init <pasta> --yes --agent <agentes-que-eu-uso> --name "<nome do canal>" --handle "@<handle>" --lang pt --about "<do que é o canal>" --audience "<para quem>" --tone "<tom de voz>" --accent "#f4b942" --background "#14110f" --font "Arial Black"
2. Entre na pasta e rode `praeko studio doctor` (se o comando `praeko` não existir, use `npx praeko-studio doctor`). Me explique o que faltar (Node 22, ffmpeg, Chrome, fontes) e como corrigir.
3. Leia as instruções do projeto. Se não existir `brief.md`, ou se o `playbook.md` ainda tiver TODO, faça a entrevista de marca CONVERSANDO: uma pergunta curta por vez, todas puláveis (nome, para quem é, tom, cores, fonte, até 3 referências, voz: só o apelido e o provedor). Grave `brief.md`, `playbook.md` e ajuste o `brand.json`. Conte o que você preencheu.
4. Pare e me entregue a lista do que SÓ eu posso fazer (conta e chave do Praeko, chave de voz, canal, aviso de licença), com os comandos exatos. Depois do meu "pronto", siga para o primeiro vídeo.
```

Cada resposta vira uma flag do `init`: `--name`, `--handle`, `--lang`, `--about`, `--audience`, `--tone`, `--accent`, `--background`, `--font`. Se você já tem uma pasta de marca com tokens, use `--brand <pasta>`. O que ficar de fora o agente pergunta na conversa e grava em `brief.md`, `playbook.md` e `brand.json`. As instruções do Studio para o seu agente (o *skill*) são gravadas por `--agent`; veja [Instruções para o seu agente](https://praeko.app/docs/studio#agents).

## 2. O que só você faz

O agente prepara a lista e os comandos; **você roda no seu terminal** (não no chat do agente: alguns clientes deixam rodar um comando com `!`, mas confira no seu). Nenhuma chave passa pela conversa.

### Conta e chave do Praeko

- Entre em `praeko.app` com o Google e crie uma chave em **Desenvolvedores, Chaves de API**. O escopo recomendado é **`write`**: sobe mídia e cria posts, sem mexer em chaves nem webhooks. Veja [Autenticação e escopos](https://praeko.app/docs/auth#scopes). Hoje o Praeko é um beta fechado: a [lista de espera](https://praeko.app/#lista) dá o acesso.
- Guarde a chave sem mostrá-la ao agente: deixe-a na variável `PRAEKO_KEY` do seu terminal (de um gerenciador de senhas, não escrita num arquivo do projeto) e rode `echo $PRAEKO_KEY | praeko studio schedule --via praeko --key`, que a guarda no Chaveiro do macOS ou no arquivo de segredos. Quem usa o servidor MCP remoto por login (OAuth) não precisa dela para publicar.

### Chave da voz (só para a voz final)

O primeiro vídeo usa voz de rascunho e **não precisa de chave**. Para a voz final, use **a sua voz** (ou uma que você tem autorização para usar) numa conta ElevenLabs sua. No seu terminal:

**No seu terminal (o comando pede a chave sem mostrá-la)**

```bash
praeko studio voice account add principal --voice my-voice --voice-id <YOUR_VOICE_ID>
praeko studio voice balance
```

Outra forma é `echo $ELEVENLABS_API_KEY | praeko studio voice config key elevenlabs/principal`. Veja [Chaves e custos](https://praeko.app/docs/studio#chaves).

### Canal e licença

- **Conectar o canal** (YouTube, Instagram ou TikTok) em **Canais**, no painel: o login nas redes é seu, o agente não faz. As três redes ainda dependem das aprovações dos apps (Meta e TikTok): se uma conexão não aparecer ou o TikTok publicar só como rascunho, é esse o limite de hoje. O YouTube sobe privado e agendado.
- **Aceitar o aviso de licença**: `praeko studio licenses --accept` registra que você leu (`praeko studio docs licenses` mostra o texto).

## 3. O primeiro vídeo

Com o projeto pronto e a lista acima feita, peça um Short de teste. A voz é de rascunho (estimada e muda, grátis, sem rede), então nada é gasto; o `check` avisa que ela não serve para publicar de verdade, e isso é esperado.

**Prompt do primeiro vídeo**

```text
Faça um Short de teste de uns 30 segundos sobre <TEMA> neste projeto do Praeko Studio. Leia as instruções do projeto, o brief.md e o playbook.md, e rode `praeko studio docs episode-yaml` antes de escrever o YAML.
1. Crie o episódio: `praeko studio new meu-teste --title "<título>"`. Escreva o roteiro (script.txt) e me mostre. Só avance depois do meu sim.
2. Voz em rascunho silencioso, que não custa nada: `praeko studio voice meu-teste --quality draft`. Não use `--quality final`: isso gasta caracteres da minha conta de voz e só com o meu sim.
3. Escreva as cenas em episode.yaml e rode, nesta ordem: `praeko studio compile meu-teste`, `praeko studio check meu-teste`, `praeko studio render meu-teste --scale 0.5`, `praeko studio contact-sheet meu-teste` (olhe a imagem e corrija o que estiver errado), `praeko studio cover meu-teste` e `praeko studio package meu-teste`.
4. Me mostre o pacote para aprovar: o roteiro, o contact-sheet, a capa, o texts.md de cada rede e os avisos do check (a voz de rascunho é esperada). Não publique nada.
```

O que você aprova aqui: o **roteiro** (antes de qualquer gasto), o **mosaico de quadros** (`contact-sheet`), a **capa** e o `texts.md` de cada rede. Para a voz final, o agente mostra o texto e o saldo (`praeko studio voice balance`) e espera o seu sim antes do `--quality final`. A declaração de conteúdo de IA fica em `publication.json` (veja [Conformidade](https://praeko.app/docs/studio#conformidade)).

## 4. Publicar, sempre depois do seu sim

Quem publica é o servidor MCP remoto `praeko`, em **duas etapas**: a primeira chamada devolve só a prévia e um `confirmation_code` (vale 10 minutos e uma vez); o agente mostra a prévia inteira e só repete a chamada com `confirm` depois do seu sim. Se qualquer argumento mudar, a prévia é refeita. Detalhes em [Servidor MCP](https://praeko.app/docs/mcp).

| Seu agente | Subir o arquivo | Criar o post |
|---|---|---|
| Com terminal | `create_media_upload`, o `curl` que ele devolve (a chave vem de `$PRAEKO_KEY`) e `complete_media_upload` | `create_post` ou `schedule_post`, nas duas etapas |
| Sem terminal | `studio_upload` no servidor local do Studio (também em duas etapas; devolve só o `mediaId`) | `create_post` no servidor remoto `praeko`, com o `mediaId` |

**Prompt para publicar**

```text
Publique o vídeo meu-teste pelo servidor MCP `praeko`, só depois do meu sim a cada etapa.
1. Chame list_channels e me diga em quais canais pretende publicar.
2. Suba o vídeo e a capa: com terminal, create_media_upload, rode o curl que ele devolve (a chave vem de $PRAEKO_KEY no ambiente; nunca a peça nem a imprima) e complete_media_upload. Sem terminal, studio_upload no servidor local do Studio.
3. Chame create_post (ou schedule_post, se eu der um horário) SEM confirm. Mostre a prévia inteira: canais, horário em BRT e UTC, mídia, textos, avisos.
4. Só repita a chamada com o confirm quando eu disser "pode publicar". Se eu mudar qualquer coisa, peça uma prévia nova.
```

Pela linha de comando, sem o MCP remoto, `praeko studio schedule <slug> --via praeko --when "dd/mm hh:mm"` só **simula** e `--send` agenda de verdade (o agente nunca usa `--send` sem você pedir). `praeko studio post` é a publicação direta com credenciais suas de cada rede, para uso avançado. O vídeo precisa de voz final antes de ir ao ar.

## 5. Aprender com os números

Depois de alguns posts, o agente lê as métricas pelo servidor MCP remoto e propõe o próximo roteiro. Só leitura: `get_insights` (visualizações, curtidas, comentários, seguidores, com comparação), `get_retention` (retenção, impressões e CTR por post), `list_posts` e `get_calendar`. Um número ausente vem como `null`, nunca como 0. Ler e responder comentários não é ferramenta do servidor: fica no painel e na API.

**Prompt para aprender**

```text
Leia como o meu canal está indo pelo servidor MCP `praeko` e proponha o próximo roteiro. Só leitura, não crie nada.
1. get_insights dos últimos 28 dias, comparando com o período anterior, e get_retention dos mesmos posts.
2. list_posts com state "sent" para ligar cada número a um título.
3. Me diga em três linhas o que funcionou e o que não, citando os números. Onde um número vier vazio (null), diga que não há dado, não chute.
4. Proponha UM roteiro para o próximo Short, com o gancho e o motivo, e espere o meu sim antes de criar o episódio.
```

## 6. Para não se perder

### O que o agente faz e o que você faz

| Etapa | O agente faz | Você faz |
|---|---|---|
| Projeto e ambiente | `init`, `doctor`, instalar as instruções do Studio | Instala o que o `doctor` apontar (Node, `ffmpeg`, Chrome) se o agente não puder |
| Marca | Entrevista por conversa, grava `brief.md`, `playbook.md`, `brand.json` | Responde e aprova o resultado |
| Contas e chaves | Diz qual comando rodar; **nunca** pede nem lê a chave | Cria a conta e a chave `write`, guarda as chaves no seu terminal, conecta o canal |
| Licença | Lembra do aviso | Lê e roda `praeko studio licenses --accept` |
| Vídeo | Roteiro, voz de rascunho, cenas, `compile`, `check`, `render`, capa, `package` | Aprova o roteiro, o mosaico, a capa e os textos; autoriza a voz final |
| Publicar | Sobe a mídia, pede a prévia, mostra tudo | Diz o sim; marca o rótulo de IA no app da rede quando for preciso |
| Aprender | Lê `get_insights` e `get_retention` e propõe o próximo roteiro | Escolhe o roteiro e volta ao passo 3 |

### Erros comuns

| Sintoma | O que fazer |
|---|---|
| O agente diz que não tem terminal | Use o caminho do [MCP local do Studio](https://praeko.app/docs/studio/mcp); ou abra um agente com shell (veja [Agentes de IA](https://praeko.app/docs/agents)). |
| `no Praeko key found` ou erro de chave ao subir | Guarde uma chave `write` no seu terminal (passo 2). Nunca cole a chave no chat. |
| `ffmpeg` não encontrado | Instale (`brew install ffmpeg` ou `sudo apt install ffmpeg`) e rode `praeko studio doctor`. |
| Node antigo | O Studio pede Node 22 ou mais novo; o `doctor` mostra a versão que achou. |
| O primeiro render demora ou falha | O Remotion baixa o Chrome Headless Shell no primeiro render (precisa de internet). Sem internet, instale o Chrome e defina `CHROME_PATH`. |
| `check` avisa que a voz é estimada | Esperado com o rascunho. Gere a voz final, com a sua chave, antes de publicar. |
| O `confirm` foi recusado (`expired`, `arguments_changed`…) | Passaram 10 minutos ou algo mudou depois da prévia: peça uma prévia nova e confirme sem mexer em nada. |

Mais casos em [Problemas comuns do Studio](https://praeko.app/docs/studio#troubleshooting) e em [Studio MCP](https://praeko.app/docs/studio/mcp).

### Checklist final

1. Node 22, `ffmpeg` e Chrome ok no `praeko studio doctor`.
2. Licença lida e aceita (`praeko studio licenses --accept`).
3. Chave `write` do Praeko guardada no seu terminal, e o agente conectado ao servidor MCP remoto `praeko`.
4. Canal conectado no painel (com a ressalva das aprovações da Meta e do TikTok).
5. `brief.md`, `playbook.md` e `brand.json` revistos por você.
6. Roteiro, mosaico, capa e textos aprovados; voz final só com o seu sim.
7. Rótulo de conteúdo de IA conferido (`ai.synthetic`) e marcado no app da rede quando preciso.
8. Prévia do post lida inteira antes do `confirm`.

### Links

- [Do zero ao primeiro vídeo](https://praeko.app/docs/get-started): O mesmo caminho pela API, o SDK e a CLI.
- [Praeko Studio](https://praeko.app/docs/studio): Comandos, projeto, chaves, licenças e problemas.
- [Studio: MCP local](https://praeko.app/docs/studio/mcp): Para o agente sem terminal.
- [Servidor MCP remoto](https://praeko.app/docs/mcp): Publicar em duas etapas e ler métricas.
- [Agentes de IA](https://praeko.app/docs/agents): Conectar o seu agente ao Praeko.
- [SDK e CLI](https://praeko.app/docs/sdk): A linha de comando praeko e o cliente JavaScript.
- [Autenticação e escopos](https://praeko.app/docs/auth): Chaves read, write e admin.