Claude Platform Docs
Managed AgentsCreare una memoria persistente

Dreams

Consenti a Claude di rivedere le sessioni passate per curare la memoria di un agente e far emergere nuove intuizioni.

Dreams sono funzionalità in anteprima di ricerca

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

statusSignificato
pendingDream creato correttamente e messo in coda.
runningLa pipeline è in elaborazione. usage si aggiorna man mano che il lavoro procede.
completedTerminato correttamente. Il valore outputs è il nuovo archivio di memoria.
failedL’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.
canceledEsecuzione 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_store al 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.typeQuando
timeoutLa pipeline ha superato il proprio budget di tempo di esecuzione.
internal_errorErrore della pipeline non classificato.
memory_store_org_limit_exceededLa tua organizzazione ha raggiunto il limite di archivi di memoria mentre la pipeline stava predisponendo lo storage di lavoro.
input_memory_store_too_largeL’archivio di memoria di input supera il limite di dimensione della pipeline.
input_memory_store_unavailableL’archivio di memoria di input è stato archiviato o eliminato dopo la creazione del dream.
input_session_unavailableUna 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à

Dreams
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.

Endpoint applicabili

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Conservazione zero dei datiNon idoneo

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ù

HIPAANon idoneo

Non idoneo per HIPAA. Si applica a tutte le sotto-funzionalità di Managed Agents.

Questa pagina ti è stata utile?