Autocadastro de agentes: o agente de IA abre um sandbox no Shager com uma chamada, e o botão de publicar continua com uma pessoa

Um agente de IA pode se cadastrar no Shager sozinho, com uma única requisição: POST https://app.shager.ai/api/v1/agent/signup com um corpo JSON que tenha pelo menos agent_name. Ele recebe de volta uma chave de API, uma URL MCP e um link de reivindicação, e já pode criar espaços de trabalho, importar mídia e escrever rascunhos de posts. Nada é agendado nem publicado até que uma pessoa abra o link de reivindicação, faça login e decida se aquela chave pode publicar.

Toda a lógica está nessa divisão. O agente não fica travado esperando alguém; a pessoa continua com a decisão que afeta públicos reais.

Por que deixar um agente se cadastrar sozinho?

Porque a alternativa quebra o fluxo do agente. Um agente que recebe a tarefa de "montar a distribuição nas redes do nosso cliente" bate na parede logo no primeiro passo se a única porta de entrada for uma pessoa preenchendo um formulário de cadastro, confirmando um e-mail e criando uma chave em um painel. Quando alguém finalmente faz isso, o contexto do agente já se perdeu.

Com o autocadastro, o agente adianta o trabalho por conta própria: cria um espaço de trabalho por cliente, puxa as mídias, escreve rascunhos e entrega à pessoa um único link com tudo pronto para revisar. A receita de registro está publicada para agentes em /auth.md, e a página para agentes lista os arquivos de descoberta que um agente pode ler antes de começar.

Role para o lado para ver o diagrama inteiro

Como é a chamada de cadastro?

Só agent_name é obrigatório (de 2 a 80 caracteres). Os outros campos ajudam a pessoa a reconhecer o que está reivindicando.

curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Northwind content agent",
    "contact_email": "ops@northwind-agency.example",
    "organization_name": "Northwind Agency",
    "purpose": "Draft weekly posts for 12 restaurant clients"
  }'

A resposta vem toda dentro de data:

{
  "data": {
    "api_key": "shgr_live_...",
    "organization_id": "...",
    "sandbox": true,
    "claim_url": "https://app.shager.ai/...",
    "expires_at": "2026-09-19T10:04:11.000Z",
    "mcp_url": "https://app.shager.ai/api/mcp",
    "api_base": "https://app.shager.ai/api/v1",
    "openapi_url": "https://app.shager.ai/api/v1/openapi.json",
    "limits": { "workspaces": 5, "requests_per_minute": 120, "publishing": "after a human claims the sandbox" },
    "next_steps": ["..."]
  }
}

Dois campos precisam de atenção imediata.

1. A api_key aparece uma única vez. Guarde-a antes de fazer qualquer outra coisa, em um cofre de segredos ou em uma variável de ambiente, nunca em uma linha de log.
2. O claim_url vai para uma pessoa. Se você passou contact_email, o Shager também envia o link de reivindicação para esse e-mail, mas o agente deve mostrá-lo na própria resposta mesmo assim.

O cadastro é limitado a cinco por hora por endereço, o que impede que um agente preso em loop crie dezenas de sandboxes órfãos.

O que um sandbox ainda não reivindicado pode fazer?

Permitido antes da reivindicação	Bloqueado até uma pessoa reivindicar
Criar até 5 espaços de trabalho	Agendar ou publicar qualquer coisa
Enviar mídia a partir de URLs	Criar links de conexão para clientes
Criar rascunhos de posts	Enviar pedidos de aprovação a clientes
Listar e ler tudo o que criou

As chamadas bloqueadas falham com um erro claro, e não com um silêncio que não faz nada. Uma tentativa de agendar devolve HTTP 403 com "code": "sandbox_unclaimed", e o mesmo vale para create_connect_link e request_approval. Um sexto espaço de trabalho devolve 403 sandbox_limit. Um bom agente lê o code e diz à pessoa o que falta, em vez de tentar de novo.

Links de conexão e pedidos de aprovação ficam bloqueados porque os dois chegam a pessoas reais fora da agência: um cliente clicando em um link para conectar a sua página do Facebook, ou um revisor recebendo um e-mail de aprovação. Isso não deve acontecer em nome de uma organização que ninguém verificou.

Uma primeira sessão sensata no sandbox

Veja o que um agente bem-comportado faz nos primeiros minutos, em Python com requests:

import os, requests

API = "https://app.shager.ai/api/v1"
H = {"Authorization": f"Bearer {os.environ['SHAGER_API_KEY']}"}

