# 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 _2026-09-12 · Un agente può aprire da solo una sandbox Shager con una POST. Ecco la chiamata, cosa consente la sandbox, la rivendicazione umana e il permesso di pubblicare._ 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](/auth.md), e la [pagina per gli agenti](/en/agents) elenca i file di scoperta che un agente può leggere prima di cominciare. ## 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. ```bash 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`: ```json { "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`: ```python 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. ## 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](/en/blog/skill-weekly-distribution-routine). 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: ```text 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: 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](/en/pricing). ### 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](https://app.shager.ai/api/v1/openapi.json). ### 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](/en/blog/agent-content-pipeline-end-to-end) riprende esattamente da qui, dal brief ai post pubblicati e ai clic per account. --- Source: https://shager.ai/it/blog/agent-self-signup-and-claim