Dreams
Consenti a Claude di rivedere le sessioni passate per curare la memoria di un agente e far emergere nuove intuizioni.
Gli agenti scrivono nei loro memory store (archivi di memoria) mentre lavorano, ma queste scritture sono locali e incrementali: nel corso di molte sessioni un archivio di memoria accumula duplicati, contraddizioni e voci obsolete.
I Dreams (sogni) permettono a Claude di fare pulizia. Un dream legge un archivio di memoria esistente insieme alle trascrizioni delle sessioni passate, quindi produce un nuovo archivio di memoria riorganizzato: duplicati uniti, voci obsolete o contraddette sostituite con il valore più recente e nuove intuizioni fatte emergere.
L’archivio di input non viene mai modificato, quindi puoi esaminare l’output e scartarlo se il risultato non ti soddisfa.
Come funziona
Un dream è un job asincrono che riceve:
- un archivio di memoria preesistente: l’archivio che Claude verifica, deduplica e riorganizza, e
- da 1 a 100 sessioni: trascrizioni passate che Claude analizza alla ricerca di pattern e intuizioni da incorporare nell’output.
Il dream produce un altro archivio di memoria di output, separato da quello di input. L’ID dell’archivio di output compare nell’array outputs del dream poco dopo che il dream passa allo stato running, una volta che il workflow ha clonato l’archivio di input; un dream in stato running può riportare brevemente un array outputs vuoto.
Crea un dream
dream = client.beta.dreams.create(
inputs=[
{"type": "memory_store", "memory_store_id": store_id},
{"type": "sessions", "session_ids": [session_a, session_b]},
],
model="claude-opus-5-5",
instructions="Focus on coding-style preferences; ignore one-off debugging notes.",
)
print(dream.id) # drm_01...Gli input del dreaming includono l’archivio di memoria preesistente e un array di sessioni. Il modello che scegli esegue la pipeline di dreaming. Sono supportati solo alcuni modelli. Facoltativamente puoi passare instructions per orientare il processo di dreaming. Consulta Orienta con le istruzioni.
La risposta è la risorsa dream completa con status: "pending":
{
"type": "dream",
"id": "drm_01AbCDefGhIjKlMnOpQrStUv",
"status": "pending",
"inputs": [
{ "type": "memory_store", "memory_store_id": "memstore_01Hx..." },
{ "type": "sessions", "session_ids": ["sesn_01...", "sesn_02..."] }
],
"outputs": [],
"model": { "id": "claude-opus-5-5" },
"instructions": "Focus on coding-style preferences; ignore one-off debugging notes.",
"session_id": null,
"created_at": "2026-04-29T17:04:10Z",
"ended_at": null,
"archived_at": null,
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
},
"error": null
}Orienta con le istruzioni
Il campo facoltativo instructions orienta ciò che la pipeline di dreaming sintetizza. Viene applicato in tutta la pipeline: cosa leggere con attenzione, cosa unire o scartare e come strutturare l’archivio di output.
Usa instructions per indicazioni di sintesi di alto livello, come aree di interesse (“concentrati sulle preferenze di stile di programmazione”), contenuti da preservare invariati o convenzioni di output che vuoi applicare a tutto l’archivio. La pipeline è un passaggio di sintesi sugli input, non un editor applicato al testo dell’archivio, quindi le direttive imperative che mirano a righe specifiche (“cambia la frase X in Y”, “correggi il conteggio nella sezione Z”) in genere non producono alcuna modifica. Per apportare modifiche mirate a singole memorie, usa direttamente l’API Memory Stores sull’archivio di output.
Monitora l’avanzamento
I dream vengono eseguiti in modo asincrono e richiedono in genere da alcuni minuti a qualche ora, a seconda del numero di trascrizioni di input. Interroga il dream tramite ID per verificarne lo stato:
while dream.status in ("pending", "running"):
time.sleep(10)
dream = client.beta.dreams.retrieve(dream.id)
print(f"status={dream.status} input_tokens={dream.usage.input_tokens}")Ciclo di vita
status | Significato |
|---|---|
pending | Dream creato correttamente e messo in coda. |
running | La pipeline è in elaborazione. usage si aggiorna man mano che il lavoro procede. |
completed | Terminato correttamente. Il valore outputs è il nuovo archivio di memoria. |
failed | L’esecuzione del dreaming è terminata con un errore. L’archivio di memoria di output viene lasciato così com’è, con quanto era stato scritto prima dell’errore. |
canceled | Esecuzione del dreaming annullata. L’archivio di memoria di output viene lasciato così com’è. |
Osserva l’esecuzione della pipeline
Quando un dream è in stato running, il suo campo session_id punta alla sessione sottostante che esegue la pipeline. Puoi ricevere in streaming gli eventi di quella sessione per osservare in tempo reale cosa il dream sta leggendo e scrivendo. La sessione viene archiviata (non eliminata) quando il dream raggiunge uno stato terminale, quindi la trascrizione rimane disponibile anche in seguito.
Usa l’output
Quando status raggiunge completed, la voce memory_store in outputs fa riferimento a un archivio completamente popolato. È un normale archivio di memoria nel tuo workspace. Esaminalo con l’API Memory Stores o nella Claude Console, quindi:
- Usalo: collegalo alle sessioni future come risorsa
memory_storeal posto dell’archivio di memoria di input (o insieme a esso), oppure - Scartalo: elimina l’archivio di memoriaAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) o archivia l’archivio di memoriaAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro).
# Al termine del dream, l'output contiene l'archivio di memoria ricostruito
output_store_id = next(
output.memory_store_id for output in dream.outputs if output.type == "memory_store"
)
session = client.beta.sessions.create(
agent=agent_id,
environment_id=environment_id,
resources=[
{"type": "memory_store", "memory_store_id": output_store_id},
],
)Il dream in sé non elimina né modifica mai i propri input. In caso di failed o canceled l’archivio di output persiste con contenuti parziali, così puoi ispezionare ciò che è stato prodotto prima dell’interruzione; ripuliscilo tramite l’API Memory Stores se non ti serve.
Annulla un dream
L’annullamento porta immediatamente un dream pending o running allo stato canceled. Annullare un dream già canceled è un’operazione idempotente senza effetti; annullare un dream completed o failed restituisce 400.
client.beta.dreams.cancel(dream.id)Archivia un dream
L’archiviazione imposta archived_at su un dream che ha raggiunto uno stato terminale (completed, failed o canceled); status rimane invariato. I dream archiviati sono esclusi dalle risposte di elenco predefinite, ma restano leggibili tramite ID. Archiviare un dream già archiviato è un’operazione idempotente senza effetti. Archiviare un dream in stato pending o running restituisce 400; annullalo prima. Non è possibile annullare l’archiviazione.
client.beta.dreams.archive(dream.id)L’archiviazione di un dream non tocca il suo archivio di memoria di output; gestiscilo separatamente tramite l’API Memory Stores.
Elenca i dream
Restituisce tutti i dream non archiviati nel workspace, dal più recente. Usa limit (predefinito 20, massimo 100) e il cursore page per la paginazione. Imposta include_archived su true per includere i dream archiviati.
for listed_dream in client.beta.dreams.list(limit=20):
print(listed_dream.id, listed_dream.status)Errori
Segue un elenco non esaustivo dei possibili errori del dreaming.
error.type | Quando |
|---|---|
timeout | La pipeline ha superato il proprio budget di tempo di esecuzione. |
internal_error | Errore della pipeline non classificato. |
memory_store_org_limit_exceeded | La tua organizzazione ha raggiunto il limite di archivi di memoria mentre la pipeline stava predisponendo lo storage di lavoro. |
input_memory_store_too_large | L’archivio di memoria di input supera il limite di dimensione della pipeline. |
input_memory_store_unavailable | L’archivio di memoria di input è stato archiviato o eliminato dopo la creazione del dream. |
input_session_unavailable | Una sessione di input è stata eliminata dopo la creazione del dream. |
Fatturazione
I dream vengono fatturati alle tariffe standard per token dell’API per il modello selezionato; usage sulla risorsa riporta i totali esatti. Il costo cresce in modo approssimativamente lineare con il numero e la lunghezza delle sessioni di input. Inizia con un piccolo gruppo di sessioni e aumenta una volta soddisfatto della qualità della curatela.
Limiti
Alla creazione dei dream si applicano i limiti di velocità predefiniti mentre questa funzionalità è in anteprima di ricerca. Contatta il supporto se hai bisogno di limiti più elevati.
Disponibilità
Claude API
- Stato
- Anteprima di ricerca
- API
- Managed Agents
- Header beta
- Richiede e
- Modelli
- Claude Fable 5.2, Fable 5.1, Fable 5
- Claude Opus 5.5, Opus 5, Opus 4.8, Opus 4.7
- Claude Sonnet 5.5, Sonnet 5, Sonnet 4.6
Gli endpoint dei dream richiedono l’header beta dreaming-2026-04-21. L’header managed-agents-2026-04-01 da solo non concede l’accesso ai dream. Le chiamate alle sessioni usano managed-agents-2026-04-01 e le chiamate agli archivi di memoria usano agent-memory-2026-07-22. L’SDK imposta l’header corretto in ogni chiamata.
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/agents/v1/sessions/v1/environments
Non idoneo per ZDR, ad eccezione di Managed Agents self-hosted. Le sessioni sono risorse con stato; le trascrizioni restano finché non le elimini. Scopri di più
Non idoneo per HIPAA. Si applica a tutte le sotto-funzionalità di Managed Agents.
Questa pagina ti è stata utile?