注意

梦境处于研究预览阶段。

智能体在工作时会写入其记忆存储，但这些写入是局部且增量的：经过多次会话后，记忆存储会积累重复、矛盾和过时的条目。

Dreams（梦境）让 Claude 来清理这些内容。梦境会读取现有的记忆存储以及过去的会话记录，然后生成一个新的、重新组织的记忆存储：合并重复项，用最新值替换过时或相互矛盾的条目，并发现新的见解。

输入存储永远不会被修改，因此您可以审查输出，如果不满意结果可以将其丢弃。

工作原理

梦境是一个异步作业，它接收：

  • 一个预先存在的记忆存储： Claude 对其进行验证、去重和重新组织的存储，以及
  • 1 到 100 个会话： Claude 从中挖掘模式和见解并整合到输出中的过去记录。

梦境会生成另一个输出记忆存储，与输入存储分开。在梦境开始 running 后不久，一旦工作流克隆了输入存储，输出存储 ID 就会出现在梦境的 outputs (csharp, go: Outputs) 数组中；处于 running 状态的梦境可能会短暂报告一个空的 outputs (csharp, go: Outputs) 数组。

创建梦境

cURL

curl -s https://api.anthropic.com/v1/dreams \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21" \
  -H "content-type: application/json" \
  -d '{
    "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."
  }'

CLI

ant beta:dreams create <<YAML
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.
YAML

Python

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

TypeScript

let dream = await client.beta.dreams.create({
  inputs: [
    { type: "memory_store", memory_store_id: storeId },
    { type: "sessions", session_ids: [sessionA, sessionB] }
  ],
  model: "claude-opus-5-5",
  instructions: "Focus on coding-style preferences; ignore one-off debugging notes."
});
console.log(dream.id); // drm_01...

C#

var dream = await client.Beta.Dreams.Create(new()
{
    Inputs =
    [
        new BetaDreamMemoryStoreInput { MemoryStoreID = storeID },
        new BetaDreamSessionsInput { SessionIds = [sessionA, sessionB] },
    ],
    Model = "claude-opus-5-5",
    Instructions = "Focus on coding-style preferences; ignore one-off debugging notes.",
});
Console.WriteLine(dream.ID);  // drm_01...

Go

dream, err := client.Beta.Dreams.New(ctx, anthropic.BetaDreamNewParams{
	Inputs: []anthropic.BetaDreamInputUnionParam{
		anthropic.BetaDreamInputParamOfMemoryStore(storeID),
		anthropic.BetaDreamInputParamOfSessions([]string{sessionA, sessionB}),
	},
	Model: anthropic.BetaDreamNewParamsModelUnion{
		OfString: anthropic.String("claude-opus-5-5"),
	},
	Instructions: anthropic.String("Focus on coding-style preferences; ignore one-off debugging notes."),
})
if err != nil {
	panic(err)
}
fmt.Println(dream.ID) // drm_01...

Java

var dream = client.beta().dreams().create(
    DreamCreateParams.builder()
        .addMemoryStoreInput(storeId)
        .addSessionsInput(List.of(sessionA, sessionB))
        .model("claude-opus-5-5")
        .instructions("Focus on coding-style preferences; ignore one-off debugging notes.")
        .build()
);
IO.println(dream.id());  // drm_01...

PHP

$dream = $client->beta->dreams->create(
    inputs: [
        ['type' => 'memory_store', 'memory_store_id' => $storeId],
        ['type' => 'sessions', 'session_ids' => [$sessionA, $sessionB]],
    ],
    model: 'claude-opus-5-5',
    instructions: 'Focus on coding-style preferences; ignore one-off debugging notes.',
);
echo "{$dream->id}\n"; // drm_01...

Ruby

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."
)
puts dream.id # drm_01...

梦境的输入包括预先存在的记忆存储和一个会话数组。您选择的模型负责运行梦境管道。仅支持部分模型。您可以选择传入 instructions (csharp, go: Instructions) 来引导梦境过程。请参阅使用指令进行引导。

响应是完整的 dream 资源，其 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
}

提示

如果您只有会话记录而没有现有存储，请先创建一个空的记忆存储，并将其作为 memory_store 输入传入。

使用指令进行引导

可选的 instructions (csharp, go: Instructions) 字段用于引导梦境管道综合哪些内容。它在整个管道中都会生效：仔细阅读哪些内容、合并或丢弃哪些内容，以及如何组织输出存储的结构。

