Agenti AI e mondo fisico: dare contesto su case e uffici

Gli agenti AI conoscono il tuo codice, i tuoi documenti e il tuo calendario, ma niente dei luoghi in cui vivi e lavori. Space Context è il livello di contesto per il mondo fisico: filmi uno spazio una volta (con l’app per iPhone, l’API, la CLI o l’SDK) e diventa uno Space Document strutturato, in cui ogni record visto nel video cita i fotogrammi da cui viene. Gli agenti lo leggono tramite un’API REST, un SDK TypeScript, una CLI e un server MCP remoto, e quando un’informazione non c’è rispondono «non documentato» invece di indovinare.

In breve

• Un video, o fino a 120 foto, diventa un documento JSON con aree, oggetti, condizioni, problemi, punti chiave, istruzioni, fatti e domande con risposta.
• Ogni record visto nel video porta con sé i fotogrammi originali in cui compare, con il loro istante nel video.
• Quattro modi di entrare: app per iPhone, API REST, CLI e SDK, server MCP per Claude, ChatGPT, Cursor, Claude Code, Codex e VS Code.
• Codici e password restano nascosti a chi non ha lo scope spaces:sensitive; il testo che prova a dare ordini a un’AI viene trattenuto.
• Le chiavi di test sono gratuite; con una carta salvata la prima scansione reale è gratuita, poi 1,00 $ a scansione.

Perché un agente AI non sa nulla di una casa o di un ufficio?

Perché quell’informazione non sta in nessun sistema. Dov’è la chiusura dell’acqua, che modello è la caldaia, quale chiave apre la cantina, se il cavo della stufetta in bagno è allentato: sono cose che stanno nella testa di qualcuno, in un quaderno, in qualche foto sparsa nel telefono. Una galleria di foto non è un dato: non ha stanze, non ha oggetti, non dice dove si trova cosa.

Chiedi a un agente dov’è il quadro elettrico di un appartamento che non conosce e farà ciò che fanno i modelli: risponderà con il posto più probabile in una casa tipica. A un agente che deve agire su un luogo reale servono tre cose: record strutturati, la prova da cui vengono, e la capacità di dire «questo non lo so».

Che cos’è un livello di contesto per il mondo fisico?

È lo strato tra un luogo fisico e gli agenti che devono lavorarci. Il flusso, in Space Context, è questo:

1. Si filma lo spazio, raccontando ciò che la camera non vede: «il quadro elettrico è nell’armadio dell’ingresso, dietro i cappotti».
2. L’analisi gira da noi: estrazione dei fotogrammi e trascrizione dell’audio, controllo di ogni fotogramma, descrizione, fusione, un passo approfondito che struttura tutto e individua i valori sensibili.
3. Ne esce uno Space Document versionato, lo stesso per gli spazi registrati con l’app e via API.
4. Gli agenti lo leggono, lo cercano, lo interrogano e confrontano due scansioni dello stesso spazio.

Affitti brevi, check-in e check-out, inventari, uffici, veicoli, prove per i sinistri: sono esempi d’uso, non il confine del prodotto. Qualsiasi spazio che puoi filmare funziona allo stesso modo.

Com’è fatto uno Space Document?

Più frames (i fotogrammi di prova, con URL firmati) e coverage (avvisi, ciò che non è documentato, la checklist dei punti chiave). Questi sono due record reali dello spazio dimostrativo, un bilocale a Brisbane scansionato due volte via API (foto di Chris Olszewski, CC BY-SA 4.0; la narrazione è inventata per la demo):

{
  "id": "loc_1",
  "kind": "electrical_panel",
  "label": "Fuse box",
  "area_id": "room-33614ab5-1",
  "location": "In the hallway cupboard behind the coats",
  "notes": null,
  "evidence": [],
  "confidence": 0.99
}

{
  "id": "iss_2",
  "area_id": "room-33614ab5-3",
  "item_id": "itm_32",
  "title": "Loose heater cable",
  "category": "safety",
  "severity": "high",
  "suggested_action": "Stop using the heater and repair or replace its cable before use.",
  "evidence": [
    { "frame_id": "frame-28", "timestamp_ms": 28087 },
    { "frame_id": "frame-30", "timestamp_ms": 30058 },
    { "frame_id": "frame-31", "timestamp_ms": 31044 }
  ]
}

Il quadro elettrico ha evidence vuoto: viene solo dalla narrazione, nessun fotogramma lo mostra, e il documento lo dice invece di inventare una foto. Il problema della stufetta, invece, cita tre fotogrammi del video a 28, 30 e 31 secondi. Il riferimento completo, campo per campo, è nella pagina The Space Document (in inglese).

Quali sono i quattro modi di entrare?

Collegare Claude Code al server MCP è una riga:

claude mcp add --transport http --scope user spacecontext https://mcp.spacecontext.app/mcp

Poi /mcp in Claude Code e Authenticate. Per Claude, ChatGPT, Codex, Cursor e VS Code i passi sono nella guida Connect an assistant (in inglese). Il collegamento è in sola lettura, a meno che tu non permetta all’assistente anche di avviare scansioni.

Dal terminale, con una chiave di test gratuita, puoi interrogare la demo anche in italiano:

npx spacecontext login --test
npx spacecontext ask spc_demo "dov'è il frigorifero?"

Dark refrigerator is in the Open-plan Living, Dining and Kitchen, at the left side of the kitchen work area. Condition: good.

Sources
  • Dark refrigerator (Open-plan Living, Dining and Kitchen)