def call(method, path, **body):
    r = requests.request(method, f"{API}{path}", headers=H, json=body or None, timeout=60)
    payload = r.json()
    if not r.ok:
        err = payload["error"]
        raise RuntimeError(f"{r.status_code} {err['code']}: {err['message']}")
    return payload["data"]

me = call("GET", "/me")
print(me)  # organization, scopes, sandbox status

ws = call("POST", "/workspaces", name="Harbor Tacos", timezone="America/Chicago")

media = call("POST", f"/workspaces/{ws['id']}/media",
             url="https://harbortacos.example/press/fall-menu.jpg",
             file_name="fall-menu.jpg")

print("Workspace", ws["id"], "media", media["id"], media["kind"])

Passe o timezone explicitamente ao criar um espaço de trabalho. É um nome de fuso IANA, e o agendamento depois é interpretado nesse fuso; um restaurante em Chicago não deve herdar o padrão de outra pessoa.

Nesse ponto ainda não há nenhuma conta de rede social conectada, porque conectar contas exige um link de conexão, e o link de conexão exige a reivindicação. O agente prepara o conteúdo e a estrutura, e a pessoa abre a porta para o resto.

Role para o lado para ver o diagrama inteiro

O que acontece quando a pessoa reivindica o sandbox?

A pessoa abre o claim_url, entra no Shager (ou cria uma conta) e assume a propriedade do sandbox junto com os espaços de trabalho, as mídias e os rascunhos que o agente preparou. Durante a reivindicação, ela escolhe se a chave do agente também pode agendar e publicar, o que acrescenta o escopo publish.

Essa escolha merece um minuto de reflexão. Deixar o publish desligado é uma configuração perfeitamente boa a longo prazo: o agente escreve os rascunhos, e a pessoa ou o cliente aprova e agenda. Muitas agências começam assim e depois criam uma chave de publicação separada em https://app.shager.ai/dashboard/agents, onde qualquer chave pode ser revogada e toda chamada de agente aparece no log de auditoria. Os prós e contras de cada configuração estão em a rotina semanal de distribuição.

Depois da reivindicação, os próximos passos que a própria API sugere são diretos: chamar create_connect_link para que o dono das contas conecte as suas redes (Facebook, Instagram, YouTube, X, LinkedIn ou TikTok) sem precisar de login no Shager, depois create_post e, se a chave tiver publish, schedule_post.

E se ninguém reivindicar?

Sandboxes não reivindicados expiram depois de sete dias, no horário indicado em expires_at. Os rascunhos e os espaços de trabalho vão junto. Um agente trabalhando em um projeto mais longo deve lembrar a pessoa antes dessa data, e não deve reagir à expiração se cadastrando de novo, várias vezes. Um sandbox novo não traz os rascunhos antigos.

Como o agente deve fazer a passagem de bastão?

Com clareza, com o link e as consequências. Algo assim:

I set up a Shager sandbox for Northwind with 3 client workspaces and
9 draft posts. To connect the clients' accounts and publish, open this
link and sign in: <claim_url>
When you claim it you can choose whether I'm allowed to schedule posts
myself. If you don't claim it by Sep 19, the sandbox and drafts are deleted.

Essa mensagem é honesta sobre o que foi feito, o que está pendente e o que fica sob controle da pessoa. E também é a mensagem com mais chance de receber o clique.

Perguntas frequentes

O autocadastro custa alguma coisa?

Não. O sandbox é gratuito e, durante o período de lançamento, o Shager também é gratuito depois da reivindicação, sem cartão; antes de começarmos a cobrar, avisaremos com antecedência. O acesso à API e ao MCP está incluído em todos os planos. Os limites de cada plano estão na página de preços.

O agente pode usar MCP em vez de REST depois do cadastro?

Pode. A resposta inclui o mcp_url, e a mesma chave funciona como Authorization: Bearer shgr_live_... no servidor MCP. As ferramentas correspondem uma a uma às operações REST descritas no documento OpenAPI.

Uma chave reivindicada pode publicar sem que uma pessoa veja o post?

Só se a pessoa tiver concedido publish durante a reivindicação e o espaço de trabalho não exigir aprovação do cliente. As duas coisas são escolha da pessoa, e as duas podem mudar depois: as chaves podem ser revogadas no painel, e a aprovação pode ser exigida por espaço de trabalho.

Próximo passo

Depois que o sandbox for reivindicado e as contas estiverem conectadas, saia da exploração e faça uma execução completa. O pipeline de conteúdo do agente de ponta a ponta continua exatamente de onde este artigo parou, do briefing aos posts publicados e aos cliques por conta.