将 instructions (csharp, go: Instructions) 用于高层次的综合指导，例如重点领域（“专注于编码风格偏好”）、需要原样保留的内容，或您希望在整个存储中应用的输出约定。该管道是对输入进行的综合处理，而不是作用于存储文本的编辑器，因此针对特定行的命令式指令（“将句子 X 改为 Y”、“修正 Z 部分中的计数”）通常不会产生任何变化。如需对单个记忆进行针对性编辑，请直接对输出存储使用 Memory Stores API。

跟踪进度

梦境以异步方式运行，通常需要几分钟到几个小时，具体取决于输入记录的数量。按 ID 轮询梦境以检查状态：

cURL

curl -s "https://api.anthropic.com/v1/dreams/$dream_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21"

CLI

ant beta:dreams retrieve --dream-id "$dream_id"

Python

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}")

TypeScript

while (dream.status === "pending" || dream.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  dream = await client.beta.dreams.retrieve(dream.id);
  console.log(`status=${dream.status} input_tokens=${dream.usage.input_tokens}`);
}

C#

while (dream.Status.Value() is BetaDreamStatus.Pending or BetaDreamStatus.Running)
{
    await Task.Delay(TimeSpan.FromSeconds(10));
    dream = await client.Beta.Dreams.Retrieve(dream.ID);
    Console.WriteLine($"status={dream.Status.Raw()} input_tokens={dream.Usage.InputTokens}");
}

Go

for dream.Status == anthropic.BetaDreamStatusPending || dream.Status == anthropic.BetaDreamStatusRunning {
	time.Sleep(10 * time.Second)
	dream, err = client.Beta.Dreams.Get(ctx, dream.ID, anthropic.BetaDreamGetParams{})
	if err != nil {
		panic(err)
	}
	fmt.Printf("status=%s input_tokens=%d\n", dream.Status, dream.Usage.InputTokens)
}

Java

while (dream.status().equals(BetaDreamStatus.PENDING)
        || dream.status().equals(BetaDreamStatus.RUNNING)) {
    Thread.sleep(10_000);
    dream = client.beta().dreams().retrieve(dream.id());
    IO.println("status=" + dream.status() + " input_tokens=" + dream.usage().inputTokens());
}

PHP

while (in_array($dream->status, [BetaDreamStatus::PENDING->value, BetaDreamStatus::RUNNING->value], true)) {
    sleep(10);
    $dream = $client->beta->dreams->retrieve($dream->id);
    echo "status={$dream->status} input_tokens={$dream->usage->inputTokens}\n";
}

Ruby

while %i[pending running].include?(dream.status)
  sleep 10
  dream = client.beta.dreams.retrieve(dream.id)
  puts "status=#{dream.status} input_tokens=#{dream.usage.input_tokens}"
end

生命周期

status (csharp, go: Status) 含义
pending 梦境已成功创建并进入队列。
running 管道正在处理中。usage (csharp, go: Usage) 会随着工作进展而更新。
completed 已成功完成。outputs (csharp, go: Outputs) 的值即为新的记忆存储。
failed 梦境运行因错误而结束。输出记忆存储保持原样，包含失败前已写入的所有内容。
canceled 梦境运行已取消。输出记忆存储保持原样。

观察管道运行

一旦梦境处于 running 状态，其 session_id (java: sessionId; php: sessionID; csharp, go: SessionID) 字段就会指向运行该管道的底层会话。您可以对该会话的事件进行流式传输，以实时观察梦境正在读取和写入的内容。当梦境达到终止状态时，该会话会被归档（而不是删除），因此之后仍可查看其记录。

使用输出

当 status (csharp, go: Status) 达到 completed 时，outputs (csharp, go: Outputs) 中的 memory_store 条目会引用一个已完全填充的存储。它是您工作区中的一个普通记忆存储。使用 Memory Stores API 或在 Claude Console 中审查它，然后选择：

cURL

# $output_store_id 是已完成梦境的 memory_store 输出的 memory_store_id
curl -s https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "agent": "'"$agent_id"'",
    "environment_id": "'"$environment_id"'",
    "resources": [
      { "type": "memory_store", "memory_store_id": "'"$output_store_id"'" }
    ]
  }'

CLI

# $output_store_id 是已完成梦境的 memory_store 输出的 memory_store_id
ant beta:sessions create <<YAML
agent: $agent_id
environment_id: $environment_id
resources:
  - type: memory_store
    memory_store_id: $output_store_id
YAML

Python

# 梦境结束后，输出中保存着重建的记忆存储
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},
    ],
)

TypeScript

