---
title: "Agenti AI e mondo fisico: dare contesto su case e uffici"
description: "Come dare a un agente AI il contesto di una casa o di un ufficio: lo Space Document, quattro modi di entrare (app, API, CLI e SDK, MCP) e le prove fotografiche."
lang: it
date: 2026-10-11
updated: 2026-10-13
tags: ["agenti ai", "mcp", "api", "space document"]
source_url: https://spacecontext.app/it/blog/contesto-mondo-fisico-agenti-ai/
---

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

Come dare a un agente AI il contesto di una casa o di un ufficio: lo Space Document, quattro modi di entrare (app, API, CLI e SDK, MCP) e le prove fotografiche.

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?

| Record | Che cosa contiene |
| --- | --- |
| Area | Nome, tipo (`kitchen`, `bathroom`…), condizione, descrizione, da dove si accede |
| Item | Nome, nome generico (`canonical_name`), categoria, quantità, posizione nell'area, condizione, marca, modello, testo visibile, alias |
| Issue | Titolo, descrizione, gravità (`low`, `medium`, `high`, `critical`), azione suggerita |
| Key location | `water_shutoff`, `electrical_panel`, `gas_shutoff`, `water_heater`, `router`, `smoke_detector`… con posizione |
| Instruction | Passi, dalla narrazione |
| Fact | Wi-Fi, regole, contatti, orari, misure, con il flag `sensitive` |
| Q&A | Domanda, risposta, fonte (`owner` o `generated`) |

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):

```json
{
  "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
}
```

```json
{
  "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](https://spacecontext.app/developers/docs/api/space-document/) (in inglese).

## Quali sono i quattro modi di entrare?

| | Per chi | Come |
| --- | --- | --- |
| App per iPhone | Chi filma sul posto | Registra il video; gli spazi si leggono poi da API, console e MCP con lo stesso account |
| API REST | Chi integra in un prodotto, un PMS, un gestionale | `https://api.spacecontext.app/v1`, JSON su HTTPS, contratto OpenAPI |
| CLI e SDK | Chi lavora dal terminale o in TypeScript | `npx spacecontext`, `@spacecontext/sdk` (Node.js, Deno, Cloudflare Workers) |
| Server MCP | Chi vuole che un assistente conosca i propri spazi | `https://mcp.spacecontext.app/mcp`, OAuth, nessuna chiave da incollare |

Collegare Claude Code al server MCP è una riga:

```bash
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](https://spacecontext.app/developers/docs/mcp/connect/) (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:

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

```text
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:

```ts
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](https://spacecontext.app/developers/console/): 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:

| Scope | Permette |
| --- | --- |
| `spaces:read` | Leggere, cercare e interrogare gli spazi |
| `scans:read` | Seguire le scansioni, leggere il saldo |
| `scans:write` | Creare spazi e scansioni (una chiave reale spende dal saldo) |
| `spaces:sensitive` | Vedere i valori sensibili: password del Wi-Fi, codici di porte e allarmi, la trascrizione |

`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](https://spacecontext.app/it/blog/verbale-consegna-riconsegna-immobile-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](https://github.com/finikoslab/spacecontext); la pipeline di analisi gira nell'API.

## Quanto costa?

| | Prezzo |
| --- | --- |
| Chiavi di test | Gratuite, sullo spazio dimostrativo |
| Prima scansione reale di un nuovo account | Gratuita, una per carta (salvare la carta non addebita nulla) |
| Ogni scansione reale successiva | 1,00 $ da un saldo prepagato, ricariche da 10 $, al netto delle imposte |
| Lettura, ricerca, domande | Incluse |
| Scansioni fallite | Rimborsate sul saldo |

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](https://spacecontext.app/it/developers/).

## Inizia con la demo

Il percorso più breve: [crea una chiave di test gratuita](https://spacecontext.app/developers/console/) 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).

## Domande frequenti

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

È ciò che manca agli agenti AI per parlare di un luogo: un documento strutturato che descrive uno spazio fisico (aree, oggetti e dove si trovano, condizioni, problemi, punti chiave, istruzioni, fatti) con i fotogrammi del video come prova. Space Context lo ricava da un video e lo rende leggibile da API, SDK, CLI e server MCP.

### Quali assistenti AI funzionano con il server MCP di Space Context?

Claude (claude.ai e Claude Desktop), Claude Code, ChatGPT, Codex, Cursor e VS Code, ognuno con i suoi passi nella documentazione, e qualsiasi client che supporta server MCP remoti con OAuth. Si aggiunge l'URL https://mcp.spacecontext.app/mcp, si accede nel browser e si sceglie cosa l'assistente può vedere.

### Cosa risponde l'agente se il video non mostra ciò che gli chiedo?

Che non è documentato. La risposta di POST /spaces/{id}/ask usa solo i record dello spazio e, quando non contengono la risposta, restituisce documented: false. La sezione coverage del documento elenca anche ciò che il video non ha mostrato.

### Quanto costa provare Space Context?

Le chiavi di test sono gratuite e lavorano sullo spazio dimostrativo. La prima scansione reale di un nuovo account è gratuita con una carta salvata (salvarla non addebita nulla), poi 1,00 $ a scansione da un saldo prepagato, al netto delle imposte. Lettura, ricerca e domande sono incluse.