Registrazione autonoma degli agenti: un agente IA apre una sandbox Shager con una sola chiamata, ma il tasto per pubblicare resta in mano a una persona

Un agente IA può registrarsi su Shager da solo con una sola richiesta: POST https://app.shager.ai/api/v1/agent/signup con un body JSON che contenga almeno agent_name. In risposta riceve una chiave API, un URL MCP e un link di rivendicazione, e può subito creare workspace, importare media e preparare bozze di post. Nulla viene programmato o pubblicato finché una persona non apre il link di rivendicazione, accede e decide se quella chiave può pubblicare.

Tutto il design sta in questa divisione. L'agente si sblocca senza aspettare nessuno; la persona mantiene la decisione che riguarda il pubblico reale.

Perché lasciare che un agente si registri da solo?

Perché l'alternativa interrompe il lavoro dell'agente. Un agente a cui si chiede di "impostare la distribuzione social del nostro cliente" si blocca al primo passo se l'unico modo per entrare è che una persona compili un modulo di registrazione, verifichi un'email e crei una chiave in una dashboard. Quando qualcuno ci arriva, il contesto dell'agente è già andato perso.

Con la registrazione autonoma l'agente prepara il terreno da solo: crea un workspace per ogni cliente, importa i media, scrive le bozze e consegna alla persona un unico link con tutto pronto da rivedere. La procedura di registrazione per gli agenti è pubblicata in /auth.md, e la pagina per gli agenti elenca i file di scoperta che un agente può leggere prima di cominciare.

Scorri di lato per vedere tutto il diagramma

Com'è fatta la chiamata di registrazione?

È obbligatorio solo agent_name (da 2 a 80 caratteri). Gli altri campi aiutano la persona a riconoscere cosa sta rivendicando.

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"
  }'

La risposta racchiude tutto in 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": ["..."]
  }
}

Due campi vanno gestiti subito.

1. api_key viene mostrata una sola volta. Salvala prima di fare qualsiasi altra cosa, in un archivio di segreti o in una variabile d'ambiente, mai in una riga di log.
2. claim_url va a una persona. Se hai passato contact_email, Shager invia il link di rivendicazione anche a quell'indirizzo, ma l'agente dovrebbe comunque riportarlo nella propria risposta.

Le registrazioni sono limitate a cinque all'ora per indirizzo, così un agente finito in un loop non genera decine di sandbox orfane.

Cosa può fare una sandbox non ancora rivendicata?

Consentito prima della rivendicazione	Bloccato finché una persona non la rivendica
Creare fino a 5 workspace	Programmare o pubblicare qualsiasi cosa
Caricare media da URL	Creare link di collegamento per i clienti
Creare bozze di post	Inviare richieste di approvazione ai clienti
Elencare e leggere tutto ciò che ha creato

Le chiamate bloccate falliscono con un errore chiaro, non con un'operazione che silenziosamente non fa nulla. Un tentativo di programmare restituisce HTTP 403 con "code": "sandbox_unclaimed", e lo stesso vale per create_connect_link e request_approval. Un sesto workspace restituisce 403 sandbox_limit. Un buon agente legge il code e spiega alla persona cosa serve, invece di riprovare.

I link di collegamento e le richieste di approvazione sono bloccati perché entrambi raggiungono persone reali fuori dall'agenzia: un cliente che clicca un link per collegare la sua pagina Facebook, o un revisore che riceve un'email di approvazione. Non dovrebbe succedere a nome di un'organizzazione che nessuno ha verificato.

Una prima sessione sensata nella sandbox

Ecco cosa fa un agente educato nei suoi primi minuti, in Python con 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"])

Passa timezone in modo esplicito quando crei un workspace. È il nome di un fuso IANA e la programmazione successiva viene interpretata in quel fuso, quindi un ristorante di Chicago non dovrebbe ereditare l'impostazione predefinita di qualcun altro.

A questo punto non ci sono ancora account social collegati, perché per collegarli serve un link di collegamento, e per il link serve la rivendicazione. L'agente prepara contenuti e struttura; la persona apre la porta al resto.

Scorri di lato per vedere tutto il diagramma

Cosa succede quando la persona la rivendica?

La persona apre claim_url, accede a Shager (o crea un account) e diventa proprietaria della sandbox insieme a workspace, media e bozze preparati dall'agente. Durante la rivendicazione sceglie se la chiave dell'agente può anche programmare e pubblicare, cosa che aggiunge il permesso publish.

Questa scelta merita un attimo di riflessione. Lasciare publish disattivato è un'ottima configurazione anche a lungo termine: l'agente prepara le bozze, la persona o il cliente approva e programma. Molte agenzie partono così e aggiungono in seguito una chiave separata per la pubblicazione su https://app.shager.ai/dashboard/agents, dove ogni chiave può essere revocata e ogni chiamata dell'agente compare nel registro di audit. I pro e i contro di queste configurazioni li trovi in la routine di distribuzione settimanale.

Dopo la rivendicazione, i passi successivi suggeriti dall'API stessa sono semplici: chiamare create_connect_link perché il titolare degli account colleghi i propri account social (Facebook, Instagram, YouTube, X, LinkedIn o TikTok) senza un accesso a Shager, poi create_post e, se la chiave ha publish, schedule_post.

E se nessuno la rivendica?

Le sandbox non rivendicate scadono dopo sette giorni, all'ora indicata in expires_at. Bozze e workspace spariscono con loro. Un agente che lavora a un progetto più lungo dovrebbe ricordarlo alla persona prima di quella data, e non dovrebbe reagire alla scadenza registrandosi ancora e ancora. Una sandbox nuova non si porta dietro le vecchie bozze.

Come dovrebbe formulare l'agente il passaggio di consegne?

In modo semplice, con il link e le conseguenze. Qualcosa come:

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.

Il messaggio è onesto su cosa è stato fatto, cosa è in attesa e cosa controlla la persona. Ed è anche il messaggio che ha più probabilità di essere cliccato.

Domande frequenti

La registrazione autonoma costa qualcosa?

No. La sandbox è gratuita, e durante il periodo di lancio Shager è gratuito anche dopo la rivendicazione, senza carta; prima di iniziare a far pagare ti avviseremo con anticipo. L'accesso API e MCP è incluso in ogni piano. I limiti dei piani sono nella pagina dei prezzi.

Dopo la registrazione l'agente può usare MCP invece di REST?

Sì. La risposta include mcp_url e la stessa chiave funziona come Authorization: Bearer shgr_live_... sul server MCP. Gli strumenti corrispondono uno a uno alle operazioni REST descritte nel documento OpenAPI.

Una chiave rivendicata può mai pubblicare senza che una persona veda il post?

Solo se la persona ha concesso publish durante la rivendicazione e il workspace non richiede l'approvazione del cliente. Sono entrambe scelte della persona ed entrambe si possono cambiare in seguito: le chiavi si revocano dalla dashboard e l'approvazione si può rendere obbligatoria per ogni workspace.

Prossimo passo

Una volta rivendicata la sandbox e collegati gli account, passa dall'esplorazione a un'esecuzione completa. La pipeline di contenuti dell'agente dall'inizio alla fine riprende esattamente da qui, dal brief ai post pubblicati e ai clic per account.