// dream 结束后，输出中保存着重建的内存存储
const output = dream.outputs.find((entry) => entry.type === "memory_store");
const outputStoreId = output!.memory_store_id;

await client.beta.sessions.create({
  agent: agentId,
  environment_id: environmentId,
  resources: [{ type: "memory_store", memory_store_id: outputStoreId }]
});

C#

var output = dream.Outputs.FirstOrDefault(entry => entry.Type.GetString() == "memory_store");
if (output is { MemoryStoreID: var outputStoreID })
{
    await client.Beta.Sessions.Create(new()
    {
        Agent = agentID,
        EnvironmentID = environmentID,
        Resources =
        [
            new BetaManagedAgentsMemoryStoreResourceParam { MemoryStoreID = outputStoreID },
        ],
    });
}

Go

for _, output := range dream.Outputs {
	if output.Type != "memory_store" {
		continue
	}
	outputStoreID := output.MemoryStoreID

	session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
		Agent: anthropic.BetaSessionNewParamsAgentUnion{
			OfString: anthropic.String(agentID),
		},
		EnvironmentID: environmentID,
		Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
			OfMemoryStore: &anthropic.BetaManagedAgentsMemoryStoreResourceParam{
				MemoryStoreID: outputStoreID,
			},
		}},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(session.ID)
	break
}

Java

var output = dream.outputs().stream()
    .filter(entry -> entry._type().equals(JsonValue.from("memory_store")))
    .findFirst();
if (output.isPresent()) {
    var outputStoreId = output.get().memoryStoreId();

    var session = client.beta().sessions().create(
        SessionCreateParams.builder()
            .agent(agentId)
            .environmentId(environmentId)
            .addMemoryStoreResource(outputStoreId)
            .build()
    );
}

PHP

$matches = array_filter($dream->outputs, fn($output) => $output->type === 'memory_store');
$output = $matches ? reset($matches) : null;
if ($output !== null) {
    $session = $client->beta->sessions->create(
        agent: $agentId,
        environmentID: $environmentId,
        resources: [
            ['type' => 'memory_store', 'memory_store_id' => $output->memoryStoreID],
        ],
    );
}

Ruby

output = dream.outputs.find { it.type == :memory_store }
if output
  client.beta.sessions.create(
    agent: agent_id,
    environment_id: environment_id,
    resources: [
      {type: "memory_store", memory_store_id: output.memory_store_id}
    ]
  )
end

梦境本身永远不会删除或修改其输入。在 failed 或 canceled 状态下，输出存储会保留部分内容，以便您检查停止前已生成的内容；如果不需要，请通过 Memory Stores API 将其清理。

警告

当梦境处于 pending 或 running 状态时，400 保护仅适用于归档梦境本身，而不适用于其存储。在运行期间归档或删除输入记忆存储（或删除输入会话）将导致梦境失败，并返回 input_memory_store_unavailable 或 input_session_unavailable。

取消梦境

取消操作会立即将 pending 或 running 状态的梦境转为 canceled。取消一个已处于 canceled 状态的梦境是幂等的空操作；取消 completed 或 failed 状态的梦境会返回 400。

注意

取消后，在进行中的工作逐渐结束期间，梦境的 usage (csharp, go: Usage) 字段可能会在几秒钟内继续更新。如果您需要最终计数，请轮询梦境直到 usage (csharp, go: Usage) 稳定下来。

cURL

curl -s -X POST "https://api.anthropic.com/v1/dreams/$dream_id/cancel" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21"

CLI

ant beta:dreams cancel --dream-id "$dream_id"

Python

client.beta.dreams.cancel(dream.id)

TypeScript

await client.beta.dreams.cancel(dream.id);

C#

await client.Beta.Dreams.Cancel(dream.ID);

Go

dream, err = client.Beta.Dreams.Cancel(ctx, dream.ID, anthropic.BetaDreamCancelParams{})
if err != nil {
	panic(err)
}

Java

client.beta().dreams().cancel(dream.id());

PHP

$client->beta->dreams->cancel($dream->id);

Ruby

client.beta.dreams.cancel(dream.id)

归档梦境

归档操作会在已达到终止状态（completed、failed 或 canceled）的梦境上设置 archived_at (java, php: archivedAt; csharp, go: ArchivedAt)；status (csharp, go: Status) 保持不变。已归档的梦境不会出现在默认的列表响应中，但仍可按 ID 读取。归档一个已归档的梦境是幂等的空操作。归档 pending 或 running 状态的梦境会返回 400；请先取消它。不支持取消归档。

cURL

curl -s -X POST "https://api.anthropic.com/v1/dreams/$dream_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21"

