桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载本文依据 Warp 开源仓库内置的 managed-agents-core.md 文档展开并辅以同一目录下的 overview、api-reference、events、tools、environments、client-patterns 等文档及多语言 SDK 示例进行深化。你将理解 Managed Agents 的四大核心对象Agent / Session / Environment / Container、Session 生命周期与内置能力、Agent 的版本化设计并掌握先建 Agent、每次运行建 Session的实战模式。Warp 内置的 Claude API Skill位于 resources/bundled/skills/claude-api向 Agent/LLM 提供了一份完整的 Claude Managed Agents 使用指南其中 managed-agents-core.md 是理解整套 API 的核心概念文档它定义了四大核心对象、Session 生命周期、Agent 版本化模型以及创建 Agent 与 Session 的完整参数表。本文以该文档为骨架结合仓库内同目录的系列文档overview、api-reference、events、tools、environments、client-patterns与 TypeScript/Python/cURL 多语言示例编写一份面向开发者与 LLM Agent 的深度实战指南。一、架构总览四个核心概念Managed Agents 围绕四个核心概念构建对应文档开头的架构表格概念Endpoint本质Agent/v1/agents持久化、带版本的对象定义 Agent 的能力与人格模型、系统提示词、工具、MCP 服务器、技能。必须在启动会话之前创建Session/v1/sessions与 Agent 的一次有状态交互。通过 ID 引用预先创建的 Agent 一个环境 初始指令产出事件流Environment/v1/environments定义容器预置配置的模板ContainerN/AAgent 的工具bash、文件操作、代码执行的隔离计算实例。Agent 循环不在这里运行——它运行在 Anthropic 编排层通过工具调用作用于容器文档给出了一张架构示意┌─────────────────────────────────────┐ │ Anthropic orchestration layer │ Agent (config) ───────▶│ (agent loop: Claude tool calls) │ └──────────────┬──────────────────────┘ │ tool calls ▼ Environment (template) ──▶ Container (tool execution workspace) │ Session ─┤ ├── Resources (files, repos — mounted at startup) ├── Vault IDs (MCP credential references) └── Conversation (event stream in/out)核心要点Agent 创建是前置条件。Session 通过 ID 引用预先创建的 Agent——model/system/tools存在于 Agent 对象上永远不在 Session 上。每个流程都从POST /v1/agents开始。这一点在 managed-agents-overview.md 中被进一步强化为强制流程步骤调用频率1POST /v1/agents——model、system、tools、mcp_servers、skills都在这里只做一次。保存agent.id和agent.version2POST /v1/sessions——agent: agent_abc123或{type: agent, id, version}每次运行都做。字符串简写使用最新版本⚠️ 如果你正要写一个带model、system或tools字段的sessions.create()——停下来。这些字段属于agents.create()。Session 只接受一个指针。二、Session 生命周期文档定义了四种状态rescheduling → running ↔ idle → terminated状态描述idleAgent 已完成当前任务正在等待输入。可能是等待user.message继续工作或是被阻塞等待user.custom_tool_result或user.tool_confirmation。附带的stop_reason包含 Agent 停止工作的更多信息runningSession 已开始运行Agent 正在积极工作rescheduling发生可重试错误后 Session 正在重新调度等待编排系统接管terminatedSession 已终止进入不可逆、不可用的状态关键行为规则事件发送时机Session 处于running或idle状态时都可以发送事件消息被排队并按顺序处理无需等待前一条消息的响应managed-agents-events.md 的消息排队一节专门强调这一点适合聊天桥接场景中的快速连续追问。状态迁移Agent 收到新事件时从idle → running完成后回到idle。错误呈现错误以session.error事件出现在事件流中不是一个状态值。内置会话特性文档列出的三个开箱即用能力Context compaction上下文压缩——接近上下文上限时API 自动压缩会话历史以维持交互。Prompt caching提示缓存——重复的历史 token 被缓存降低处理时间与成本。Extended thinking扩展思考——默认开启以agent.thinking事件返回。会话操作操作说明List / fetch分页列表或按 ID 获取单个资源Update仅title可更新ArchiveSession 变为只读。不可逆Delete永久删除 Session、事件历史、容器和检查点三、Session 对象与创建Session 对象字段API 返回的关键字段字段类型描述typestring恒为sessionidstring唯一 Session IDtitlestring人类可读标题statusstringidle、running、rescheduling、terminatedcreated_atstringISO 8601 时间戳updated_atstringISO 8601 时间戳archived_atstringISO 8601 时间戳可空environment_idstring环境 IDagentobjectAgent 配置resourcesarray附加的文件和仓库metadataobject用户提供的键值对最多 8 个键usageobjectToken 用量统计创建 Session先建 Agent再引用没有 Agent 的 Session 毫无意义。Session 通过 ID 引用预先创建的 Agent。先用agents.create()创建 Agent再引用它// 1. 创建 Agent可复用、带版本 const agent await client.beta.agents.create( { name: Coding Assistant, model: claude-opus-4-7, system: You are a helpful coding agent., tools: [{ type: agent_toolset_20260401}], }, ); // 2. 启动引用它的 Session const session await client.beta.sessions.create( { agent: agent.id, // 字符串简写 → 最新版本。或者{ type: agent, id: agent.id, version: agent.version } environment_id: environmentId, title: Hello World Session, }, );Session 创建参数字段类型必填描述agentstring 或 object是字符串简写agent_abc123最新版本或{type: agent, id, version}environment_idstring是环境 IDtitlestring否人类可读名称出现在日志/仪表盘中resourcesarray否文件或 GitHub 仓库启动时挂载到容器vault_idsarray否Vault IDvlt_*——MCP 凭据支持自动刷新。详见 managed-agents-tools.md 的 Vaults 一节metadataobject否用户提供的键值对Agent 配置字段传给agents.create()不是sessions.create()字段类型必填描述namestring是人类可读名称1-256 字符modelstring 或 object是Claude 模型 ID裸字符串或{id, speed}对象。支持所有 Claude 4.5 模型systemstring否系统提示词——定义 Agent 行为最多 100K 字符toolsarray否包含三类工具(1) 预构建 Claude Agent 工具agent_toolset_20260401、(2) MCP 工具mcp_toolset、(3) 自定义客户端工具。最多 128 个mcp_serversarray否MCP 服务器连接——标准化第三方能力如 GitHub、Asana。最多 20 个名称唯一skillsarray否自定义最佳实践上下文支持渐进式披露。最多 64 个descriptionstring否Agent 描述最多 2048 字符metadataobject否任意键值对最多 16 个键 ≤64 字符值 ≤512 字符模型简写补充来自 managed-agents-api-reference.mdmodel可传裸字符串claude-opus-4-7使用standard速度或完整配置对象{type: model_config, id: claude-opus-4-6, speed: fast}。注意speed: fast仅在 Opus 4.6 上受支持。四、Agent一切流程的起点每个 Managed Agents 流程都从这里开始。Agent 对象是持久化、带版本的配置——创建一次之后每次启动 Session 都用 ID 引用它。没有 Agent → 没有 Session。Agent 对象API 是扁平的——model、system、tools等都是顶层字段不会包装在agent:{}子对象中字段类型必填描述namestring是人类可读名称modelstring是Claude 模型 IDsystemstring否系统提示词toolsarray否Agent 工具集 / MCP 工具集 / 自定义工具mcp_serversarray否MCP 服务器连接skillsarray否技能引用最多 64 个descriptionstring否Agent 描述metadataobject否任意键值对生命周期创建一次运行多次就地更新Agent 是持久化资源不是每次运行的参数。预期模式┌─ setup (once) ─────────┐ ┌─ runtime (every invocation) ─┐ │ agents.create() │ │ sessions.create( │ │ → store agent_id │ ──→ │ agent{type:..., id: ID} │ │ in config/env/db │ │ ) │ └────────────────────────┘ └──────────────────────────────┘反模式在每次脚本运行的开头调用agents.create()。这会积累大量孤儿 Agent 对象、为每次调用支付创建延迟并破坏版本化模型。如果你在按请求或按 cron 触发调用的函数里看到agents.create()那就是错误的——把它提升到一次性设置中并持久化 ID。managed-agents-client-patterns.md 也给出了同样的建议正确形态是创建一次 → 持久化 ID配置文件、环境变量、密钥管理器→ 每次运行加载 ID 并调用sessions.create()如果用户代码每次调用都执行agents.create()他们在无意义地积累孤儿 Agent 并支付创建延迟。版本化机制每次POST /v1/agents/{id}更新都会创建新的不可变版本数值时间戳如1772585501101368014。Agent 的历史是只追加的——你无法编辑过去的版本。为什么需要版本化可复现性——把 Session 固定到已知良好的配置{type: agent, id, version: 3}安全迭代——更新 Agent 不会破坏已在旧版本上运行的 Session回滚——如果新系统提示词导致回退先把新 Session 固定回先前版本再调试version是可选的。省略它或使用字符串简写agentagent_abc123在创建 Session 时使用最新版本。显式传参{type: agent, id, version: N}则固定版本以保证可复现性。如何拿到要固定的版本agents.create()和agents.update()都会在响应中返回version。把它和agent_id一起存储。获取现有 Agent 的当前最新版本GET /v1/agents/{id}→.version。何时更新 vs 新建当它概念上还是同一个 Agent、只是行为微调更好的提示词、新增工具时用更新POST /v1/agents/{id}。当它是不同的人格/用途时新建 Agent。经验法则如果你会给它相同的name就更新。Agent 端点操作方法路径创建POST/v1/agents列表GET/v1/agents获取GET/v1/agents/{id}更新POST/v1/agents/{id}归档POST/v1/agents/{id}/archive⚠️归档是永久性的。归档使 Agent 变为只读现有 Session 继续运行但新 Session 不能再引用它且没有取消归档操作。由于 Agent 没有delete这是终态生命周期。永远不要把归档生产环境 Agent 当作例行清理——先与用户确认。命名怪癖来自 managed-agents-api-reference.mdAgent 没有delete只有archive。而 Environments、Sessions、Vaults、Credentials 同时有delete和archiveSession Resources、Files、Skills 则只有delete。此外 Go SDK 的事件流方法名是StreamEvents不是Stream。在 Session 中使用 Agent通过字符串 ID最新版本或带显式版本的对象引用 Agent# 字符串简写 —— 使用 Agent 的最新版本 session client.beta.sessions.create( agentagent.id, environment_idenvironment_id, ) # 或固定到特定版本int session client.beta.sessions.create( agent{type: agent, id: agent.id, version: agent.version}, environment_idenvironment_id, )五、从核心概念到完整实现一次端到端实战理解核心对象后结合 managed-agents-client-patterns.md、managed-agents-events.md 与各语言 README可以组装出完整的驱动流程。环境Environment先行Session 创建需要一个environment_id。环境是可复用的容器配置模板——可以为不同用例创建不同环境如数据可视化 vs Web 开发配不同软件包。环境名称必须唯一重名创建返回 409。网络策略有两种unrestricted完全出网除法律封禁清单与package_managers_and_custom包管理器 自定义allowed_hosts。const env await client.beta.environments.create({ name: my_env, config: { type: cloud, networking: { type: unrestricted }, }, });MCP 注意如果使用受限网络务必把 MCP 服务器域名加入allowed_hosts否则容器无法到达它们、工具会静默失败。打开流优先于发送事件永远先打开事件流再发送启动事件。流只投递打开之后发生的事件——它不重放当前状态或历史事件。如果先发消息再开流早期事件包括快速的状态转换会以单个缓冲批次到达你就失去了实时响应的能力。// ✅ 正确 —— 流与发送并发 const [response] await Promise.all([ streamEvents(sessionId), // 打开 SSE 连接 sendMessage(sessionId, text), ]); // ❌ 错误 —— 流打开前的事件以单个缓冲批次到达 await sendMessage(sessionId, text); const response await streamEvents(sessionId);流是长连接 SSE服务器周期性发送心跳保活轮询GET /v1/sessions/{id}/events则是普通的分页 GET立即返回。正确的空闲-退出判定Pattern 5不要仅凭session.status_idle就退出循环。Session 会短暂进入 idle——例如并行工具执行之间、等待user.tool_confirmation或user.custom_tool_result时。只有当 idle 伴随终止性stop_reason时才退出或直接退出于session.status_terminated。for await (const event of stream) { handle(event) if (event.type session.status_terminated) break if (event.type session.status_idle) { if (event.stop_reason.type requires_action) continue // 在等你——处理它 break // end_turn 或 retries_exhausted —— 两者都是终止性的 } }session.status_idle上stop_reason.type的三个取值requires_action—— Agent 在等待客户端事件工具确认、自定义工具结果。处理它不要退出。retries_exhausted—— 终止性失败。退出然后用sessions.retrieve()检查错误状态。end_turn—— 正常完成。丢流后的无损重连Pattern 1SSE 流没有重放。如果连接中途断开httpx 读超时、网络抖动重连后只会收到重连之后发出的事件间隙期的事件会从流中丢失。解决方案每次重连接时先用events.list()抓取完整事件历史再消费实时流并按事件 ID 去重——让历史先产出流追赶时以event.id去重managed-agents-events.md 给出了等价的 Python 实现。⚠️不要信任 HTTP 库超时作为墙钟上限requests的timeout(c, r)和httpx.Timeout(n)是每块读超时每收到一个字节就重置涓流连接可能无限阻塞。需要硬截止时间时在循环层面用time.monotonic()计时并显式退出。优先使用 SDK 的sessions.events.stream()/sessions.events.list()而不是手写 HTTP。工具确认往返Pattern 4当 Agent 配置了permission_policy: { type: always_ask }时任何对该工具的调用都会触发带evaluated_permission ask的agent.tool_use事件Session 进入 idle 等待决策。用user.tool_confirmation响应for await (const event of stream) { if (event.type agent.tool_use event.evaluated_permission ask) { await client.beta.sessions.events.send(session.id, { events: [{ type: user.tool_confirmation, tool_use_id: event.id, // 不是 toolu_ ID —— 用 event.id result: allow, // 或 deny // deny_message: ..., // 可选仅与 result: deny 一起使用 }], }) } }要点tool_use_id是event.id通常是sevt_...不是toolu_...IDresult是allow | deny可用deny_message告诉模型你拒绝的原因有多个待决工具时对每个evaluated_permission ask的agent.tool_use事件响应一次。非 MCP 密钥通过自定义工具留在宿主机侧Pattern 9Session 容器内目前无法设置环境变量vault 也只存放 MCP 凭据、不会暴露给容器 shell。如果 Agent 需要调用第三方 API 或运行需要密钥的 CLI正确做法是在 Agent 上声明自定义工具当 Agent 发出agent.custom_tool_use时由你的编排进程读取 SSE 流的进程用自己持有的凭据执行调用并以user.custom_tool_result回应。容器永远看不到密钥且这不暴露任何公共端点——整个往返都在你已持有的、带 API 密钥的 SSE 流上进行。不要把 API 密钥塞进系统提示词或用户消息作为变通——提示词和消息会持久保存在 Session 的事件历史中能被events.list()读取、会被包含进压缩摘要。会话管理收尾Post-idle 状态写竞态Pattern 6SSE 流发出session.status_idle的时间略早于 Session 可查询状态的实际更新。客户端如果一看到 idle 就立即调用sessions.delete()或sessions.archive()会间歇性收到 400 cannot delete/archive while running。清理前先轮询确认let s for (let i 0; i 10; i) { s await client.beta.sessions.retrieve(session.id) if (s.status ! running) break await new Promise(r setTimeout(r, 200)) } if (s?.status ! running) { await client.beta.sessions.archive(session.id) } // else: 2 秒后仍在 running —— 不要归档让它 settle 或升级处理归档Session是例行清理Session 每次运行、用完即弃但不要把这一做法推广到 Agent 或 Environment——它们是持久化、可复用的资源归档即永久无取消归档新 Session 不能引用。本仓库的完整事件类型参考、Beta 请求头、限流与错误处理细节可进一步阅读 managed-agents-events.md、managed-agents-api-reference.md并对照 typescript/managed-agents/README.md、python/managed-agents/README.md 与 curl/managed-agents.md 获取各语言等价示例。赞分享桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载相关推荐Warp 内置 Claude API 技能解读Managed Agents 环境与资源实战指南Warp 内置 Claude API 技能解读Managed Agents 环境与资源实战指南 本文深入解析 Warp 开源仓库内置的 Claude API桌面应用开发者工具人工智能AI 应用AI Agent代码智能体Warp 内置 Claude API Skill 解读Managed Agents 会话事件系统与 Steering 实战指南Warp 内置 Claude API Skill 解读Managed Agents 会话事件系统与 Steering 实战指南 导读 本指南以 Warp 开源桌面应用开发者工具人工智能AI 应用AI Agent代码智能体Warp 内置 Claude API 技能Claude 模型目录与 Models API 实战指南Warp 内置 Claude API 技能Claude 模型目录与 Models API 实战指南 导读 本文以 Warp 仓库内置的 claude api桌面应用开发者工具人工智能AI 应用AI Agent代码智能体创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考