开始会话

构建将工作委托给代理

启动会话

创建会话以运行您的代理并开始执行任务。

会话是环境中运行的代理实例。每个会话引用一个代理和一个环境（两者都是单独创建的），并在多次交互中维护对话历史。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置 beta 标头。

创建会话

会话需要一个 agent ID 和一个 environment ID。代理是版本化资源；将 agent ID 作为字符串传入会使用最新代理版本启动会话。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

要将会话固定到特定的代理版本，请传入一个对象。这样您可以精确控制运行的版本并独立地分阶段推出新版本。

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

代理定义了 Claude 在会话中的行为方式，包括模型、系统提示、工具和 MCP 服务器。有关详细信息，请参阅代理设置。

通过保险库进行 MCP 身份验证

如果您的代理使用需要身份验证的 MCP 工具，请在会话创建时传入 vault_ids 以引用包含存储的 OAuth 凭证的保险库。Anthropic 代表您管理令牌刷新。有关如何创建保险库和注册凭证的信息，请参阅使用保险库进行身份验证。

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

启动会话

创建会话会配置环境和代理，但不会启动任何工作。要委派任务，请使用用户事件向会话发送事件。会话充当状态机，跟踪进度，而事件驱动实际执行。

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

有关如何流式传输代理的响应和处理工具确认的信息，请参阅事件和流式传输。

会话状态

会话经历这些状态：

状态	描述
`idle`	代理等待输入，包括用户消息或工具确认。会话以 `idle` 开始。
`running`	代理正在主动执行
`rescheduling`	发生瞬时错误，自动重试
`terminated`	会话因不可恢复的错误而结束

其他会话操作

检索会话

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

列出会话

for session in client.beta.sessions.list():
    print(f"{session.id}: {session.status}")

归档会话

归档会话以防止发送新事件，同时保留其历史记录：

client.beta.sessions.archive(session.id)

删除会话

删除会话以永久移除其记录、事件和关联的容器。running 会话无法删除；如果需要立即删除，请发送中断事件。

文件、内存存储、环境和代理是独立资源，不受会话删除的影响。

client.beta.sessions.delete(session.id)

Was this page helpful?

构建将工作委托给代理

启动会话

创建会话以运行您的代理并开始执行任务。

会话是环境中运行的代理实例。每个会话引用一个代理和一个环境（两者都是单独创建的），并在多次交互中维护对话历史。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置 beta 标头。

创建会话

会话需要一个 agent ID 和一个 environment ID。代理是版本化资源；将 agent ID 作为字符串传入会使用最新代理版本启动会话。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

要将会话固定到特定的代理版本，请传入一个对象。这样您可以精确控制运行的版本并独立地分阶段推出新版本。

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

代理定义了 Claude 在会话中的行为方式，包括模型、系统提示、工具和 MCP 服务器。有关详细信息，请参阅代理设置。

通过保险库进行 MCP 身份验证

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

启动会话

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

有关如何流式传输代理的响应和处理工具确认的信息，请参阅事件和流式传输。

会话状态

会话经历这些状态：

状态	描述
`idle`	代理等待输入，包括用户消息或工具确认。会话以 `idle` 开始。
`running`	代理正在主动执行
`rescheduling`	发生瞬时错误，自动重试
`terminated`	会话因不可恢复的错误而结束

其他会话操作

检索会话

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

列出会话

for session in client.beta.sessions.list():
    print(f"{session.id}: {session.status}")

归档会话

归档会话以防止发送新事件，同时保留其历史记录：

client.beta.sessions.archive(session.id)

删除会话

删除会话以永久移除其记录、事件和关联的容器。running 会话无法删除；如果需要立即删除，请发送中断事件。

文件、内存存储、环境和代理是独立资源，不受会话删除的影响。

client.beta.sessions.delete(session.id)

Was this page helpful?