CLI

ant beta:dreams archive --dream-id "$dream_id"

Python

client.beta.dreams.archive(dream.id)

TypeScript

await client.beta.dreams.archive(dream.id);

C#

await client.Beta.Dreams.Archive(dream.ID);

Go

dream, err = client.Beta.Dreams.Archive(ctx, dream.ID, anthropic.BetaDreamArchiveParams{})
if err != nil {
	panic(err)
}

Java

client.beta().dreams().archive(dream.id());

PHP

$client->beta->dreams->archive($dream->id);

Ruby

client.beta.dreams.archive(dream.id)

归档梦境不会影响其输出记忆存储；请通过 Memory Stores API 单独管理该存储。

列出梦境

返回工作区中所有未归档的梦境，按最新优先排序。使用 limit (csharp, go: Limit)（默认 20，最大 100）和 page (csharp, go: Page) 游标进行分页。将 include_archived (java, php: includeArchived; csharp, go: IncludeArchived) 设置为 true 以包含已归档的梦境。

cURL

curl -s "https://api.anthropic.com/v1/dreams?limit=20" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21"

CLI

ant beta:dreams list --limit 20

Python

for listed_dream in client.beta.dreams.list(limit=20):
    print(listed_dream.id, listed_dream.status)

TypeScript

for await (const listedDream of client.beta.dreams.list({ limit: 20 })) {
  console.log(listedDream.id, listedDream.status);
}

C#

var page = await client.Beta.Dreams.List(new() { Limit = 20 });
await foreach (var listed in page.Paginate())
{
    Console.WriteLine($"{listed.ID} {listed.Status.Raw()}");
}

Go

dreams := client.Beta.Dreams.ListAutoPaging(ctx, anthropic.BetaDreamListParams{
	Limit: anthropic.Int(20),
})
for dreams.Next() {
	listed := dreams.Current()
	fmt.Println(listed.ID, listed.Status)
}
if err := dreams.Err(); err != nil {
	panic(err)
}

Java

for (var listedDream : client.beta().dreams().list(
    DreamListParams.builder()
        .limit(20)
        .build()
).autoPager()) {
    IO.println(listedDream.id() + " " + listedDream.status());
}

PHP

foreach ($client->beta->dreams->list(limit: 20)->pagingEachItem() as $dream) {
    echo "{$dream->id} {$dream->status}\n";
}

Ruby

client.beta.dreams.list(limit: 20).auto_paging_each do
  puts "#{it.id} #{it.status}"
end

错误

以下是可能出现的梦境错误的非详尽列表。

error.type 发生时机
timeout 管道超出了其运行时间预算。
internal_error 未分类的管道故障。
memory_store_org_limit_exceeded 在管道配置工作存储时，您的组织达到了记忆存储数量上限。
input_memory_store_too_large 输入记忆存储超出了管道的大小限制。
input_memory_store_unavailable 输入记忆存储在梦境创建后被归档或删除。
input_session_unavailable 某个输入会话在梦境创建后被删除。

计费

梦境按您所选模型的标准 API 令牌费率计费；资源上的 usage (csharp, go: Usage) 会报告确切的总量。成本大致随输入会话的数量和长度线性增长。建议先从一小批会话开始，在对整理质量满意后再扩大规模。

限制

在此功能处于研究预览期间，梦境创建适用默认的速率限制。如果您需要更高的限制，请联系支持团队。

可用性

梦境在部分模型上处于研究预览阶段。

API 支持

Managed Agents

  • 可用性：可用
状态 云平台 模型
研究预览 Claude API Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 4.6

所需的 beta 请求头

Beta 请求头概览

Beta 请求头让您可以在实验性功能和新模型能力成为标准 API 的一部分之前访问它们。

  • managed-agents-2026-04-01
  • dreaming-2026-04-21

梦境端点需要 dreaming-2026-04-21 beta 标头。仅凭 managed-agents-2026-04-01 标头无法访问梦境。会话调用使用 managed-agents-2026-04-01，记忆存储调用使用 agent-memory-2026-07-22。SDK 会为每个调用设置正确的标头。

数据处理

数据处理概览

项目 零数据保留 HIPAA
状态 不具备资格 不具备资格
详细信息 会话是有状态的资源；对话记录会一直保留，直到您将其删除。适用于所有 Managed Agents 子功能，包括自托管沙箱。 适用于所有 Managed Agents 子功能，包括自托管沙箱。

适用的端点：

  • /v1/agents
  • /v1/sessions
  • /v1/environments