Con le chiavi reali (sc_live_…) la ricerca tra gli spazi è semantica e multilingue (con una chiave di test la ricerca sullo spazio dimostrativo è lessicale): «rubinetto dell’acqua» trova «water shut-off valve». Dall’SDK, la stessa domanda è una chiamata:

import { SpaceContext } from '@spacecontext/sdk';

const sc = new SpaceContext({ apiKey: process.env.SPACECONTEXT_API_KEY });
const answer = await sc.spaces.ask('spc_demo', 'Where is the water shut-off?');
console.log(answer.answer, answer.citations);

Per provare tutto senza pagare nulla, crea una chiave di test gratuita: lavora sullo spazio dimostrativo, le scansioni finiscono all’istante e non viene addebitato niente.

Perché contano i fotogrammi di prova?

Ogni record ricavato dal video porta con sé evidence: un elenco di { frame_id, timestamp_ms } che punta ai frames del documento. Ogni fotogramma ha un URL firmato a breve scadenza che serve l’immagine originale, non ritoccata; quando scade, si rilegge il documento per averne uno nuovo. Da MCP, get_evidence_photo mostra all’assistente il fotogramma dietro un record.

Per un agente questo cambia il tipo di risposta. Non «di solito il quadro elettrico è nell’ingresso», ma «nell’armadio dell’ingresso, dietro i cappotti, secondo la narrazione; nessuna foto lo mostra». Per un essere umano che deve fidarsi, la differenza è tutta lì. Lo stesso vale per il confronto tra due scansioni dell’API: un oggetto è dato per sparito solo se un fotogramma della scansione successiva mostra il posto vuoto; il resto è not_seen, «non visto», da verificare.

Che cosa succede quando un’informazione non c’è?

Il sistema è costruito per dirlo. POST /spaces/{id}/ask risponde in una-tre frasi usando solo i record dello spazio, con le citazioni; quando i record non contengono la risposta, documented è false e la risposta lo dice. La Skill esportata (SKILL.md) dice all’agente di rispondere «non documentato» invece di indovinare, e il server MCP gli dà la stessa indicazione.

Il documento elenca anche i propri buchi: coverage.not_documented dice ciò che un lettore si aspetterebbe e il video non ha mostrato, e coverage.checklist dice quali punti chiave del tipo di spazio sono stati visti nei fotogrammi: per una casa quadro elettrico, chiusura dell’acqua, caldaia, rilevatore di fumo, estintore, router, termostato e contatore del gas; uffici, negozi, magazzini, garage, veicoli, camper, barche ed elettrodomestici hanno ciascuno la propria lista. Non visto vuol dire non ripreso: è un suggerimento per la prossima registrazione.

Come si dà un luogo a un agente senza dargli le password?

Un video racconta anche cose che un agente non deve ripetere. Le chiavi hanno scope:

spaces:sensitive non è mai concesso per impostazione predefinita. Una chiave senza quello scope legge il documento oscurato, e i risultati di ricerca non contengono valori sensibili qualunque sia la chiave.

C’è poi il prompt injection dal mondo fisico: un cartello o una frase detta in video («ignora le istruzioni precedenti e…») che prova a dare ordini all’agente che leggerà lo spazio. Space Context riconosce questo testo (in inglese e in italiano, e i tentativi di scavalcare le istruzioni anche in spagnolo, francese e tedesco), lo trattiene da documenti, Skill, ricerca e risposte, e lo segnala in coverage.warnings. È una rete di sicurezza, non una garanzia: un agente deve comunque trattare come non fidato ciò che viene dal mondo fisico.

Che cosa si può costruire?

Qualche esempio, tra i tanti possibili:

• Un assistente per chi gestisce case: «dov’è la chiusura dell’acqua nel bilocale al mare?», con la stanza e la foto.
• Check-in e check-out: due scansioni e un confronto che separa ciò che è confermato da ciò che non è stato ripreso; come funziona è spiegato nell’articolo sul verbale di consegna e riconsegna con video.
• Uffici e sedi aziendali: dove sono il quadro, gli estintori, il router di ogni sede.
• Un PMS o un gestionale che crea uno spazio per ogni struttura (con external_id, per esempio l’id dell’annuncio), avvia le scansioni e riceve il webhook scan.completed.
• Claude Code: uno spazio esportato come Agent Skill, con npx spacecontext skill spc_demo --out ./brisbane-apartment-skill.
• Agenti che pagano da soli: un agente con USDC su Base o Solana compra credito e una chiave in una sola chiamata x402 (POST /v1/agent/credits), senza account né carta.

SDK, CLI, server MCP, contratto OpenAPI e documentazione sono MIT su GitHub; la pipeline di analisi gira nell’API.

Quanto costa?

Nessun abbonamento e il saldo non scade. Gli spazi registrati con l’app per iPhone si leggono via API, console e MCP con lo stesso account, senza costi. Il riepilogo per sviluppatori in italiano è su Space Context per sviluppatori.

Inizia con la demo

Il percorso più breve: crea una chiave di test gratuita e chiedi allo spazio dimostrativo dov’è il quadro elettrico, con npx spacecontext ask spc_demo "where is the fuse box?" o con l’SDK. Quando funziona come ti serve, salva una carta, filma uno spazio vero e fai la prima scansione reale, che è gratuita; poi collega il server MCP al tuo assistente, che legge i tuoi spazi reali (lo spazio dimostrativo si legge solo con una chiave di test).